Signing requests

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

The big one — uploads the PDF, places the fields, dispatches the emails (and SMS, if asked), and returns a per-signer URL list. Multipart when the PDF rides as a binary form field; JSON when you point us at a URL.

Request body

Send the PDF one of two ways:

• multipart/form-data with a file part (the JSON fields ride as form fields), or
• application/json with a file_url — we fetch the PDF server-side (SSRF-guarded: https/http only, no private hosts, no redirects, ≤ 25 MB).

Field object (placement="explicit")

// "Point us at a PDF, place a signature by its centre, require an SMS code, send" — one JSON call:
{
  "file_url": "https://your-dms.example.com/contracts/42.pdf",
  "placement": "explicit",
  "fields": [
    { "page": 2, "x": 0.70, "y": 0.65, "w": 0.18, "h": 0.06, "kind": "signature", "role": "client", "origin": "center" }
  ],
  "signers": [
    { "role": "client", "email": "sara@acme.ch", "name": "Sara Buyer", "phone_e164": "+41791112233", "require_sms_verification": true }
  ]
}

Signer object

Second factor by SMS

Yes — a signer can be required to confirm an SMS code. Two fields on the signer, one rule:

Validation rule: require_sms_verification: true without a phone_e164 is rejected before anything is created — 400 invalid_request, and the error text names the rule: phone_e164 is required when require_sms_verification is true. A number that isn't E.164 fails the same way (phone must be E.164). A phone_e164 on its own, without the flag, is stored on the request but the invite still goes out by email and no code is sent.

What the signer experiences: they open their signing link as usual, and before the document is shown we text a one-time code to phone_e164. They enter it, and only then can they sign. The check is recorded on the audit trail, and the resulting signature is classed as an advanced electronic signature (AES) rather than the simple (SES) email-link level — the same distinction you see in the dashboard. It is available on every plan, subject to the workspace's monthly SMS allowance.

{
  "signers": [
    {
      "role": "tenant",
      "email": "tenant@example.com",
      "name": "Ann Tenant",
      "phone_e164": "+41791112233",
      "require_sms_verification": true
    }
  ]
}

The same two fields exist on POST /v1/documents/{id}/confirm for staged template instances.

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/wesign/callback",
    "secret": "whsec_…",
    "note":   "Store this secret. We do not display it again. …"
  }
}

callback is only present when you passed callback_url. The secret is the HMAC key for that document's deliveries and is shown exactly once.

signingUrl lives on the workspace's signing host (https://yourco.letssign.now/en/sign/… for branded workspaces) — only the API host is api.wesign.now.

Read one signer

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

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. Every accepted call sends another email — this endpoint does not take an Idempotency-Key, so guard retries on your side.

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

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" }