> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 | Release Type | Key Changes |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [v1.32.0](#v1-32-0) | 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) | 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) | 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) | 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) | 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) | 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) | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 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) | 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) | 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) | 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) | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | Minor Release | Download Signing Request endpoint |
| v1.15.3 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 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.32.0
**Release type:** Minor Release
[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
[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
[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 `![]()
`. 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
[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
[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
[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
[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
[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
[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
[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
[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
[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
[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
[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
[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/{id}** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/{id}** 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
[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
### 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
### 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/{id}/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](/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
}
}
```
**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](/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": "Hi {{signer_name}},
Please sign using this link: {{signing_link}}
"
}
```
#### 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` |
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](/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` |
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](/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](/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](/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](/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](/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](/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](/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](/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