Create a signature request

POST/signatures

The primary V3 endpoint. It uploads your PDF document(s), creates the submission together with its signers and signature fields, and returns the submission with a per-signer signature link.

⚠️

This endpoint is multipart/form-data, not JSON. The signers field is a JSON string sent inside the form — this is the most common integration mistake.

Request Properties

file File (PDF) — required
One or more PDFs. Repeat the file field once per document. Only application/pdf is accepted.
name String — required
Name of the signature request / submission.
signers String (JSON) — required
A JSON-encoded array of signer objects (see below).
skipIntro Boolean (default false)
Set true to skip the intro screen on the signing page.
sendEmail Boolean (default false)
Set true to make Digit email the signing invite to each signer. Changes email validation — see below.

Signer object

firstname String — required
lastname String — required
email String — conditional
Optional by default. Required for every signer when sendEmail is true. When present it must be a valid email format.
fields Array — required, at least 1

Field object

type String — required
The field type. Use signature.
name String — required
document String — required
The uploaded file's name. Must exactly match the name of one of the uploaded files, otherwise the request fails with Document {name} not found.
area Object — required
The placement of the field on the page.
- x Number — required
- y Number — required
- w Number > 0 — required
- h Number > 0 — required
- page Integer ≥ 0 — required

signers

"signers": [
  {
    "firstname": "Jane",
    "lastname": "Doe",
    "email": "jane@acme.com",
    "fields": [
      {
        "type": "signature",
        "name": "Sign here",
        "document": "contract.pdf",
        "area": {
          "x": 120,
          "y": 640,
          "w": 200,
          "h": 80,
          "page": 0
        }
      }
    ]
  }
]

📐

Coordinates are in PDF user-space points relative to the page and are converted server-side to page-relative percentages using the actual PDF page size. page is 0-indexed.

Email behavior (the `sendEmail` rule)

sendEmail omitted or false → email is optional per signer. When omitted, the signer is created without an email and no email is sent — you distribute the returned signatureLink yourself.
sendEmail: true → email is required for every signer. Digit sends the signing-invite email to each signer.

The email format validated is ^[^\s@]+@[^\s@]+\.[^\s@]+$.

📘

Even with sendEmail: true, only the initial invite email is sent for API submissions in V3 — the final signed-document email is not.

📘

Content-Type : multipart/form-data

NodeJS

var axios = require("axios").default;
var fs = require("fs");
var FormData = require("form-data");
 
let formData = new FormData()
formData.append('file', fs.createReadStream('./contract.pdf'))
formData.append('name', 'Acme NDA')
formData.append('signers', JSON.stringify([
  {
    "firstname": "Jane",
    "lastname": "Doe",
    "email": "jane@acme.com",
    "fields": [
      {
        "type": "signature",
        "name": "Sign here",
        "document": "contract.pdf",
        "area": { "x": 120, "y": 640, "w": 200, "h": 80, "page": 0 }
      }
    ]
  }
]))
 
var options = {
  method: 'POST',
  url: 'https://api.signature.nc/api/v3/signatures',
  headers: {'Authorization': 'Bearer {apiKey}', ...formData.getHeaders()},
  data: formData
};
 
axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

cURL

curl -X POST "https://api.signature.nc/api/v3/signatures" \
  -H "Authorization: Bearer {apiKey}" \
  -F "file=@./contract.pdf" \
  -F "name=Acme NDA" \
  -F 'signers=[
    {
      "firstname": "Jane",
      "lastname": "Doe",
      "email": "jane@acme.com",
      "fields": [
        { "type": "signature", "name": "Sign here", "document": "contract.pdf",
          "area": { "x": 120, "y": 640, "w": 200, "h": 80, "page": 0 } }
      ]
    }
  ]'

Response

Returns the created submission with each signer's signing details. The signatureLink is the URL to send to the signer (append ?skipIntro=true when skipIntro was set).

json

{
    "name": "Acme NDA",
    "uuid": "b1c2e3d4-5678-90ab-cdef-1234567890e9",
    "createdAt": "2026-06-22T10:00:00.000Z",
    "updatedAt": "2026-06-22T10:00:00.000Z",
    "template": {
        "name": "Acme NDA",
        "uuid": "73e135cc-19c0-468e-a218-e6e5062e2af9",
        "createdAt": "2026-06-22T10:00:00.000Z",
        "updatedAt": "2026-06-22T10:00:00.000Z"
    },
    "submitters": [
        {
            "email": "jane@acme.com",
            "firstname": "Jane",
            "lastname": "Doe",
            "uuid": "c08f0b15-b17b-48a6-9555-ec2e4adb5229",
            "signatureLink": "http://localhost:3000/sign/c08f0b15-b17b-48a6-9555-ec2e4adb5229",
            "status": "sent",
            "signedDocuments": null,
            "signerInformation": null,
            "completedAt": null
        }
    ],
    "createdBy": {
        "firstname": "Owner",
        "lastname": "User",
        "email": "owner@acme.com"
    }
}

Per-signer `status` values

Status	Meaning
`initiated`	Signer created, signing record not yet provisioned
`sent`	Ready to sign; link active, not yet opened
`opened`	Signer opened the link, not yet signed
`completed`	Signer has signed (`signedDocuments` populated, `completedAt` set)

Errors

All validation failures return 400 Bad Request with a plain-text message.

Message	Cause
`At least 1 file must be provided`	No `file` uploaded
`Only PDF files are supported`	A non-PDF file uploaded
`A name must be provided`	Missing `name`
`A signers must be provided`	Missing `signers`
`At least 1 signer must be provided`	Empty signers array
`Signer {n}: A firstname must be provided`	Missing / blank firstname
`Signer {n}: A lastname must be provided`	Missing / blank lastname
`Signer {n}: An email must be provided when sendEmail is enabled`	`sendEmail:true` and missing email
`Signer {n}: Invalid email format: {email}`	Email present but malformed
`Signer {n} ({email}): Must have at least 1 field`	Signer has no fields
`Signer {n} ..., Field {m}: A type must be provided`	Missing field type
`Signer {n} ..., Field {m}: A name must be provided`	Missing field name
`Signer {n} ..., Field {m}: An area must be provided`	Missing `area`
`Signer {n} ..., Field {m}: Area x/y coordinate must be a number`	Bad coordinate
`Signer {n} ..., Field {m}: Area width/height must be a positive number`	`w` / `h` ≤ 0
`Signer {n} ..., Field {m}: Area page must be a non-negative integer`	Bad `page`
`Document {name} not found`	`field.document` doesn't match any uploaded file name
`Index page unknown`	`area.page` out of range for the PDF

Other failures: 401 (bad token), 403 "You've reached the API limit for this plan" (production envelope quota exhausted).

Introduction List all submissions