api reference · v1

The Usign REST API.

A predictable, versioned, Stripe-style API. Every resource is JSON over HTTPS. Idempotency keys are built in. Base URL:

https://api.usign.upfluence.com/v1

Authentication

Authenticate with a workspace API key in the Authorization header. Keys are scoped to one workspace and never expire until revoked.

curl https://api.usign.upfluence.com/v1/contracts \
  -H "Authorization: Bearer sk_live_…"

The two-phase model

Create never sends. POST /v1/contracts always returns a draft. Email is dispatched only by POST /v1/contracts/:id/send. There is no single call that creates and sends, by design.

Contracts

POST /v1/contracts

Create a contract. Always returns a draft. Pass dispatch:false (the default) — sending is a separate call.

{ "template_id": "tpl_creator_v4",\n  "signer": "maya@studio.co",\n  "fields": { "fee_amount": 2500 },\n  "external_reference": "deal_4821" }\n\n→ 201 · { "id": "ctr_8fK2a", "status": "draft" }

POST /v1/contracts/:id/send

The deliberate send. Mints signing tokens and dispatches the signer email. This is the only call that sends.

→ 200 · { "id": "ctr_8fK2a", "status": "sent",\n         "sent_at": "2026-05-27T14:02:00Z" }

GET /v1/contracts/:id

Retrieve a contract with its current status and full audit trail.

→ 200 · { "id": "ctr_8fK2a", "status": "completed",\n         "audit": [ … ] }

GET /v1/contracts

List and filter contracts by status, signer, or external_reference. Cursor-paginated.

→ 200 · { "data": [ … ], "next_cursor": "ctr_…" }

POST /v1/contracts/:id/void

Void a contract. A reason is required and recorded in the audit log.

{ "reason": "wrong fee amount" }\n\n→ 200 · { "id": "ctr_8fK2a", "status": "voided" }

Templates

Templates are immutable per version. List them, fetch one, and inspect its merge-field registry before drafting.

GET/v1/templates

→ 200 · [
  { "id": "tpl_creator_v4", "name": "Creator Agreement", "version": 4 },
  { "id": "tpl_nda_v2", "name": "NDA", "version": 2 }
]

Webhooks

Every lifecycle event POSTs an HMAC-signed payload to your endpoint, carrying the external_reference you supplied at creation. Verify the Usign-Signature header against your signing secret.

{
  "event": "contract.completed",
  "contract_id": "ctr_8fK2a",
  "external_reference": "deal_4821",
  "status": "completed",
  "sealed_pdf_url": "https://…/ctr_8fK2a.pdf"
}