Signing requests

Create, read, remind, and withdraw — the four endpoints around the signing_request resource.

A signing request is one signer's row on a document. A document with two signers has two signing requests; with five signers, five. Each carries a status, an expiry, an audit log, and a unique signing URL the signer clicks to sign.

Create

POST https://api.letssign.now/v1/signing-requests

The big one — uploads the PDF, places the fields, dispatches the emails, and returns a per-signer URL list. Multipart upload because the PDF rides as a binary form field.

Request body

Field	Type	Required	Description
`file`	multipart	✓	The PDF to sign. ≤ 25 MB.
`signers`	`Signer[]`	✓	1–20 entries. See Signer object.
`placement`	`"anchors" \| "auto_append" \| "manual" \| "explicit"`		Default `anchors` with fallback to `auto_append`. See Placement modes.
`fields`	`Field[]`		Required when `placement="explicit"`.
`observer_emails`	`string[]`		0–20 CC-style recipients.
`callback_url`	`string`		Per-request webhook override. HMAC-signed.
`signing_mode`	`"parallel" \| "sequential"`		Default `parallel`.
`locale`	`"en" \| "de"`		Default email + UI language.
`expires_in_days`	`int 1..90`		Default 14. Per-link TTL.
`placement_assignee_email`	`string`		Only for `placement="manual"`.

Signer object

Field	Type	Required	Description
`email`	`string`	✓	Where the invite goes.
`role`	`string`	✓	`[a-z][a-z0-9_-]{0,40}`. Must match an anchor placeholder when `placement="anchors"`.
`name`	`string`		Display name. Auto-fills the typed-signature default.
`role_label`	`string \| { en, de }`		Human-readable label shown in emails + UI.
`locale`	`"en" \| "de"`		Override request-level locale.
`signing_order`	`int ≥ 1`		Only when `signing_mode="sequential"`.

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "documentId":      "8a1e4f9a-…",
  "status":          "pending",
  "placement":       "anchors",
  "presentedSha256": "4f9a…d21c",
  "anchors":         { "found": 4, "fields": 4 },
  "signers": [
    { "role": "tenant",   "email": "tenant@example.com", "status": "pending", "signingUrl": "…", "signingRequestId": "…" },
    { "role": "landlord", "email": "owner@example.com",  "status": "pending", "signingUrl": "…", "signingRequestId": "…" }
  ],
  "observers": [],
  "callback":  {
    "url":    "https://yourapp.com/letssign/callback",
    "secret": "whsec_…",
    "note":   "Store this secret. We do not display it again."
  }
}

When placement="manual" is used, the response is HTTP 202 instead of 201, includes a placementUrl + placementToken, and the per-signer list comes back with status="awaiting_placement". Signing requests are created when the placer hits Send — see Placement modes.

Read one signer

GET https://api.letssign.now/v1/signing-requests/{id}

Status, signing URL, and the last 50 audit events for a single signer. Use this when you want a tight poll loop on one recipient without re-fetching the whole document.

{
  "id":         "11111111-…",
  "documentId": "8a1e4f9a-…",
  "signer":     { "email": "tenant@example.com", "name": null, "role": "tenant", "order": null },
  "status":     "viewed",
  "locale":     "en",
  "channel":    "email",
  "expiresAt":  "2026-05-13T10:30:00Z",
  "createdAt":  "2026-04-29T10:30:00Z",
  "signingUrl": "https://yourco.letssign.now/en/sign/abc…",
  "auditEvents": [
    { "type": "email_sent", "createdAt": "2026-04-29T10:30:01Z", "meta": { "to": "…" } },
    { "type": "viewed",     "createdAt": "2026-04-29T10:32:08Z", "meta": null }
  ]
}

For a doc-level view of all signers, see GET document.

Remind

POST /v1/signing-requests/{id}/remind

Re-send the original invite email. Allowed only while the request is pending or viewed and not yet expired. Empty request body. The audit trail records the API key as the actor.

200 OK    { "ok": true }
409 Conflict    { "error": "Cannot remind a signed request", "code": "invalid_state" }
409 Conflict    { "error": "Request has expired", "code": "expired" }

Withdraw

POST /v1/signing-requests/{id}/withdraw

Cancel an in-flight signing request. Status flips to withdrawn — subsequent reminder/withdraw calls return 409, and the signing URL no longer accepts signatures. In sequential mode, queued downstream signers stay queued until you withdraw or resend them too.

200 OK    { "ok": true }
409 Conflict    { "error": "Cannot withdraw a signed request", "code": "invalid_state" }

Both remind and withdraw are also available on the in-app UI under Documents → details. The API endpoints share business rules with the UI flow — same status gates, same audit-event shape.