Recipes

Common shapes integrators ship. Each is a real call sequence with the corner cases called out. Every URL is on the canonical host https://api.wesign.now/v1; its alias works identically.

Document automation tool → wesign.now

Pattern: Your Portant / DocAssemble / Pandoc / LaTeX pipeline generates the PDF; wesign.now sends it for signature.

<!-- HTML→PDF template -->
<p>Tenant signature: [[ls:signature:tenant]]</p>
<p>Date: [[ls:date:tenant]]</p>

curl -X POST https://api.wesign.now/v1/signing-requests \
  -H "Authorization: Bearer $WSK_KEY" \
  -H "Idempotency-Key: ${SOURCE_DOC_ID}" \
  -F "file=@/tmp/contract.pdf" \
  -F 'signers=[
        {"email":"tenant@example.com",  "role":"tenant"},
        {"email":"landlord@example.com","role":"landlord", "phone_e164":"+41791112233", "require_sms_verification":true}
      ]' \
  -F 'callback_url=https://yourapp.com/wesign/callback'

Two-signer power of attorney from a template

Pattern: A company grants a power of attorney that two representatives sign, one after the other. The contract is a locked PDF template in your workspace; your system supplies the company's details per case. Needs the Enterprise template entitlement (GET /v1/me → capabilities.templates).

Author the template once in the app, as in the PDF track of the Template quickstart: two recipient slots, company.legal_name and company.tax_id as Sender / API boxes, signing.place and signing.place_s2 as Signer boxes, a signature per slot, locked.

curl -X POST https://api.wesign.now/v1/templates/$TPL_ID/instantiate \
  -H "Authorization: Bearer $WSK_KEY" \
  -H "Idempotency-Key: ZT-2026-0142-poa" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "slot": 1, "email": "anna@example.ch", "name": "Anna Muster",
        "job_title": "Geschäftsführerin", "company": "Muster AG" },
      { "slot": 2, "email": "ben@example.ch", "name": "Ben Keller",
        "job_title": "Mitglied des Verwaltungsrates", "company": "Muster AG" }
    ],
    "field_values": {
      "company.legal_name": "Muster AG",
      "company.tax_id": "DE123456789-00001"
    },
    "signing_mode": "sequential",
    "version": 3,
    "locale": "de",
    "metadata": { "case_id": "ZT-2026-0142" }
  }'

Multi-tenant platform (one key, many clients)

Pattern: You run a platform for many firms and send on their behalf.

• One workspace API key covers every document the workspace sends; hooks are per workspace, so one dashboard-registered webhook with one stable secret receives everything. Route on document_id (or on an id you keep in your own table keyed by documentId from the 201).
• If a client needs its own brand on the signing page, that is a workspace of its own with its own key — brand, hosting region and reply-to all hang off the key.
• Pin outbound fetches to api.wesign.now (or to the alias host if you deliberately use it); the signed_pdf_url field only ever names the canonical host.

Invitations from your own email provider

Pattern: Your app already sends mail through Resend, Postmark, SendGrid or Amazon SES, and the signing invitation should come from your domain, in your own design. wesign.now creates the request, hosts the signing page and seals the PDF; you send the invitation.

{
  "file_url":     "https://files.example.com/orders/order-123.pdf",
  "placement":    "auto_append",
  "signing_mode": "sequential",
  "send_emails":  false,
  "signers": [
    { "email": "jane@example.com", "role": "client",        "name": "Jane Doe" },
    { "email": "sam@example.com",  "role": "countersigner", "name": "Sam Lee" }
  ],
  "metadata": { "order_id": "order-123" }
}

// Called after verifyWeSignSignature passed and the event id is new
// (Verifying a signature → Node.js). Throwing answers non-2xx: we redeliver.
import { Resend } from 'resend'
import { SignInvite } from './emails/sign-invite' // your React Email template

const resend = new Resend(process.env.RESEND_API_KEY!)

export async function onSigningRequestSent(event: {
  signing_request_id: string
  source?: string
  emailed?: boolean
  metadata: { order_id?: string } | null
}) {
  // The first signer's invitation went out right after the create call.
  if (event.source !== 'sequential_release' || event.emailed !== false) return

  const res = await fetch(
    `https://api.wesign.now/v1/signing-requests/${event.signing_request_id}`,
    { headers: { Authorization: `Bearer ${process.env.WSK_KEY}` } },
  )
  if (!res.ok) throw new Error(`wesign.now ${res.status}`)
  const { status, signer, signingUrl } = await res.json()
  if (status !== 'pending' && status !== 'viewed') return // withdrawn or expired meanwhile

  const { error } = await resend.emails.send(
    {
      from: 'Acme <contracts@acme.example>',
      to: signer.email,
      subject: 'Your turn to sign',
      react: SignInvite({ url: signingUrl }),
    },
    { idempotencyKey: `${event.metadata?.order_id}/invite/${event.signing_request_id}` },
  )
  if (error) throw new Error(error.message)
}

What still comes from us:

• The workspace's automatic reminders, from our sending address, by default 7 and 14 days after the request was created. A later signer in a sequential send is counted from that moment too, not from their turn, so they can get the first reminder within a day of your invitation. They follow the workspace's reminder settings (Settings → Signing); switching them off applies to every document of the workspace.
• The completion emails.
• The SMS code, when a signer has to verify by SMS: the signer asks for it on the signing page (Second factor by SMS).
• The signing page (on your workspace's subdomain) and the confirmation after signing. There is no redirect back to your app.

There is no sandbox: test with addresses you control, then withdraw the request (Testing without a sandbox).

Zapier / no-code triggers

Pattern: A Google Form / Typeform / Notion entry triggers a signing.

Without an SDK you can stitch this with Zapier's "Webhooks by Zapier" app, which Zapier does not offer on its free plan:

1. Trigger: form submission.
2. Action 1: pull the PDF (Google Drive download).
3. Action 2: Webhooks by Zapier's POST action to https://api.wesign.now/v1/signing-requests, with the PDF from action 1 in a field named file and signers as a JSON string, which we parse as JSON. Not Custom Request: Zapier's help states that it cannot send file objects. Check the first run's response for a 201 with documentId.
4. Action 3: log the response in a Google Sheet for audit.

If the PDF already sits at a URL we can fetch directly (https or http, no redirects, ≤ 25 MB), skip the binary step: send JSON with file_url instead of a file part — Custom Request can send that. A Google Drive download link answers with a redirect, which file_url refuses (redirect_not_allowed), so a Drive file goes up as bytes.

Most no-code platforms throttle long-running steps — the multipart upload may take >10s for large PDFs. Set an Idempotency-Key header from the trigger (the form submission's id) and a retry from Zapier's built-in error handler replays the first response instead of sending twice. Without the header, every retry is a new send.

Agent-generated PDFs

Pattern: An AI agent (Claude tool-use, OpenAI function-calling, LangChain/LangGraph) produces a draft contract and ships it for signature without human-in-the-loop review.

Have the agent emit role-tagged anchors — [[ls:signature:client]] — into the draft and send with placement="anchors". The anchor is placed where the signature belongs by construction, so there is no "signature box on page 3 paragraph 4" failure mode. For fully programmatic layouts, placement="explicit" takes exact coordinates.

placement="manual" (a human-review placement URL) was retired on 2026-07-31 — requests using it receive 400 placement_retired. Keep the human in the loop before the send instead: generate, review, then dispatch with anchors — or stage a template instance for review.

CRM sync (Salesforce / HubSpot / Attio)

Pattern: A Closed-Won opportunity triggers a contract send; contract status updates back to the CRM record.

1. Webhook from CRM fires when stage flips to "Closed-Won".
2. Your handler builds the PDF (template + opportunity field values).
3. POST to https://api.wesign.now/v1/signing-requests with callback_url pointing back at your handler.
4. On signing_request.signed, update the CRM custom field signed_at. On document.completed, archive the signed PDF + the audit trail in the CRM Notes / Files tab.

X-WeSign-Event-Id is your dedup key on the receiver side — at- least-once delivery means retries occasionally re-fire the same event. (The same value also arrives as X-LetsSign-Event-Id.) For document.completed, deduplicate on document_id too: a database failure at the moment of completion can repeat it with a new id.

Building your own

Three rules of thumb:

• Always pass an Idempotency-Key on the create calls — POST /v1/signing-requests and POST /v1/templates/{id}/instantiate. /remind does not take one and re-sends on every call, so debounce it yourself.
• Verify webhook signatures. Skipping this is the #1 incident pattern; an attacker can forge signing_request.signed and your handler updates a CRM with bogus state. Node and PHP snippets are in Verifying a signature.
• Store the signed PDF yourself. Pull it once on document.completed and keep it: a workspace can have signed PDFs deleted after a set number of days, after which /signed answers 410 deleted_by_retention for good. Don't re-fetch it on every dashboard view either. See Retrieve the signed document.