Firma.dev API v1.10.0: Conditional Fields, DOCX Support, Audit Trail, and More

Firma.dev API v1.10.0 is live. This is the most feature-dense release to date, shipping five additive features with zero breaking changes. If you're on v1.9.0, your existing integration works without modification. Everything here is new capability, not migration work.

Here's what's in the box.

What's in v1.10.0

All five features are additive. New fields default to null or false. No schema removals, no behavior changes.

Conditional field logic

This is the headline feature. Fields can now have dynamic required_conditions and visibility_conditions that evaluate based on other field values at signing time. Instead of building conditional form logic in your own UI, you define the rules once in the API and Firma.dev handles evaluation on both the client and server side.

The structure is composable. A ConditionSet contains one or more ConditionGroup objects, and each group contains individual Condition objects. The logic operator at the set level (and or or) controls how groups relate to each other, while conditions within a group use the opposite operator.

Ten comparison operators are available: is_filled, is_empty, equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal, and less_than_or_equal.

Here's a practical example. Say you have an employment contract where a spouse name field should only appear when the signer checks a "Married" checkbox:

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

When the checkbox is unchecked, the spouse name field stays hidden and skips validation entirely. When checked, it appears and can be set as required through a separate required_conditions rule using the same structure.

A few use cases this unlocks directly:

• Conditional disclosure fields that appear only when a signer selects a specific option

• Dependent approval sections where additional sign-off fields surface based on a dollar amount or risk level

• Progressive forms that adapt as the signer fills in information, keeping the initial view clean

The key detail for compliance-sensitive integrations: conditions are enforced server-side on submission. A signer can't bypass visibility or required rules through client-side tampering. If a field should be required based on another field's value, Firma.dev validates that server-side before accepting the signed document.

DOCX document support

All document upload endpoints now accept .docx files alongside PDF. When you upload a Word document, Firma.dev converts it to PDF server-side automatically. No client-side preprocessing, no extra dependencies in your pipeline.

This applies to template creation, template document replacement, signing request creation, and all PUT/PATCH update operations.

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

Existing PDF integrations are completley unaffected. If you're already uploading PDFs, nothing changes. This just removes the conversion step for teams that author documents in Word.

Audit trail endpoint

A new GET /signing-requests/{id}/audit endpoint returns the complete chronological event log for any signing request. It combines both admin actions (created, edited, sent, cancelled) and signer actions (viewed, signed, declined, downloaded) into a single timeline.

Each event includes a timestamp, source (admin or signer), event type, actor identity, IP address (for signer events), and event-specific metadata.

This endpoint covers the most common compliance ask: producing an evidence package that shows exactly who did what, when, and from where. Whether you need it for internal audit logs, regulatory reporting, or customer-facing activity feeds, the data is all in one call.

For the full response schema and endpoint details, see the audit trail API reference.

Signature frame control

By default, completed PDFs include a visual border around each signature with a Signature ID. The new show_signature_frame setting lets you control this at three levels with a clean inheritance chain:

1. Company sets the default (enabled by default)

2. Workspace overrides Company (null inherits)

3. Signing Request overrides Workspace (null inherits)

To disable the frame at workspace level:

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

The primary use case here is white-labeling. If you're embedding Firma.dev into your own product and want clean signatures without any Firma.dev framing on the final document, set this to false at the workspace level and every signing request in that workspace inherits it. Conversly, regulated industries that require visible signature identifiers can explicitly keep it enabled.

Force remove conditions on user deletion

This one is a developer ergonomics improvement. When you delete a recipient whose fields are referenced in other fields' conditions (from the conditional logic above), the API previously had no way to handle the dependency. Now, the force_remove_conditions parameter controls the 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 matters when you're programmatically managing recipients in dynamic workflows. Without force_remove_conditions, deleting a recipient whose fields feed into conditions on other fields would require you to manually clean up every condition reference first.

Technical summary

New schemas: ConditionSet, ConditionGroup, Condition

Upgrading from v1.9.0

No breaking changes. No field removals. No behavior changes. New fields default to null or false, so existing integrations require zero modification. If you're coming from an earlier version, the same applies to every release since v1.0.0. Check the full API changelog for the complete version history.

For details on v1.9.0 (OTP verification, template document replacement), see the v1.9.0 changelog section.

Get started

New to Firma.dev? Pay-as-you-go pricing at $0.029 per envelope, no contracts or minimums. Get started with Firma.dev for free, no credit card required.

Get your API key now

For the full API reference, see the Firma.dev documentation.