API reference

Overview

The base URL is https://api.pactivo.com/v1. All requests and responses are JSON. Every capability the console has is available here — it authenticates against the same API.

An envelope is one signing request: one or more documents, the recipients who act on them, and the fields they complete.

Authentication

Authenticate with a secret API key as a bearer token. Create and revoke keys in the console under Developers → API keys; the full key (starting pk_) is shown once. Keys are scoped to your organisation and carry your role’s permissions.

Authorization: Bearer pk_live_…

Create an envelope

Upload document(s), add recipients, and place fields. Set identity to require Certivus verification, and verification to email_otp for a one-time code.

curl https://api.pactivo.com/v1/envelopes \
  -H "Authorization: Bearer pk_live_…" \
  -F document=@engagement-letter.pdf \
  -F 'title=Client engagement letter' \
  -F 'signer[name]=Eleanor Hartley' \
  -F 'signer[email]=eleanor@hartley.co.uk' \
  -F 'verification=email_otp'

Send for signature

Freezes the documents (with a recorded checksum) and emails each recipient their secure signing link, respecting the signing order (sequential or any).

Retrieve & list

List and filter envelopes, fetch one with its recipients and status, or pull the full tamper-evident audit trail (the SHA-256 hash chain) as structured events.

Download artifacts

Once complete, download the signed PDF (carrying a PAdES digital signature and RFC-3161 timestamp) and the evidence certificate. Each is fingerprinted with SHA-256, so any later tampering is detectable.

Manage in flight

Nudge a pending recipient, fix a mistyped recipient email (the old link is revoked and a fresh one re-sent), or void an envelope you no longer need. Terminal states — completed, declined, voided, expired — are immutable.

Webhooks

Register an https:// endpoint in the console (Developers → Webhooks) to receive events. Verify every delivery: each request carries an X-Pactivo-Signature — an HMAC of {timestamp}.{body} — and an X-Pactivo-Timestamp; reject stale timestamps and mismatched signatures. Failed deliveries retry with backoff.

const sig = crypto.createHmac("sha256", endpointSecret)
  .update(`${req.headers["x-pactivo-timestamp"]}.${rawBody}`)
  .digest("hex");
if (sig !== req.headers["x-pactivo-signature"]) reject();

SDKs

An embeddable component inherits your app’s colour, type and radius and completes signing in place — no redirect, no Pactivo branding unless you want it. Reach for the API for server-side flows, the SDK for in-app signing.