Send Signature Request

curl --request POST \
  --url https://api.luminpdf.com/v1/signature_request/send \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "file_url": "https://example.com/path/to/document.pdf",
  "title": "Financial Year-End Report Authorization",
  "signers": [
    {
      "email_address": "[email protected]",
      "name": "John Doe",
      "group": 1,
      "verification": {
        "method": "vc",
        "payload": {
          "doc_type": "driver_license",
          "claims": [
            "given_name",
            "family_name"
          ]
        }
      }
    },
    {
      "email_address": "[email protected]",
      "name": "Jane Doe",
      "group": 2
    }
  ],
  "viewers": [
    {
      "email_address": "[email protected]",
      "name": "Jane Doe"
    }
  ],
  "expires_at": 1927510980694,
  "use_text_tags": false,
  "signing_type": "ORDER"
}
'

import requests

url = "https://api.luminpdf.com/v1/signature_request/send"

payload = {
    "file_url": "https://example.com/path/to/document.pdf",
    "title": "Financial Year-End Report Authorization",
    "signers": [
        {
            "email_address": "[email protected]",
            "name": "John Doe",
            "group": 1,
            "verification": {
                "method": "vc",
                "payload": {
                    "doc_type": "driver_license",
                    "claims": ["given_name", "family_name"]
                }
            }
        },
        {
            "email_address": "[email protected]",
            "name": "Jane Doe",
            "group": 2
        }
    ],
    "viewers": [
        {
            "email_address": "[email protected]",
            "name": "Jane Doe"
        }
    ],
    "expires_at": 1927510980694,
    "use_text_tags": False,
    "signing_type": "ORDER"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    file_url: 'https://example.com/path/to/document.pdf',
    title: 'Financial Year-End Report Authorization',
    signers: [
      {
        email_address: '[email protected]',
        name: 'John Doe',
        group: 1,
        verification: {
          method: 'vc',
          payload: {doc_type: 'driver_license', claims: ['given_name', 'family_name']}
        }
      },
      {email_address: '[email protected]', name: 'Jane Doe', group: 2}
    ],
    viewers: [{email_address: '[email protected]', name: 'Jane Doe'}],
    expires_at: 1927510980694,
    use_text_tags: false,
    signing_type: 'ORDER'
  })
};

fetch('https://api.luminpdf.com/v1/signature_request/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.luminpdf.com/v1/signature_request/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'file_url' => 'https://example.com/path/to/document.pdf',
    'title' => 'Financial Year-End Report Authorization',
    'signers' => [
        [
                'email_address' => '[email protected]',
                'name' => 'John Doe',
                'group' => 1,
                'verification' => [
                                'method' => 'vc',
                                'payload' => [
                                                                'doc_type' => 'driver_license',
                                                                'claims' => [
                                                                                                                                'given_name',
                                                                                                                                'family_name'
                                                                ]
                                ]
                ]
        ],
        [
                'email_address' => '[email protected]',
                'name' => 'Jane Doe',
                'group' => 2
        ]
    ],
    'viewers' => [
        [
                'email_address' => '[email protected]',
                'name' => 'Jane Doe'
        ]
    ],
    'expires_at' => 1927510980694,
    'use_text_tags' => false,
    'signing_type' => 'ORDER'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.luminpdf.com/v1/signature_request/send"

	payload := strings.NewReader("{\n  \"file_url\": \"https://example.com/path/to/document.pdf\",\n  \"title\": \"Financial Year-End Report Authorization\",\n  \"signers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"John Doe\",\n      \"group\": 1,\n      \"verification\": {\n        \"method\": \"vc\",\n        \"payload\": {\n          \"doc_type\": \"driver_license\",\n          \"claims\": [\n            \"given_name\",\n            \"family_name\"\n          ]\n        }\n      }\n    },\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\",\n      \"group\": 2\n    }\n  ],\n  \"viewers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\"\n    }\n  ],\n  \"expires_at\": 1927510980694,\n  \"use_text_tags\": false,\n  \"signing_type\": \"ORDER\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.luminpdf.com/v1/signature_request/send")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file_url\": \"https://example.com/path/to/document.pdf\",\n  \"title\": \"Financial Year-End Report Authorization\",\n  \"signers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"John Doe\",\n      \"group\": 1,\n      \"verification\": {\n        \"method\": \"vc\",\n        \"payload\": {\n          \"doc_type\": \"driver_license\",\n          \"claims\": [\n            \"given_name\",\n            \"family_name\"\n          ]\n        }\n      }\n    },\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\",\n      \"group\": 2\n    }\n  ],\n  \"viewers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\"\n    }\n  ],\n  \"expires_at\": 1927510980694,\n  \"use_text_tags\": false,\n  \"signing_type\": \"ORDER\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.luminpdf.com/v1/signature_request/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file_url\": \"https://example.com/path/to/document.pdf\",\n  \"title\": \"Financial Year-End Report Authorization\",\n  \"signers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"John Doe\",\n      \"group\": 1,\n      \"verification\": {\n        \"method\": \"vc\",\n        \"payload\": {\n          \"doc_type\": \"driver_license\",\n          \"claims\": [\n            \"given_name\",\n            \"family_name\"\n          ]\n        }\n      }\n    },\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\",\n      \"group\": 2\n    }\n  ],\n  \"viewers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\"\n    }\n  ],\n  \"expires_at\": 1927510980694,\n  \"use_text_tags\": false,\n  \"signing_type\": \"ORDER\"\n}"

response = http.request(request)
puts response.read_body

{
  "signature_request": {
    "signature_request_id": "<string>",
    "created_at": "<string>"
  }
}

{
  "error_code": "<string>",
  "error_message": "<string>"
}

POST

signature_request

send

Send Signature Request

curl --request POST \
  --url https://api.luminpdf.com/v1/signature_request/send \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "file_url": "https://example.com/path/to/document.pdf",
  "title": "Financial Year-End Report Authorization",
  "signers": [
    {
      "email_address": "[email protected]",
      "name": "John Doe",
      "group": 1,
      "verification": {
        "method": "vc",
        "payload": {
          "doc_type": "driver_license",
          "claims": [
            "given_name",
            "family_name"
          ]
        }
      }
    },
    {
      "email_address": "[email protected]",
      "name": "Jane Doe",
      "group": 2
    }
  ],
  "viewers": [
    {
      "email_address": "[email protected]",
      "name": "Jane Doe"
    }
  ],
  "expires_at": 1927510980694,
  "use_text_tags": false,
  "signing_type": "ORDER"
}
'

import requests

url = "https://api.luminpdf.com/v1/signature_request/send"

payload = {
    "file_url": "https://example.com/path/to/document.pdf",
    "title": "Financial Year-End Report Authorization",
    "signers": [
        {
            "email_address": "[email protected]",
            "name": "John Doe",
            "group": 1,
            "verification": {
                "method": "vc",
                "payload": {
                    "doc_type": "driver_license",
                    "claims": ["given_name", "family_name"]
                }
            }
        },
        {
            "email_address": "[email protected]",
            "name": "Jane Doe",
            "group": 2
        }
    ],
    "viewers": [
        {
            "email_address": "[email protected]",
            "name": "Jane Doe"
        }
    ],
    "expires_at": 1927510980694,
    "use_text_tags": False,
    "signing_type": "ORDER"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    file_url: 'https://example.com/path/to/document.pdf',
    title: 'Financial Year-End Report Authorization',
    signers: [
      {
        email_address: '[email protected]',
        name: 'John Doe',
        group: 1,
        verification: {
          method: 'vc',
          payload: {doc_type: 'driver_license', claims: ['given_name', 'family_name']}
        }
      },
      {email_address: '[email protected]', name: 'Jane Doe', group: 2}
    ],
    viewers: [{email_address: '[email protected]', name: 'Jane Doe'}],
    expires_at: 1927510980694,
    use_text_tags: false,
    signing_type: 'ORDER'
  })
};

fetch('https://api.luminpdf.com/v1/signature_request/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.luminpdf.com/v1/signature_request/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'file_url' => 'https://example.com/path/to/document.pdf',
    'title' => 'Financial Year-End Report Authorization',
    'signers' => [
        [
                'email_address' => '[email protected]',
                'name' => 'John Doe',
                'group' => 1,
                'verification' => [
                                'method' => 'vc',
                                'payload' => [
                                                                'doc_type' => 'driver_license',
                                                                'claims' => [
                                                                                                                                'given_name',
                                                                                                                                'family_name'
                                                                ]
                                ]
                ]
        ],
        [
                'email_address' => '[email protected]',
                'name' => 'Jane Doe',
                'group' => 2
        ]
    ],
    'viewers' => [
        [
                'email_address' => '[email protected]',
                'name' => 'Jane Doe'
        ]
    ],
    'expires_at' => 1927510980694,
    'use_text_tags' => false,
    'signing_type' => 'ORDER'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.luminpdf.com/v1/signature_request/send"

	payload := strings.NewReader("{\n  \"file_url\": \"https://example.com/path/to/document.pdf\",\n  \"title\": \"Financial Year-End Report Authorization\",\n  \"signers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"John Doe\",\n      \"group\": 1,\n      \"verification\": {\n        \"method\": \"vc\",\n        \"payload\": {\n          \"doc_type\": \"driver_license\",\n          \"claims\": [\n            \"given_name\",\n            \"family_name\"\n          ]\n        }\n      }\n    },\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\",\n      \"group\": 2\n    }\n  ],\n  \"viewers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\"\n    }\n  ],\n  \"expires_at\": 1927510980694,\n  \"use_text_tags\": false,\n  \"signing_type\": \"ORDER\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.luminpdf.com/v1/signature_request/send")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file_url\": \"https://example.com/path/to/document.pdf\",\n  \"title\": \"Financial Year-End Report Authorization\",\n  \"signers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"John Doe\",\n      \"group\": 1,\n      \"verification\": {\n        \"method\": \"vc\",\n        \"payload\": {\n          \"doc_type\": \"driver_license\",\n          \"claims\": [\n            \"given_name\",\n            \"family_name\"\n          ]\n        }\n      }\n    },\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\",\n      \"group\": 2\n    }\n  ],\n  \"viewers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\"\n    }\n  ],\n  \"expires_at\": 1927510980694,\n  \"use_text_tags\": false,\n  \"signing_type\": \"ORDER\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.luminpdf.com/v1/signature_request/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file_url\": \"https://example.com/path/to/document.pdf\",\n  \"title\": \"Financial Year-End Report Authorization\",\n  \"signers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"John Doe\",\n      \"group\": 1,\n      \"verification\": {\n        \"method\": \"vc\",\n        \"payload\": {\n          \"doc_type\": \"driver_license\",\n          \"claims\": [\n            \"given_name\",\n            \"family_name\"\n          ]\n        }\n      }\n    },\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\",\n      \"group\": 2\n    }\n  ],\n  \"viewers\": [\n    {\n      \"email_address\": \"[email protected]\",\n      \"name\": \"Jane Doe\"\n    }\n  ],\n  \"expires_at\": 1927510980694,\n  \"use_text_tags\": false,\n  \"signing_type\": \"ORDER\"\n}"

response = http.request(request)
puts response.read_body

{
  "signature_request": {
    "signature_request_id": "<string>",
    "created_at": "<string>"
  }
}

{
  "error_code": "<string>",
  "error_message": "<string>"
}

Required scopes (OAuth 2.0)

This endpoint requires the following scope:sign:requests

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.

Authorizations

X-API-Key

string

header

required

Provide your API key in the X-API-Key header, e.g., X-API-Key: YOUR_API_KEY.

Body

application/json

signers

object[]

required

Signers of the signature request.

Hide child attributes

signers.email_address

string

required

Email address of the signer.

signers.name

string

required

Name of the signer.

signers.group

string

The signing order of signer for signature request with signing_type is ORDER. Required if signing_type is ORDER. Group starts at 1. Only signers in first group will receive email/notification, signers in subsequent groups will receive email/notification when all signers in previous group has signed.

signers.verification

object

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.

Hide child attributes

signers.verification.method

enum<string>

The verification method used. Required when the verification object is present.

Possible values: vc – Verifiable Credential (via mDocs)

Available options:

vc

signers.verification.payload

object

Payload parameters required by the verification method. Required when the verification object is present.

Hide child attributes

signers.verification.payload.doc_type

enum<string>

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.

Available options:

driver_license,

photo_id,

nz_business_passport

signers.verification.payload.claims

enum<string>[]

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.

Available options:

given_name,

family_name,

issuing_country,

issuing_authority,

document_number

title

string

required

The title of the signature request.

Required string length: 1 - 255

expires_at

integer<unix-epoch>

required

When the signature request will expire. This is a unix epoch timestamp (miliseconds). Should be later than today.

file_url

string

The URL of a single file to be downloaded and signed. This field is mutually exclusive with file, files, and file_urls. Only one of these fields should be provided in the request.

file

A single uploaded file to be sent for signature. This field is mutually exclusive with file_url, files, and file_urls. Only one of these fields should be provided in the request.

file_urls

string[]

An array of URLs of files to be downloaded and signed. This field is mutually exclusive with file, files, and file_url. Only one of these fields should be provided in the request.

files

binary[]

An array of uploaded files to be sent for signature. This field is mutually exclusive with file, file_url, and file_urls. Only one of these fields should be provided in the request.

viewers

object[]

Viewers of the signature request.

Hide child attributes

viewers.email_address

string

required

Email address of the viewer.

viewers.name

string

required

Name of the viewer.

use_text_tags

boolean

Set to true to enable Text Tag parsing in your document. Your Text Tags will be converted into UI components for the user to interact with. Defaults to false.

signing_type

enum<string>

The signing order for the signature request. Defaults to SAME_TIME.

Available options:

SAME_TIME,

ORDER

custom_email

object

Custom email content for the email sent to signers.

Hide child attributes

custom_email.sender_email

string

The email address of the sender.

custom_email.subject_name

string

The subject of the email.

custom_email.title

string

The title of the email.

Response

Returns the information of the created signature request.

signature_request

object

required

Contains information about a signature request.

Hide child attributes

signature_request.signature_request_id

string

required

The unique identifier for the signature request.

signature_request.created_at

string

required

The time the signature request was created.

signature_request.status

enum<string>

required

The status of the signature request.

Available options:

WAITING_FOR_PROCESSING,

FAILED

Update Signature Request

Send Signature Request from Template

API Documentation

Lumin API reference

Send Signature Request

Authorizations

Body

Response