End-to-End Signing Flow

This guide walks through the complete workflow from uploading a document to getting a signed PDF.

Step 1: Upload the document

curl -X POST https://app.formalingo.com/api/v1/documents \
-H "Authorization: Bearer af_live_YOUR_KEY" \
-F "file=@contract.pdf" \
-F "title=Service Agreement"
# → { "data": { "id": "DOC_ID", ... } }

Step 2: Create signer roles

curl -X POST https://app.formalingo.com/api/v1/documents/DOC_ID/signer-roles \
-H "Authorization: Bearer af_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "label": "Client" }'
# → { "data": { "role": "signer_1", ... } }

Step 3: Place fields on the document

curl -X POST https://app.formalingo.com/api/v1/documents/DOC_ID/fields \
-H "Authorization: Bearer af_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
  "label": "Client Signature",
  "type": "digital_signature",
  "pageNumber": 2,
  "x": 0.1, "y": 0.85,
  "width": 0.35, "height": 0.06,
  "assigneeRole": "signer_1",
  "isRequired": true
}'

Step 4: Create a submission

curl -X POST https://app.formalingo.com/api/v1/documents/DOC_ID/submissions \
-H "Authorization: Bearer af_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
  "signers": [{
    "role": "signer_1",
    "name": "Jane Smith",
    "email": "jane@client.com",
    "prefill": {
      "COMPANY_FIELD_ID": "Client Corp Ltd"
    }
  }]
}'
# → { "data": { "signers": [{ "link": "https://www.formalingo.com/d/TOKEN", ... }] } }

Send signers[0].link to your signer. They open it in their browser, review the document, and sign.

Step 6: Wait for completion

When all signers complete signing:

Submission status → completed
A signed PDF is generated and stored
A document_all_complete webhook event fires (if configured)

You can either poll the submissions endpoint or listen to the document_all_complete webhook.

Option A: Poll for completion

curl https://app.formalingo.com/api/v1/documents/DOC_ID/submissions \
-H "Authorization: Bearer af_live_YOUR_KEY"
# Look for status: "completed" in the response

Option B: Webhook

Configure a document_all_complete webhook — see Webhook Events for payload details.

Step 7: Download the signed PDF

Once the submission is completed, download the signed PDF:

GET/api/v1/documents/{id}/submissions/{sid}/pdf

Required scope:read:submissions

Returns a short-lived presigned download URL (5-minute expiry). Use the URL to download the file directly.

# Get the download URL
curl https://app.formalingo.com/api/v1/documents/DOC_ID/submissions/SUB_ID/pdf \
-H "Authorization: Bearer af_live_YOUR_KEY"

# Response: { "data": { "downloadUrl": "https://...", "expiresIn": 300 } }

# Download the PDF
curl -o signed-contract.pdf "DOWNLOAD_URL_FROM_RESPONSE"

Response200

{
  "success": true,
  "data": {
    "submissionId": "submission-uuid",
    "completedAt": "2026-03-11T14:30:00.000Z",
    "downloadUrl": "https://storage.supabase.co/...signed.pdf?token=...",
    "expiresIn": 300
  }
}

The downloadUrl expires after 5 minutes. Request a new URL by calling the endpoint again.

End-to-End Signing Flow

On this page