Skip to main content
For e-signatures, you upload a reusable template, create a signature request with one or more signers, mint a signing URL per recipient for embedded flows, then download the signed envelope when they’re done.

​
Templates

A template is a document you’ve uploaded (PDF, DOC, or DOCX) with fields placed on it — for example signature, text, date, checkbox, or amount. Templates are reusable: upload once, then create many signature requests from the same templateId. Templates can define signer roles (for example Client and Witness). Assign a role to each required field in the editor. When you create a signature request, every role used by a required field must have a matching signer. See the Embedded templates walkthrough for the full workflow.

​
Signature requests

A signature request is one send of a template to one or more signers. You can create a regular (email) signature request or an embedded signature request. Both return a signatureRequestId plus a recipientSignatureId for each signer. For regular requests, Formable emails each signer a link — you do not create signing URLs. For embedded requests, generate a short-lived signing URL from each recipientSignatureId and embed it in an iframe. When signing finishes, wait for the document_completed webhook, then download the signed envelope — a temporary URL to the completed PDF. Get a signature request returns the same signers (with recipientSignatureId) and fields as create, plus the current status. Use it to poll progress or recover recipient IDs you didn’t persist.
An envelope is Formable’s internal record of a document prepared for a recipient. As an API consumer you work with signature requests; the signed envelope endpoint is how you get the final PDF.

​
Embedded Signing URLs are short-lived and embeddable

Signing URLs are meant to be embedded in an iframe in your own product. They expire (typically after one hour), so generate them on demand right before you display them rather than storing them.
Generate signing URLs from your backend and pass them to the client just-in-time. Never expose your API keys in client-side code.

​
Test mode

Signature requests accept a testMode flag. Use it while integrating so activity doesn’t count toward billing. Test mode documents are watermarked and are not legally binding. Test API keys always created test signatures.

​
Events

Track signing progress two ways:
  • Push — configure a webhook for real-time events such as document_viewed, document_signed, and document_completed. Wait for document_completed before downloading the signed PDF.
  • Pull — poll signature request events or check the signature request status to reconcile state.
Prefer webhooks for reacting in near real time, and use polling to backfill anything missed.

​
Redlining (optional)

Redlining is a separate workflow for negotiating a DOCX contract between two parties before signing. It uses redline requests, member roles, and turn-based rounds — see that walkthrough when you’re ready.