> ## 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. # Send Signature Request > Send a document for signing from a file or a Lumin template using the Lumin API. 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 ` or `Bearer ` 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](/tabs/api-reference/api/templates/list-templates) to list available templates in your Workspace. *** ## Integration steps 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](/tabs/api-reference/api/signature-requests/send-signature-request) and [Send Signature Request from Template](/tabs/api-reference/api/signature-requests/send-signature-request-from-template) for full request schemas. 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](/tabs/guides/walkthroughs/text-tags). 1. Call `GET /templates` to find your `template_id`. See [List Templates](/tabs/api-reference/api/templates/list-templates). 2. Call `GET /templates/{template_id}` to see required `tags`, `fields`, `variables`, `signer_roles`, and `collections`. See [Get Template Details](/tabs/api-reference/api/templates/get-template-details). 3. 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 | 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`: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "signers": [ { "email_address": "alice@example.com", "name": "Alice", "group": 1 }, { "email_address": "bob@example.com", "name": "Bob", "group": 2 } ] } ``` **From template** — include `signer_role` when the template defines roles: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "signers": [ { "signer_role": "Tenant", "email_address": "tenant@example.com", "name": "Alex Tenant" }, { "signer_role": "Landlord", "email_address": "landlord@example.com", "name": "Sam Landlord" } ] } ``` Optionally add `viewers` for recipients who can view but not sign. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST https://api.luminpdf.com/v1/signature_request/send \ -H "Authorization: API-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": "alice@example.com", "name": "Alice", "group": 1 }, { "email_address": "bob@example.com", "name": "Bob", "group": 2 } ] }' ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST https://api.luminpdf.com/v1/signature_request/send-from-template \ -H "Authorization: API-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": "tenant@example.com", "name": "Alex Tenant" }, { "signer_role": "Landlord", "email_address": "landlord@example.com", "name": "Sam Landlord" } ] }' ``` Both endpoints return `201` with the new request ID: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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. Poll `GET /signature_request/{id}` to read the current state of the request and each signer: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl https://api.luminpdf.com/v1/signature_request/696d007913f3b8... \ -H "Authorization: API-key " ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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": "alice@example.com", "name": "Alice", "group": 1, "status": "APPROVED", "is_approved": true }, { "email_address": "bob@example.com", "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 | Once the status is `APPROVED`, retrieve the signed document: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl "https://api.luminpdf.com/v1/signature_request/696d007913f3b8.../file?type=agreement" \ -H "Authorization: API-key " ``` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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](/tabs/guides/webhooks/overview) to configure an endpoint.