Embedded Signing Quickstart

This quickstart takes about 10 minutes. In just 4 API calls, you go from a plain PDF, DOC, or DOCX to a signed document with an audit trail.

Prerequisites

Before you begin, you need:

An API key from Settings — see Set up a developer account and Authentication
A PDF, DOC, or DOCX file under 40MB to send for signature

The examples below use the production base URL https://api.formabledocs.com/v1. Replace $TOKEN with your API key (it starts with fmbl_). Prefer a typed client? The same four calls are in the official SDKs.

Steps

Upload a template

Upload your document as multipart/form-data. Formable returns a templateId you’ll use to send the document. Optionally pass signer_roles so you can assign roles to fields in the editor.

curl --request POST \
  --url https://api.formabledocs.com/v1/templates \
  --header "Authorization: Bearer $TOKEN" \
  --form 'file=@./agreement.pdf' \
  --form 'filename=agreement.pdf' \
  --form 'signer_roles=[{"name":"Client","order":0}]'

Response

{
  "templateId": "abc123xyz",
  "editTemplateAccess": {
    "editUrl": "https://app.formabledocs.com/template-setup/abc123xyz",
    "expiresAt": "2024-01-16T10:30:00.000Z"
  }
}

Open the editUrl in a browser to place signature, text, and date fields on the document. Assign each required field a signer role (for example Client). See Embedded templates.

Template editor with a Signature field selected over the Customer line, showing Required toggle and Reference ID in the sidebar — Place a Signature field on the document, then click Save template.

Create an embedded signature request

Create a signature request from the template. Provide signers (who signs, with a role that matches required field roles on the template). sender is optional and defaults to the API key organization owner.

curl --request POST \
  --url https://api.formabledocs.com/v1/signature-requests/embedded \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "abc123xyz",
    "signers": [
      { "email": "signer@example.com", "name": "Jane Doe", "role": "Client" }
    ],
    "sender": { "email": "you@yourcompany.com", "name": "Your Company" },
    "testMode": true
  }'

Response

{
  "signatureRequestId": "sr_456def",
  "templateId": "abc123xyz",
  "signers": [
    {
      "email": "signer@example.com",
      "name": "Jane Doe",
      "recipientSignatureId": "rsig_789ghi"
    }
  ],
  "sender": { "email": "you@yourcompany.com", "name": "Your Company" },
  "status": "Created",
  "testMode": true
}

Save each signer’s recipientSignatureId. You’ll use it to mint that person’s signing URL.

Generate a signing URL

Turn a recipient signature into an embeddable signing URL. The URL expires one hour after creation.

curl --request POST \
  --url https://api.formabledocs.com/v1/recipient-signatures/rsig_789ghi/url \
  --header "Authorization: Bearer $TOKEN"

Response

{
  "signingUrl": "https://app.formabledocs.com/sign/embedded/xyz789abc",
  "expiresAt": "2024-01-16T10:30:00.000Z"
}

Load the signingUrl in an iframe or redirect the signer to it (link does not need to be embedded in iframe to be opened):

<iframe src="https://app.formabledocs.com/sign/embedded/xyz789abc" width="100%" height="800"></iframe>

Embedded signing view showing document.docx with a Sign here field on the Customer line, a Required callout, and a Start button — The signer clicks Start and completes each required field on the document.

Retrieve the signed document

Once the signer completes the document, download the signed PDF from a presigned URL.

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?..."
}

This endpoint returns 409 until the document is complete. Wait for the document_completed webhook, or poll signature request events / the signature request status until it’s Completed.

The signed PDF includes an audit trail with created, sent, signed, and completed events.

Formable audit trail for document.docx showing Created, Sent, Signed, and Completed events with status Completed — Every signed document includes an audit trail with timestamps and actors.

Next steps