> ## 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.
# Embedded Signing Quickstart
> Create your first signature request and get an embeddable signing URL.
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](https://app.formabledocs.com/settings) — see [Set up a developer account](/developer-account) and [Authentication](/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](/sdks/overview).
## Steps
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.
```bash theme={null}
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}]'
```
```json Response theme={null}
{
"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](/walkthroughs/embedded-templates).
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.
```bash theme={null}
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
}'
```
```json Response theme={null}
{
"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.
Turn a recipient signature into an embeddable signing URL. The URL expires one hour after creation.
```bash theme={null}
curl --request POST \
--url https://api.formabledocs.com/v1/recipient-signatures/rsig_789ghi/url \
--header "Authorization: Bearer $TOKEN"
```
```json Response theme={null}
{
"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):
```html theme={null}
```
Once the signer completes the document, download the signed PDF from a presigned URL.
```bash theme={null}
curl --request GET \
--url https://api.formabledocs.com/v1/signature-requests/sr_456def/signed-envelope \
--header "Authorization: Bearer $TOKEN"
```
```json Response theme={null}
{
"signedEnvelopePresignedUrl": "https://s3.amazonaws.com/bucket/signed-envelope.pdf?..."
}
```
This endpoint returns `409` until the document is complete. Wait for the [`document_completed`](/webhooks/events#document_completed) webhook, or poll [signature request events](/api-reference/endpoint/get-signature-request-events) / the [signature request](/api-reference/endpoint/get-signature-request) `status` until it's `Completed`.
The signed PDF includes an audit trail with created, sent, signed, and completed events.
## Next steps
Prefill fields, embed signing, detect completion, and download the signed PDF.
Email each signer a signing link.
Place fields and reuse documents across signature requests.
Get notified when a document is viewed or signed.
Need contract negotiation before signing? See the optional [redlining walkthrough](/walkthroughs/redlining).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.