Send Signature Request

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

Choose how to send

Use one of two endpoints:

Method	Endpoint	When to use
From file	`POST /signature_request/send`	You already have a PDF — link, upload, or host it yourself.
From template	`POST /signature_request/send-from-template`	You 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.

Prepare the document

From file
From template

Supply the document in one of four ways. Only one field is allowed per request.

Field	Type	Description
`file_url`	string	Public HTTPS URL to a single file
`file_urls`	array	Array of public HTTPS URLs (multiple files)
`file`	binary	A single uploaded file (multipart)
`files`	array	Multiple uploaded files (multipart)

Set use_text_tags: true if your PDF contains embedded text tags that define signing fields. See the Text Tags guide.

Call GET /templates to find your template_id. See List Templates.
Call GET /templates/{template_id} to see required tags, fields, variables, signer_roles, and collections. See Get Template Details.
Include template_id and the placeholder values your template expects:

Field	Used for
`tags`	Merge tags in Sign templates (`sign_` prefix)
`fields`	Form fields in PDF or Sign templates
`variables`	Variables in AgreementGen templates (`ag_` prefix)
`collections`	Row-loop tables in AgreementGen templates

Configure signers

Each signer requires email_address and name. Set signing_type to control signing order:

Value	Behaviour
`SAME_TIME`	All signers receive the request at once. Default.
`ORDER`	Signers 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.

Send the request

From file
From template

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 }
    ]
  }'

curl -X POST https://api.luminpdf.com/v1/signature_request/send-from-template \
  -H "Authorization: API-key <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "sign_123456",
    "title": "Mutual NDA Agreement",
    "expires_at": 1927510980694,
    "tags": {
      "Client.Name": "Acme Corp",
      "Effective.Date": "2026-01-01"
    },
    "signers": [
      { "signer_role": "Tenant", "email_address": "[email protected]", "name": "Alex Tenant" },
      { "signer_role": "Landlord", "email_address": "[email protected]", "name": "Sam Landlord" }
    ]
  }'

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.

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
      }
    ]
  }
}

Status	Meaning
`WAITING_FOR_PROCESSING`	Request received, being prepared
`NEED_TO_SIGN`	The sender must also sign (when sender is a signer)
`WAITING_FOR_OTHERS`	Waiting on at least one signer
`APPROVED`	All signers have signed
`REJECTED`	A signer declined
`FAILED`	Processing error — check `reason`
`CANCELLED`	Manually cancelled

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` value	Returns
`agreement`	The signed agreement PDF (default)
`coc`	Certificate of Completion PDF
`merged`	Agreement + 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.

Getting started

Authentication

Webhooks

Walkthroughs

Prerequisites

Integration steps

Webhooks

​Prerequisites

​Integration steps

​Webhooks

Prerequisites

Integration steps

Webhooks