Non-embedded signing

Send a document for signature without embedding Formable in your product. You create a regular signature request with one or more signers, and Formable emails each person a signing link. Use this flow when signers should complete the document in their browser from an email.

Prefer signing inside your product? See Embedded signing instead.

Prerequisites

Before you begin:

Create an organization and API key in Settings.
Upload a template and place at least one signature field — see the Embedded templates walkthrough.
Call the Formable API from your backend only. Never expose your API key in the browser.

Overview

Create a regular signature request

Start a request from a template with one or more signers. Formable emails each signer automatically.

Signer completes the document

The signer opens the link from email and fills required fields on Formable.

Detect completion and download

Listen for webhooks or poll status, then fetch the signed PDF.

Create a regular signature request

Call this from your backend when you’re ready to send. A regular signature request needs:

templateId — which document to send
signers — who will sign (email + name), in signing order

Unlike embedded signature requests, you do not generate a signing URL. Formable creates the shares and emails each signer for you. See Create a regular signature request.

curl --request POST \
  --url https://api.formabledocs.com/v1/signature-requests \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "abc123xyz",
    "signers": [
      { "email": "jane@example.com", "name": "Jane Doe", "role": "Client" },
      { "email": "bob@example.com", "name": "Bob Smith", "role": "Witness" }
    ],
    "testMode": true
  }'

Response

{
  "signatureRequestId": "sr_456def",
  "templateId": "abc123xyz",
  "signers": [
    {
      "email": "jane@example.com",
      "name": "Jane Doe",
      "recipientSignatureId": "rsig_jane123"
    },
    {
      "email": "bob@example.com",
      "name": "Bob Smith",
      "recipientSignatureId": "rsig_bob456"
    }
  ],
  "sender": {
    "email": "owner@example.com",
    "name": "Org Owner"
  },
  "status": "Created",
  "testMode": true
}

Save the signatureRequestId. You’ll use it to track progress and download the signed PDF.

Each signer receives an email with a link to /sign/{envelopeShareId} — the same style of link used when you share from the Formable app.

Test mode

Set testMode: true while integrating so the request doesn’t count toward billing. Test mode documents are watermarked and are not legally binding.

Signing experience

Signers open the link from their email and complete required fields on Formable. Click Start to begin. Required fields are highlighted so the signer knows where to act.

Signing view showing document.docx with a Sign here field on the Customer line, a Required callout, and a Start button — The signing experience with a required Signature field highlighted. Click Start to begin.

When the signer reaches a Signature field, they can Draw, Type, or use a Saved signature. They must agree to the terms and conditions before confirming.

Signature modal over the document with Draw, Type, and Saved tabs, a drawn signature, consent checkbox, and Confirm button — The signature modal with Draw selected. Signers can also type a signature or reuse a saved one.

After all required fields are complete, the signer reviews the document and clicks Finish.

Signing view with a completed Customer signature and a Finish button — Review step after the signature is placed. Click Finish to complete the request.

Detect completion

When signing finishes, the signature request status becomes Completed. You have three ways to learn that:

Listen for the document_completed webhook

Configure a webhook endpoint and handle the document_completed event. Formable pushes this once the signed PDF is ready, so you can download without polling. Do not use document_signed alone — that fires when a signer finishes, before the completed file is available.

{
  "event": {
    "event_type": "document_completed",
    "event_category": "signing"
  },
  "signing": {
    "signature_request_id": "sr_456def"
  }
}

Poll the signature request status

Fetch the signature request and check status. It moves from Created to Completed. The response also includes signers (with recipientSignatureId) and envelope fields.

curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def \
  --header "Authorization: Bearer $TOKEN"

Read the event stream

Fetch signature request events for a chronological history of what happened.

curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def/events \
  --header "Authorization: Bearer $TOKEN"

Prefer the document_completed webhook as the source of truth before downloading. Use List signature requests with updatedSince, or the event stream, to reconcile anything you missed.

Download the signed PDF

Once status is Completed, fetch a temporary download URL for the signed PDF (the signed envelope).

curl --request GET \
  --url https://api.formabledocs.com/v1/signature-requests/sr_456def/signed-envelope \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "signedEnvelopePresignedUrl": "https://s3.amazonaws.com/bucket/signed-envelope.pdf?..."
}

Open or download that URL promptly — it is a short-lived presigned link.

Requesting the signed envelope before signing is complete returns 409 with "Envelope has not been signed yet".

Embedded vs non-embedded

	Embedded	Non-embedded
Endpoint	`POST /v1/signature-requests/embedded`	`POST /v1/signature-requests`
Delivery	You generate a signing URL and embed it	Formable emails each signer
UI	Iframe in your product	Formable hosted page from email link
Best for	In-app signing flows	Email-based signing outside your app

Next steps

Embedded signing

Embed the signing experience in an iframe inside your product.

Migrate from Dropbox Sign

Map send / send_with_template to Formable.

Webhooks

Get notified when a document is viewed or signed.

Create a regular signature request

Request and response schema for POST /v1/signature-requests.

Getting Started

Walkthroughs

SDKs

Migrations

Webhooks

Prerequisites

Overview

Create a regular signature request

Test mode

Signing experience

Detect completion

Download the signed PDF

Embedded vs non-embedded

Next steps

Embedded signing

Migrate from Dropbox Sign

Webhooks

Create a regular signature request

​Prerequisites

​Overview

​Create a regular signature request

​Test mode

​Signing experience

​Detect completion

​Download the signed PDF

​Embedded vs non-embedded

​Next steps

Embedded signing

Migrate from Dropbox Sign

Webhooks

Create a regular signature request

Prerequisites

Overview

Create a regular signature request

Test mode

Signing experience

Detect completion

Download the signed PDF

Embedded vs non-embedded

Next steps