Firma.dev API v1.9.0: OTP Verification, Template Document Replacement, and Schema Updates

v1.9.0 is a focused release built on top of v1.8.0 with no breaking changes. If you're integrated today, nothing breaks. Two new capabilities are now available when you need them: Signer Email OTP verification and Template Document Replacement.

What's in v1.9.0

Both changes are additive. No fields were removed, no endpoint behavior was changed, no migration is required from v1.8.0.

New: Signer Email OTP Verification

The require_otp_verification setting adds an identity verification step before a signer can access a document. When enabled, signers see a verification screen on opening their signing link, receive a 6-digit code to their email, and must enter it before the document loads.

The setting is a tri-state field: true, false, or null. Null means inherit from the level above. The override chain runs company → workspace → template → signing request, with signing request taking highest priority.

Enable OTP at the workspace level

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}

All signing requests in this workspace now require OTP by default.

Override OTP off for a specific signing request

PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}

PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}

PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}

This request skips OTP regardless of the workspace setting.

Schema Changes

New: Replace Template Document

The new POST /templates/{id}/replace-document endpoint lets you swap the underlying PDF on a template while keeping all field placements, signer assignments, and settings intact.

The replacement document must meet two validation requirements: same page count as the original, and page dimensions within 1pt tolerance. These constraints exist to ensure field positions remain valid after the swap. If either check fails, the API returns a 400 with a clear error.

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

const fs = require("fs");

const base64PDF = fs.readFileSync("./updated-contract.pdf").toString("base64");

const response = await fetch(
  `https://api.firma.dev/v1/templates/${templateId}/replace-document`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ document: base64PDF })
  }
);

const updatedTemplate = await response.json();

Error cases:

New Endpoints

Upgrading From v1.8.0

No action required. The checklist:

• No fields removed from any existing object

• No behavior changes to existing endpoints

• require_otp_verification defaults to null (inherits), so existing integrations are unaffected until you explicitly set it

• POST /templates/{id}/replace-document is a new endpoint, not a replacement for anything

Full API documentation is at docs.firma.dev. The complete API changelog is at docs.firma.dev/guides/api-changelog.

Get your API key and start building for free, no credit card required.