Create a signing request

POST a document and signer list to start a signing ceremony.

POST /v1/signing-requests

Creates a new signing request, validates field coordinates at ingestion, and returns a signing_url for the first signer.

Request headers

Header	Value
`Authorization`	`Bearer sk_live_...` (API key)
`Content-Type`	`application/json`

Request body

The field names below are illustrative. Verify the exact schema against your NoSign instance’s API.

{
  "document": "<base64-encoded PDF>",
  "callback_url": "https://your-app.com/webhooks/nosign",
  "signers": [
    {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "fields": [
        {
          "page": 1,
          "x": 72,
          "y": 640,
          "w": 180,
          "h": 48,
          "type": "signature",
          "required": true
        }
      ]
    }
  ]
}

Top-level fields

Field	Type	Required	Description
`document`	string	Yes*	Base64-encoded PDF content (*not needed when creating from a `template_id`)
`callback_url`	string	Yes	HTTPS URL to receive the webhook after all signers complete
`signers`	array	Yes	Ordered list of signers; signing is sequential in this order
`template_id`	string	No	Create from a reusable template instead of inlining field coordinates
`expires_in`	integer	No	Days until the request expires if unsigned (default 30) — see lifecycle

Signer object

Field	Type	Required	Description
`name`	string	Yes	Full name of the signer (appears in the UI and audit trail)
`email`	string	Yes	Email address for identity verification and ceremony link delivery
`fields`	array	Yes	One or more signature field definitions

Field object

Field	Type	Required	Description
`page`	integer	Yes	1-based page number within the document
`x`	number	Yes	Left edge in PDF points from page left
`y`	number	Yes	Top edge in PDF points from page top
`w`	number	Yes	Width in PDF points
`h`	number	Yes	Height in PDF points
`type`	string	Yes	One of `signature`, `initials`, `date`, `checkbox`, `text` — see field types
`required`	boolean	Yes	Whether the signer must complete this field to submit
`label`	string	No	Label for a `text` field
`max_length`	integer	No	Maximum length for a `text` field

Response

201 Created

{
  "id": "sr_...",
  "status": "pending",
  "signing_url": "https://your-nosign-host/sign/...",
  "expires_at": "2026-06-14T13:00:00Z"
}

Field	Description
`id`	Signing request identifier for status polls and the subsequent DELETE call
`status`	Current status (`pending`, `in_progress`, `completed`, `declined`, `expired`) — see lifecycle
`signing_url`	One-time link for signer #1 — deliver this through your platform
`expires_at`	ISO 8601 timestamp after which the request expires if not completed

Poll a request’s current state and per-signer status at any time with GET /v1/signing-requests/{id} — see lifecycle.

Error responses

Status	Cause
`401`	Missing or invalid API key
`422`	Invalid payload — field coordinates out of bounds, missing required fields, or malformed JSON

← Legal class Templates