> ## 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 from Template
> Creates and sends a new signature request from a template with the submitted template data.
This endpoint requires the following scopes:
`sign:requests` and `templates`
The `verification` field on signers requires a **Digital Trust license** enabled at the Workspace level. If your Workspace is not licensed, the request will return a `403 verification_not_licensed` error. Contact your Lumin account manager to enable Digital Trust.
## OpenAPI
````yaml POST /signature_request/send-from-template
openapi: 3.1.0
info:
version: 1.0.0
title: Lumin API Reference
description: >
The Lumin API Reference provides a comprehensive set of tools to integrate
document workflows — including editing, eSignatures, and automation — into
your applications.
Useful links:
- [Document Repository](https://github.com/luminpdf/luminsign-docs)
- [API
Definition](https://github.com/luminpdf/luminsign-docs/blob/main/openapi.yaml)
- [Authentication Guide](/tabs/guides/authentication/overview)
termsOfService: https://www.luminpdf.com/terms-of-use/
contact:
name: API Support
email: integration@luminpdf.com
url: https://help.luminpdf.com
servers:
- url: https://api.luminpdf.com/v1
description: Production server
security: []
tags:
- name: Signature Requests
description: Everything about Signature Requests
- name: Users
description: Everything about Users
- name: Templates
description: Everything about Templates
- name: Documents
description: Everything about Documents
- name: Workspaces
description: Everything about Workspaces
- name: Agreements
description: Everything about Agreements
paths:
/signature_request/send-from-template:
post:
tags:
- Signature Requests
summary: Send Signature Request from Template
description: >-
Creates and sends a new signature request from a template with the
submitted template data.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SignatureRequestFromTemplateDTO'
responses:
'201':
description: Returns the information of the created signature request.
content:
application/json:
schema:
$ref: '#/components/schemas/SignatureRequestCreateResponse'
4XX:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKey: []
- BearerAuth:
- sign:requests
- templates
components:
schemas:
SignatureRequestFromTemplateDTO:
type: object
required:
- template_id
- signers
- title
- expires_at
properties:
template_id:
type: string
description: >-
ID of the template. ID needs to include the prefix returned by the
template list endpoint.
title:
type: string
minLength: 1
maxLength: 255
description: The title of the signature request.
tags:
type: object
description: >
Key–value pairs for **Merge Tags** defined in the Sign template.
Keys must match tag names. Values replace the corresponding tags and
are rendered as **plain text** in the sent agreement.
fields:
type: object
description: >
Key–value pairs for **Form Fields** defined in the template. Keys
must match field names. Values prefill the corresponding fields in
the sent agreement.
variables:
type: object
description: >
Key–value pairs for **Variables** defined in the AgreementGen
template. Keys must match variable names. Values prefill the
corresponding variables and are rendered as **plain text** in the
sent agreement.
collections:
type: object
description: >
Map of **collection name → array of record objects** used to expand
table-scoped row-loop markers in the template.
- Each key must match a collection name returned by [Get Template
Details](/tabs/api-reference/api/templates/get-template-details)
under `collections[].name`.
- Each value is an ordered array of flat record objects; each record
is a key–value map where keys match the collection's variable names
and values are strings.
- Records are rendered in array order.
- Maximum 100 items per collection, and up to 50 collections per
request.
Applies to AgreementGen templates only. Ignored silently when the
resolved template `type` is not `lumin`.
additionalProperties:
type: array
items:
type: object
additionalProperties:
type: string
signers:
type: array
items:
$ref: '#/components/schemas/SignerWithRole'
description: Signers of the signature request.
viewers:
type: array
items:
$ref: '#/components/schemas/Viewer'
description: Viewers of the signature request.
custom_email:
type: object
description: Custom email content for the email sent to signers.
properties:
sender_email:
type: string
description: The email address of the sender.
subject_name:
type: string
description: The subject of the email.
title:
type: string
description: The title of the email.
expires_at:
type: integer
format: unix-epoch
description: >-
When the signature request will expire. This is a unix epoch
timestamp (miliseconds). Should be later than today.
example:
template_id: sign_123
title: Mutual NDA Agreement
tags:
ClientName: ACME Corp
EffectiveDate: '2026-01-01'
ContractValue: $50,000
fields:
CustomerName: John Doe
AgreeToTerms: true
ContractDuration: 12
signers:
- signer_role: Tenant
email_address: tenant@acmecorp.com
name: Jane Smith
verification:
method: vc
payload:
doc_type: driver_license
claims:
- given_name
- family_name
- issuing_country
- issuing_authority
- document_number
- signer_role: Customer
email_address: customer@example.com
name: John Doe
viewers:
- email_address: legal@acmecorp.com
name: Legal Team
expires_at: 1927510980694
custom_email:
sender_email: tenant@acmecorp.com
subject_name: Mutual NDA Agreement from ACME Corp
title: Mutual NDA Agreement from ACME Corp
SignatureRequestCreateResponse:
type: object
required:
- signature_request
properties:
signature_request:
$ref: '#/components/schemas/SignatureRequestSummary'
description: Contains information about a signature request.
Error:
type: object
required:
- error_code
- error_message
properties:
error_code:
type: string
description: The system error code.
error_message:
type: string
description: The human-readable error message.
SignerWithRole:
type: object
required:
- email_address
- name
properties:
email_address:
type: string
description: Email address of the signer.
name:
type: string
description: Name of the signer.
signer_role:
type: string
description: >
The name of the signer role defined in the template. Must match a
signer role in the template. Required when the template has defined
signer roles.
verification:
type: object
description: >
Defines the identity verification method for a signer before they
can complete the signing process. This allows stronger assurance of
signer authenticity.
**Requires a Digital Trust license** enabled at the Workspace level.
If your Workspace is not licensed, including this field will return
a `403 verification_not_licensed` error. Contact your Lumin account
manager to enable Digital Trust.
properties:
method:
type: string
enum:
- vc
description: >
The verification method used. Required when the `verification`
object is present.
Possible values: `vc` – Verifiable Credential (via mDocs)
payload:
type: object
description: >
Payload parameters required by the verification method. Required
when the `verification` object is present.
properties:
doc_type:
type: string
enum:
- driver_license
- photo_id
- nz_business_passport
description: >
The type of credential requested from the signer.
- If **defined** → VC verification is **required** for this
signer.
- If **omitted** → VC verification is **optional** for this
signer.
Must be in the Workspace's `enabled_doc_types` list.
claims:
type: array
description: >
The specific attributes requested from the credential.
Required when the `verification` object is present.
**Required claims (always):**
- `given_name` – Signer's given name, validated against the
verified credential
- `family_name` – Signer's family name, validated against
the verified credential
**Optional claims:**
- `issuing_country` – Country where the credential was
issued
- `issuing_authority` – The issuing authority tied to the
root certificate
- `document_number` – The ID/number of the credential
The provided list must be a subset of the Workspace's
`required_claims`.
items:
type: string
enum:
- given_name
- family_name
- issuing_country
- issuing_authority
- document_number
Viewer:
type: object
required:
- email_address
- name
properties:
email_address:
type: string
description: Email address of the viewer.
name:
type: string
description: Name of the viewer.
SignatureRequestSummary:
type: object
required:
- signature_request_id
- created_at
- status
properties:
signature_request_id:
type: string
description: The unique identifier for the signature request.
created_at:
type: string
description: The time the signature request was created.
status:
type: string
description: The status of the signature request.
enum:
- WAITING_FOR_PROCESSING
- FAILED
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: >
Provide your API key in the `X-API-Key` header, e.g., `X-API-Key:
YOUR_API_KEY`.
BearerAuth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.luminpdf.com/oauth2/auth
tokenUrl: https://auth.luminpdf.com/oauth2/token
scopes:
openid: >-
Retrieve basic identity details (username, email, profile
picture).
offline_access: Request a refresh token for long-lived access. Private apps only.
profile.read: View basic user profile information.
workspaces: View and manage Workspaces and Spaces.
workspaces.read: View information about the authenticated user's Workspace.
templates: View and manage templates in a Workspace.
pdf:files: Create, edit, and delete PDF files in a Workspace.
pdf:files.read: Retrieve PDF documents stored in a Workspace.
sign:requests: Create, update, or view signature requests.
sign:requests.read: Retrieve signature requests.
agreements: Create, update, or delete AgreementGen documents.
description: >
OAuth 2.0 authorization code flow. Provide your access token in the
`Authorization` header, e.g., `Authorization: Bearer `. See the
[OAuth 2.0 guide](/tabs/guides/authentication/oauth2) for details.
````