Firma.dev API v1.3 + v1.4: New Field Types, Custom Email Domains, and Granular Control

We shipped two API releases back-to-back, just in the last week. Nothing breaking, but new features … all in February 2026. 👊

Version 1.3 landed with custom email domains and credit cost tracking. Version 1.4 followed with three new field types and granular PATCH operations for individual fields.

Both releases share the same theme: more control without more complexity. And neither introduces breaking changes, so you can adopt these features at your own pace.

If you're searching for an api signature solution that gives you flexibility without forcing migrations, this is what that looks like.

Here's everything new in v1.3 and v1.4.

v1.4.0: New Field Types and Granular Updates

Release Date: January 31, 2026

Version 1.4 expands what you can do with document fields and how you update them. Three new field types give you more options for collecting data. PATCH operations now support individual field updates. And a new template_user_id parameter makes recipient matching explicit.

Three New Field Types

The field type enum now includes textarea, url, and radio_buttons:

The radio type still works for backward compatibility, but radio_buttons is the canonical name going forward.

The url Field types

The new url field type lets you embed clickable links directly in your signing documents. The field is automatically set to read_only: true since signers click the link rather than edit it.

Use read_only_value to set the target URL and format_rules.urlDisplayText to customize what signers see:

{
  "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" }
  }
}

{
  "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" }
  }
}

{
  "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" }
  }
}

Use case: Embedded terms and policies. If your signing flow requires signers to acknowledge terms of service, privacy policies, or external contracts, the url field type keeps everything in one document. Signers click the link, review the referenced content, and continue signing. No need to attach multiple PDFs or redirect signers to external pages before they can complete the workflow.

This is especially useful for SaaS platforms where terms change frequently. Update the linked URL once, and every new signing request points to the current version.

The textarea Field Type

The textarea field type supports multi-line text input. Use it when you need signers to provide longer responses: special instructions, delivery notes, or any free-form text that won't fit in a single-line text field.

PATCH Operations for Individual Fields

Previously, updating a single field on a template meant sending the full template payload or using the comprehensive PUT endpoint. Now both Template and Signing Request PATCH endpoints support single-field operations.

Template PATCH (PATCH /templates/{id}) can update:

• Template properties

• A single user

• A single field (new in v1.4)

Signing Request PATCH (PATCH /signing-requests/{id}) can update:

• Signing request properties

• A single recipient

• A single field (new in v1.4)

To create a new field, include the field object without an id:

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

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

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

To update an existing field, include the field.id:

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

This granular approach simplifies field management when you need to adjust a single field position, change a field's required status, or add a new field without reconstructing the entire template payload.

Template User Matching with template_user_id

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

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

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

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

Before v1.4, recipient matching relied on the order property. That still works as a fallback, buttemplate_user_id removes ambiguity. If your template has multiple signers and you want to guarantee that Jane gets the "Buyer" role (not the "Seller" role), explicit matching ensures the right person gets the right fields.

v1.4 Schema Changes

Field type enum updated from:

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

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

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

To:

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

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

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

Recipient schema now includes template_user_id for explicit template user matching when creating signing requests.

v1.3.0: Custom Email Domains and Usage Visibility

Version 1.3 introduced the Email Domains API for white-label email sending, credit cost tracking for usage visibility, and declined status handling for signing requests.

Email Domains API

A complete API category for configuring custom email domains. Instead of signing request emails coming from noreply@firma.dev, they can come from signing@yourbrand.com.

Eight new endpoints:

New schemas:

• Domain: Email domain configuration with verification status

• DomainDnsRecord: DNS record details for domain verification

The verification flow works like most email domain setups: add your domain, verify ownership with a TXT record, configure SPF/DKIM/DMARC, finalize with the email provider, and set your primary sending domain.

Use case: White-label signing emails. If you're building an electronic signature API integration for your SaaS product, your customers expect emails to come from your brand. A signing request email from contracts@yourplatform.com builds trust. An email from noreply@firma.dev raises questions.

Custom email domains pair well with Customer Workspaces for full white-label deployments. Each of your customers gets an isolated workspace with templates and signing requests that never reference Firma.dev in the signer experience.

For a deeper look at white-labeling options, see our guides on white-label document signature API and white-label e-signature emails.

Credit Cost Tracking

Two new fields provide visibility into credit usage:

• credit_cost on Template schema: Number of credits consumed when sending a signing request from this template

• credit_cost on SigningRequest schema: Credits consumed when this signing request was sent

A new workspace setting, show_credit_cost_in_editor, lets you toggle whether credit costs display in the embedded template and signing editors.

This matters for SaaS platforms that pass costs through to customers or need to track usage per workspace. With credit cost visible at the template and signing request level, you can build billing dashboards, set usage alerts, or show customers their consumption without querying separate analytics endpoints.

At $0.029 per envelope, costs stay predictable. But visibility into where those credits go helps you optimize.

Signing Request Declined Status

Signing requests now support a declined status:

• Added declined to SigningRequest.status enum values

• Added date_declined field to SigningRequest schema

When a signer declines to sign, you'll see it reflected in the status and timestamp. This complements the declined_on and decline_reason fields on SigningRequestUser that shipped in v1.2.

v1.3 Schema Improvements

Template fields:

• Added date_default field for setting default date values (ISO 8601 format)

• Enhanced multi_group_id description to explain mutually exclusive field grouping for checkboxes and radio buttons

• Clarified that page_number is 1-indexed and must not exceed the document page count

Signing request fields:

• Same multi_group_id improvements as template fields

Migration Notes

Neither v1.3 nor v1.4 introduces breaking changes.

Migrating from v1.2 to v1.3:

• Email domain configuration is available but optional

• declined status added to signing request status enum

• Credit cost tracking available on templates and signing requests

Migrating from v1.3 to v1.4:

• radio field type renamed to radio_buttons (both accepted for backward compatibility)

• New PATCH capabilities for granular field updates

• template_user_id available for explicit recipient matching

You can adopt these features incrementally. Existing integrations continue to work without modification.

Build Your Electronic Signature API Integration

irma.dev is built for developers who need to add document signing to their products without the overhead of enterprise contracts or complex integrations. Pay-as-you-go pricing at $0.029 per envelope. No minimums. No contracts.

These releases reflect what we hear from customers: more field flexibility, better white-labeling, and granular control over templates and signing requests.

Check the full API changelog for version history and migration guides. Or start building now.

Get started with Firma.dev for free—no credit card required.