Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt

Use this file to discover all available pages before exploring further.

Use this guide to send a document for signing from start to finish — uploading or linking a file, configuring signers, and retrieving the signed result.

​
Prerequisites

  • A valid API key. Pass it as Authorization: API-key <your-key> on every request.
  • A PDF document accessible via a public URL, or a file you can upload directly.
1
Provide your document
2
You can supply the document in one of four ways. Use whichever fits your integration — only one field is allowed per request.
3
FieldTypeDescriptionfile_urlstringPublic HTTPS URL to a single filefile_urlsarrayArray of public HTTPS URLs (multiple files)filebinaryA single uploaded file (multipart)filesarrayMultiple uploaded files (multipart)
4
Configure signers
5
Each signer object requires email_address and name. When using ordered signing (signing_type: ORDER), also set group to control the signing sequence.
6
{
  "signers": [
    {
      "email_address": "[email protected]",
      "name": "Alice"
    }
  ]
}
7
For ordered signing with multiple signers:
8
{
  "signers": [
    { "email_address": "[email protected]", "name": "Alice", "group": 1 },
    { "email_address": "[email protected]", "name": "Bob", "group": 2 }
  ]
}
9
Choose a signing type
10
ValueBehaviourSAME_TIMEAll signers receive the request at once and can sign in any order. This is the default.ORDERSigners receive notifications sequentially by group number. Group 2 is only notified after all signers in group 1 have signed.
11
Send the request
12
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 }
    ],
    "custom_email": {
      "subject_name": "Please sign: Year-End Report",
      "title": "Your signature is required"
    }
  }'
13
The API responds with a 201 and the new request’s ID and initial status:
14
{
  "signature_request": {
    "signature_request_id": "696d007913f3b8...",
    "created_at": "1768751225657",
    "status": "WAITING_FOR_PROCESSING"
  }
}
15
WAITING_FOR_PROCESSING is the initial status. Processing is asynchronous — the request transitions to NEED_TO_SIGN or WAITING_FOR_OTHERS shortly after creation.
16
Check the status
17
Poll GET /signature_request/{id} to read the current state of the request and each signer:
18
curl https://api.luminpdf.com/v1/signature_request/696d007913f3b8... \
  -H "Authorization: API-key <your-key>"
19
{
  "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",
    "details_url": "https://sign.luminpdf.com/auth?mode=view-contract&token=...",
    "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
      }
    ]
  }
}
20
Signature request statuses
21
StatusMeaningWAITING_FOR_PROCESSINGRequest received, being preparedNEED_TO_SIGNThe sender must also sign (when sender is a signer)WAITING_FOR_OTHERSWaiting on at least one signerAPPROVEDAll signers have signedREJECTEDA signer declinedFAILEDProcessing error — check reasonCANCELLEDManually cancelled
22
Download the signed file
23
Once the status is APPROVED, retrieve the signed document:
24
curl "https://api.luminpdf.com/v1/signature_request/696d007913f3b8.../file?type=agreement" \
  -H "Authorization: API-key <your-key>"
25
{
  "signed_url": "https://files.luminpdf.com/download/report-signed.pdf?expires=...",
  "expires_at": 1766726700
}
26
The signed_url is a pre-signed HTTPS download link that expires in 30 minutes. You can also request:
27
type valueReturnsagreementThe signed agreement PDF (default)cocCertificate of Completion PDFmergedAgreement + Certificate of Completion in a single PDF

​
Full request body reference

{
  "title": "Financial Year-End Report Authorization",
  "file_url": "https://example.com/report.pdf",
  "signing_type": "ORDER",
  "expires_at": 1927510980694,
  "use_text_tags": false,
  "signers": [
    {
      "email_address": "[email protected]",
      "name": "Alice",
      "group": 1
    },
    {
      "email_address": "[email protected]",
      "name": "Bob",
      "group": 2
    }
  ],
  "viewers": [
    {
      "email_address": "[email protected]",
      "name": "Manager"
    }
  ],
  "custom_email": {
    "sender_email": "[email protected]",
    "subject_name": "Please sign: Year-End Report",
    "title": "Your signature is required"
  }
}

​
Webhooks

Instead of polling, listen for the signature_request_approved webhook event to be notified the moment all signers complete the request. See the Webhooks guide to configure an endpoint.
Set use_text_tags: true if your PDF contains embedded text tags that define signing fields. See the Text Tags guide for syntax details.