Skip to main content
Send a signature request from a PDF file or a Lumin template, then track status and download the signed result.

​
Prerequisites

  • A valid API key or OAuth app with the sign:requests scope. Pass credentials as Authorization: API-key <your-key> or Bearer <token> on every request.
  • From file: a PDF accessible via a public URL, or a file you can upload directly.
  • From template: a Lumin template ID and the templates scope (OAuth) or API key access to templates. See List Templates to list available templates in your Workspace.

​
Integration steps

1

Choose how to send

Use one of two endpoints:
MethodEndpointWhen to use
From filePOST /signature_request/sendYou already have a PDF — link, upload, or host it yourself.
From templatePOST /signature_request/send-from-templateYou have a Lumin template with merge tags, form fields, or variables to fill in.
See Send Signature Request and Send Signature Request from Template for full request schemas.
2

Prepare the document

Supply the document in one of four ways. Only one field is allowed per request.
FieldTypeDescription
file_urlstringPublic HTTPS URL to a single file
file_urlsarrayArray of public HTTPS URLs (multiple files)
filebinaryA single uploaded file (multipart)
filesarrayMultiple uploaded files (multipart)
Set use_text_tags: true if your PDF contains embedded text tags that define signing fields. See the Text Tags guide.
3

Configure signers

Each signer requires email_address and name. Set signing_type to control signing order:
ValueBehaviour
SAME_TIMEAll signers receive the request at once. Default.
ORDERSigners are notified sequentially by group number.
From file — assign group when using ORDER:
{
  "signers": [
    { "email_address": "[email protected]", "name": "Alice", "group": 1 },
    { "email_address": "[email protected]", "name": "Bob", "group": 2 }
  ]
}
From template — include signer_role when the template defines roles:
{
  "signers": [
    { "signer_role": "Tenant", "email_address": "[email protected]", "name": "Alex Tenant" },
    { "signer_role": "Landlord", "email_address": "[email protected]", "name": "Sam Landlord" }
  ]
}
Optionally add viewers for recipients who can view but not sign.
4

Send the request

curl -X POST https://api.luminpdf.com/v1/signature_request/send \
  -H "Authorization: API-key <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Financial Year-End Report Authorization",
    "file_url": "https://example.com/report.pdf",
    "signing_type": "ORDER",
    "expires_at": 1927510980694,
    "signers": [
      { "email_address": "[email protected]", "name": "Alice", "group": 1 },
      { "email_address": "[email protected]", "name": "Bob", "group": 2 }
    ]
  }'
Both endpoints return 201 with the new request ID:
{
  "signature_request": {
    "signature_request_id": "696d007913f3b8...",
    "created_at": "1768751225657",
    "status": "WAITING_FOR_PROCESSING"
  }
}
WAITING_FOR_PROCESSING is the initial status. Processing is asynchronous, the request transitions to NEED_TO_SIGN or WAITING_FOR_OTHERS shortly after creation.
5

Check the status

Poll GET /signature_request/{id} to read the current state of the request and each signer:
curl https://api.luminpdf.com/v1/signature_request/696d007913f3b8... \
  -H "Authorization: API-key <your-key>"

{
  "signature_request": {
    "signature_request_id": "696d007913f3b8...",
    "title": "Financial Year-End Report Authorization",
    "status": "WAITING_FOR_OTHERS",
    "signing_type": "ORDER",
    "created_at": "1768751225657",
    "expires_at": "1927510980694",
    "signers": [
      {
        "email_address": "[email protected]",
        "name": "Alice",
        "group": 1,
        "status": "APPROVED",
        "is_approved": true
      },
      {
        "email_address": "[email protected]",
        "name": "Bob",
        "group": 2,
        "status": "NEED_TO_SIGN",
        "is_approved": false
      }
    ]
  }
}
StatusMeaning
WAITING_FOR_PROCESSINGRequest received, being prepared
NEED_TO_SIGNThe sender must also sign (when sender is a signer)
WAITING_FOR_OTHERSWaiting on at least one signer
APPROVEDAll signers have signed
REJECTEDA signer declined
FAILEDProcessing error — check reason
CANCELLEDManually cancelled
6

Download the signed file

Once the status is APPROVED, retrieve the signed document:
curl "https://api.luminpdf.com/v1/signature_request/696d007913f3b8.../file?type=agreement" \
  -H "Authorization: API-key <your-key>"

{
  "signed_url": "https://files.luminpdf.com/download/report-signed.pdf?expires=...",
  "expires_at": 1766726700
}
The signed_url is a pre-signed HTTPS download link that expires in 30 minutes.
type valueReturns
agreementThe signed agreement PDF (default)
cocCertificate of Completion PDF
mergedAgreement + Certificate of Completion in a single PDF

​
Webhooks

Instead of polling, listen for the signature_request_approved webhook event to be notified when all signers complete the request. See the Webhooks guide to configure an endpoint.