Signing Requests

A signing request invites a specific person (by email) to review and sign a document version. The signer receives an email with a unique, time-limited link — no account required.

Status Values

Status	Description
PENDING	Invitation sent, signer has not yet opened it
ACCEPTED_FULL	Signer accepted all clauses
ACCEPTED_PARTIAL	Signer accepted some optional clauses and rejected others
REJECTED	Signer rejected one or more mandatory clauses
VOIDED	Manually voided before completion
EXPIRED	Token expired before the signer completed

Endpoints

Method	Path	Description
GET	/api/v1/signing-requests	List with filters and pagination
POST	/api/v1/signing-requests	Create a signing request
GET	/api/v1/signing-requests/:id	Get a signing request

---

List signing requests GET

GET /api/v1/signing-requests

Query parameters:

Parameter	Type	Default	Description
status	enum	—	Filter by status (see table above)
versionId	UUID	—	Filter to a specific document version
search	string	—	Search by signer name or email (max 200 chars)
dateRange	enum	—	7d, 30d, or 90d
sortBy	enum	created_at	created_at, signer_name, or status
sortDir	enum	desc	asc or desc
limit	number	25	Results per page (1–100)
offset	number	0	Pagination offset

Response 200:

{
  "data": [
    {
      "id": "018e1234-abcd-7000-8000-000000000030",
      "version_id": "018e1234-abcd-7000-8000-000000000020",
      "signer_name": "Jane Doe",
      "signer_email": "jane@example.com",
      "status": "ACCEPTED_FULL",
      "token": "abc123...",
      "created_at": "2026-02-01T09:00:00.000Z",
      "expires_at": "2026-03-01T09:00:00.000Z",
      "completed_at": "2026-02-10T14:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 25,
    "offset": 0
  }
}

---

Create a signing request POST

POST /api/v1/signing-requests

Sends a signing invitation email to the specified address. The version must be ACTIVE.

Request body:

Field	Type	Required	Constraints
versionId	UUID	Yes	Must be an ACTIVE document version
signerName	string	Yes	Min 1 character
signerEmail	string	Yes	Valid email address

{
  "versionId": "018e1234-abcd-7000-8000-000000000020",
  "signerName": "Jane Doe",
  "signerEmail": "jane@example.com"
}

Response 201:

{
  "data": {
    "id": "018e1234-abcd-7000-8000-000000000030",
    "version_id": "018e1234-abcd-7000-8000-000000000020",
    "signer_name": "Jane Doe",
    "signer_email": "jane@example.com",
    "status": "PENDING",
    "token": "abc123def456...",
    "created_at": "2026-02-21T10:00:00.000Z",
    "expires_at": "2026-03-21T10:00:00.000Z",
    "completed_at": null
  }
}

Error cases:

Status	Code	Cause
400	BAD_REQUEST	Invalid email, missing fields
401	UNAUTHORIZED	Missing or invalid API key
404	NOT_FOUND	versionId not found or not ACTIVE
409	CONFLICT	A pending request already exists for this email + version

Note

The signing link in the email is valid for the expiry_days set on the document version. After expiry, the request status transitions to EXPIRED and the link no longer works.

---

Get a signing request GET

GET /api/v1/signing-requests/:id

Returns full details including clause-level responses if the signing is complete.

Response 200:

{
  "data": {
    "id": "018e1234-abcd-7000-8000-000000000030",
    "version_id": "018e1234-abcd-7000-8000-000000000020",
    "signer_name": "Jane Doe",
    "signer_email": "jane@example.com",
    "status": "ACCEPTED_PARTIAL",
    "token": "abc123...",
    "assent_map": {
      "018e0001-aaaa-7000-8000-000000000001": true,
      "018e0002-bbbb-7000-8000-000000000002": false
    },
    "rejection_note": null,
    "expires_at": "2026-03-01T09:00:00.000Z",
    "completed_at": "2026-02-10T14:30:00.000Z",
    "is_superseded": false,
    "created_by": "018e0000-user-7000-8000-000000000001",
    "created_at": "2026-02-01T09:00:00.000Z",
    "updated_at": "2026-02-10T14:30:00.000Z",
    "version": {
      "version_number": 1,
      "document": {
        "id": "018e1234-abcd-7000-8000-000000000010",
        "name": "Privacy Policy"
      }
    }
  }
}

Tip

assent_map keys are clause UUIDs. true means the signer accepted the clause; false means rejected. The field is null for signing requests that have not yet been completed.

Error cases:

Status	Code	Cause
401	UNAUTHORIZED	Missing or invalid API key
404	NOT_FOUND	Signing request not found in this organisation