New in Firma.dev: White-Label Your Signing Page Down to the Buttons

Firma.dev's signing page already carries your brand: your logo, your colors, your signer terms, your emails and your completion page. As of API v1.40.0, released October 17, 2026, it also follows your rules about what a signer can do on it. Two new settings hide the Decline to Sign and Save & Finish Later buttons on hosted and embedded signing pages, so a SaaS platform running embedded signing inside its own product now decides which actions its signers get.

New: Choose Which Buttons Your Signers See

The release adds two switches. allow_decline controls the Decline to Sign button and show_save_for_later controls Save & Finish Later. Both apply to the hosted signing page and to the embedded signing iframe, and both default to visible, so your signing pages stay exactly as they are until you set a value.

Hiding Decline to Sign is enforced. With allow_decline set to false, Firma.dev refuses any decline on that signing request, for signers and approvers alike, and the request can only be stopped by cancelling it... which hands the decline decision to your product. Hiding Save & Finish Later just removes the button.

Your Signing Page, White-Labeled End to End

Button visibility is the newest layer of a white-label stack that SaaS platforms already use to make embedded signing look and behave like part of their own app. The current controls, grouped by where the signer meets them:

On the signing page

• Signing page buttons (new): show or hide Decline to Sign and Save & Finish Later.

• Button labels: rename nine signing-view buttons per language with signing_button_label_overrides, Decline to Sign and Save & Finish Later included. More in custom signing button labels.

• Color theme: 11 color_* hex settings at company and workspace level. Five of them also theme the embedded editors.

• Display settings: signature frame, partial watermark, QR code, email OTP verification, terms acceptance, guided navigation and pre-signing download.

• Signer terms: your own consent statement per language, with an optional terms link.

• Field background colors and a signing UI in 15 languages, picked with the lang parameter.

Embedding

• Embedded signing in an iframe that emits signing.started, signing.completed, signing.declined and signing.error postMessage events. The embedded e-signature API quickstart walks through it.

• Embeddable template and signing request editors with theme and close controls.

Emails

• A custom sending domain verified with SPF, DKIM and DMARC, and your own sender address local part.

• Your logo (PNG or JPEG, up to 2 MB) on signing emails and certificates.

• Custom email templates at company or workspace level, plus per-request switches that turn off Firma.dev's signing, finish, expiration and cancellation emails. See white-label e-signature emails and signing links.

After signing

• A completion page with your own title, message and HTTPS redirect, covered in completion page customization.

• Organization seals with your company stamp on completed PDFs.

Per customer

• With Customer Workspaces, every setting that supports workspace level can differ from one customer to the next.

Labels and visibility stack, so one workspace can rename Decline to Sign to "Request changes" while another workspace hides it compeltely. The complete guide to the white-label e-signature API goes through each control in depth, and the white-label e-signatures feature page has the overview. All of it ships at the same price as everything else on Firma.dev pricing: €0.049 per envelope (~5¢ USD), pay-as-you-go, with no monthly minimums and no per-seat fees.

Four Levels, the Most Specific Wins

Each button can be set at four levels: company, workspace, template and signing request. Firma.dev reads the signing request's own value first. When that is null, the workspace value applies, and when the workspace is null too, the company value applies. The company default is true, which is why nothing moves until you change it. Two timing rules matter once this is in production.

Templates copy at creation

A signing request created from a template copies the template's values at the moment it is created. A value you pass in the create call's settings overrides the template, and null there falls through to the workspace. Editing the template later leaves the requests already created from it alone.

Workspace and company changes reach requests already sent

Any signing request whose own value is null picks up a workspace or company change, including requests already out for signature. Flip allow_decline to false on a busy workspace and every open request without its own value loses the Decline button too... so check what's in flight first.

Where to find it in the dashboard

• Company: Settings > Company Settings, under Signing page buttons. Two switches set the default for every workspace.

• Workspace: the workspace's Settings tab, under Signing page buttons. Choose Show, Hide or Use company default, and the change saves immediately.

• Template and signing request: the document settings tab in the editor sidebar, with Show, Hide or Use workspace default. A signing request can be changed until it is sent.

Run Your Own Decline Flow Inside Your Product

When a signer says no, plenty of products need the reason. A sales tool wants it on the deal record, a lending app wants a loan officer to call back, and a marketpalce wants to send a revised quote. With allow_decline: false, Firma.dev refuses every decline on the request, so the Decline button in your own UI becomes the only way a signer can say no.

A typical flow looks like this:

1. Set allow_decline: false on the signing request, its template or the workspace, and embed the signing page in an iframe pointing at https://app.firma.dev/signing/{signing_request_user_id}.

2. Put your own Decline button next to the iframe. When the signer clicks it, open your own dialog and capture a reason.

3. Route that reason where it belongs: a CRM note, an alert to the account manager, a support ticket.

4. From your backend, cancel the signing request with the reason attached.

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/SIGNING_REQUEST_ID/cancel \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Signer declined in app: pricing", "notify_signers": true}'

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/SIGNING_REQUEST_ID/cancel \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Signer declined in app: pricing", "notify_signers": true}'

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/SIGNING_REQUEST_ID/cancel \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Signer declined in app: pricing", "notify_signers": true}'

reason is optional and capped at 500 characters. notify_signers defaults to true, so set it to false if your product sends its own message to the signer. Cancel works on a request that has been sent and is not already finished or cancelled, and returns 409 otherwise. The same rule covers approvers, because a hidden Decline applies to every participant on the request.

Firma.dev is compliant with the ESIGN Act, UETA, eIDAS (SES and AES) and UK eIDAS, and signatures are legally binding in 55+ countries whichever buttons you show.

Single-signature forms

A one-page form with a single signatrue has nothing to come back to... hide Save & Finish Later on that template and the signer has one less button to think about.

One workflow, different rules

Keep Decline on as the company default and switch it off on a single template... an internal policy acknowledgement, say, where declining is not part of the process. Every other template keeps the button.

Set It Up With the API

All four levels take the same two keys. The company default accepts true or false only:

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": true, "show_save_for_later": true}'

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": true, "show_save_for_later": true}'

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": true, "show_save_for_later": true}'

A workspace override accepts null to fall back to the company value:

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/WORKSPACE_ID/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": false, "show_save_for_later": null}'

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/WORKSPACE_ID/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": false, "show_save_for_later": null}'

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/WORKSPACE_ID/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": false, "show_save_for_later": null}'

Per request, the keys go in settings on POST /signing-requests or POST /signing-requests/create-and-send. This example uses the template's recipients because none are passed:

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order form - Acme",
    "template_id": "TEMPLATE_ID",
    "settings": {"allow_decline": false, "show_save_for_later": false}
  }'

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order form - Acme",
    "template_id": "TEMPLATE_ID",
    "settings": {"allow_decline": false, "show_save_for_later": false}
  }'

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order form - Acme",
    "template_id": "TEMPLATE_ID",
    "settings": {"allow_decline": false, "show_save_for_later": false}
  }'

On PUT /signing-requests/{id} the same object lives under signing_request_properties.settings, and on PUT /templates/{id} under template_properties.settings. POST /templates and the PATCH routes take a top-level settings. Any value other than true, false or null returns 400 VALIDATION_ERROR naming the key, and nothing is written. The full table of routes is in the API changelog for v1.40.0.

Also in v1.40.0: A Clear 413 for Oversized Requests

Request bodies over 6 MiB now return 413 REQUEST_TOO_LARGE with the standard error and code body. Before, the gateway answered with a 502, which told you very little about what went wrong. For larger files, request an upload URL with POST /documents, upload the file to it, and pass document_id or document_ids in your create call.

In short, v1.40.0 lets you hide Decline to Sign and Save & Finish Later at company, workspace, template or request level. A hidden Decline is enforced, and the cancel endpoint gives your own decline flow a clean way to close the request. And it all sits on top of the logo, colors, labels, signer terms, emails and completion page you already control.

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