API documentation

Send a PDF or a filled template for signature over one REST API. The wesign.now API reference, guides, errors and support.

The whole signing flow — anchors, signers, dispatch, signed PDF, audit trail, webhooks — sits behind one REST API at https://api.wesign.now/v1, authenticated with a Bearer API key. No templates required, no portal redirect for the recipient, no SDK to install.

The Base URL section says exactly what is — and what isn't — the contract.

Four steps to ship

Get your API key

1. Sign up free.
2. Open Settings → API and switch Developer settings on.
3. Settings → API → Create API key.
4. Call GET /v1/me with the key. It sends nothing and shows the key works.

Copy the wsk_live_… token into WESIGN_API_KEY, the name every sample on this site reads — we only display the plaintext once. Keys minted before September 2026 start with lsk_live_ and keep working unchanged. Every plan gets a key, with a monthly cap on the documents you create through the API:

Free: 10 documents a month, the plan's own cap
Branded: 100 documents a month through the API
Enterprise: no cap

Check the key — this call sends nothing

GET /v1/me creates nothing and emails no one. A 200 names the key's workspace and what it may use (capabilities); a 401 says what to fix.

# Paste the full key — the dashboard only shows its prefix
export WESIGN_API_KEY="wsk_live_…"

# Sends nothing: checks the key and names its workspace
curl https://api.wesign.now/v1/me \
  -H "Authorization: Bearer $WESIGN_API_KEY"
# 200 → { "workspace": { … }, "key": { … }, "capabilities": { … }, … }

Send your first signing request

Two signers with distinct roles — the role is how a signature field finds its signer. placement=auto_append adds a signature page, so any PDF works:

# Paste the full key — the dashboard only shows its prefix
export WESIGN_API_KEY="wsk_live_…"

curl -X POST https://api.wesign.now/v1/signing-requests \
  -H "Authorization: Bearer $WESIGN_API_KEY" \
  -H "Idempotency-Key: quickstart-$(date +%s)" \
  -F "file=@contract.pdf" \
  -F "placement=auto_append" \
  -F 'signers=[
        { "email": "anna.muster@example.com",
          "name": "Anna Muster", "role": "counterparty" },
        { "email": "you@example.com",
          "name": "Your name", "role": "company" }
      ]'
# 201 → { "documentId": "…", "signers": [
#   { "role": "counterparty", "signingUrl": "…", "emailed": true },
#   { "role": "company",      "signingUrl": "…", "emailed": true } ] }
# Every answer carries an X-Request-Id header: quote it to
# support@wesign.now when something is off.

Every key is live — there is no sandbox yet — so this sends real invitations: use addresses you own, and see Testing without a sandbox.

To place the fields yourself, put [[ls:signature:counterparty]] and [[ls:signature:company]] where each signature belongs and send placement=anchors — see Placement modes. Need a signer to confirm an SMS code before they can sign? Add phone_e164 and require_sms_verification to the signer — see Second factor by SMS, and SMS verification for the whole flow.

(Optional) Receive real-time events

Register a receiver once with POST /v1/hooks (or at Settings → API → Webhooks, or per request with callback_url). Send "payload": "minimal" for identifiers only, without personal data. We POST signing_request.signed as each signer completes, and document.completed with key-authenticated URLs of the signed PDF and the audit trail when everyone's done. Every delivery is HMAC-signed (X-WeSign-Signature) — verify it before trusting the body — and POST /v1/hooks/{id}/test sends a signed ping to check your endpoint.

Sending contracts you author once in the app? The Template quickstart goes from a template to a sealed PDF: a one-signer rich-text letter, or a PDF two people sign in order. An app that asks its users for the values first follows Prepare a fill in your app: read the template's contract, ask, dry-run with validate_only, then send.

What's in this site

Quickstart

Your own PDF to a sealed, signed PDF in five minutes, terminal only.

Template quickstart

Author a template in the app, fill it over the API, follow two signers in order, download the result.

API overview

Base URL, versioning, the map of v1 resources.

OpenAPI spec

The machine-readable contract — import it into Postman, Insomnia or a client generator.

Authentication

Bearer keys, key format, rotation, error shape.

Create a signing request

The big endpoint. Multipart or JSON, signers, placement, SMS second factor. Read one signer, remind, withdraw.

Placement modes

Anchors, auto-append, or explicit coordinates — and why manual placement is retired.

Documents

GET a document and its signers, signed-PDF download, audit-trail PDF.

Templates

Instantiate a locked template with field_values; stage for review first.

Prepare a fill in your app

Read a template's contract, ask your user for what it needs, dry-run, then send.

Webhooks

Events we emit, signature verification in Node and PHP, retry semantics.

Idempotency

Safely retry network blips without double-sending.

Rate limits

60 requests/minute per API key. Retry-After on 429.

Errors

Stable error codes mapped to HTTP statuses.

Security

Encryption at rest and in transit, signature evidence, webhook signing.

How verification works

Hash lookup, PAdES validation, eIDAS QES detection, trust scope.

For AI assistants

Building the integration with an AI assistant or coding agent? Give it these instead of pasted pages. The two text files are generated from this site's source on every deploy, so they always match the pages.

Tell your assistant three things: there is no sandbox (every key is live and sends real email and SMS; test with validate_only, review: true and send_emails: false); the exact shapes are in the OpenAPI spec; there is no SDK, so it generates a client from the spec or calls the REST API directly. An agent that should send and track documents itself connects to the MCP server with your API key; it never signs.