> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formabledocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> The key objects and terms you'll work with when embedding e-signatures.

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.

* Create a template with [Create a template](/api-reference/endpoint/create-template).
* Place fields using the **editor URL** returned on creation, or fetch a fresh one with [Create a template edit URL](/api-reference/endpoint/create-template-edit-url).

See the [Embedded templates walkthrough](/walkthroughs/embedded-templates) 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](/api-reference/endpoint/create-regular-signature-request) or an [embedded signature request](/api-reference/endpoint/create-signature-request). Both return a `signatureRequestId` plus a `recipientSignatureId` for each signer.

| Field | Description |
| - | - |
| `signers` | People who sign (`email`, `name`, and `role` matching required field roles). Returned on create and [get](/api-reference/endpoint/get-signature-request). |
| `recipientSignatureId` | Per-signer ID on each signer. For embedded flows, use it to mint that person's signing URL. |
| `sender` | Optional. Who is sending (`email` + `name`). Defaults to the API key organization owner. |
| `status` | `Created` when made, `Completed` once signed, or `Expired`. |
| `fields` | Envelope fields on create and get: type, required, filled, current value, and which recipient owns the field. Signature image data is never returned. |
| `testMode` | When `true`, the request doesn't count toward billing. Documents are watermarked and not legally binding. |

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`](/webhooks/events#document_completed) webhook, then download the **signed envelope** — a temporary URL to the completed PDF.

[Get a signature request](/api-reference/endpoint/get-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.

<Info>
  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.
</Info>

## 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.

<Warning>
  Generate signing URLs from your backend and pass them to the client just-in-time. Never expose your API keys in client-side code.
</Warning>

## 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](/webhooks/overview) 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](/api-reference/endpoint/get-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](/walkthroughs/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.