Developers

API reference

Create envelopes, send them for signature, and collect court-grade proof — over a small, predictable REST API. The console is just one client of it.

Overview

The base URL is https://oesufgbdyhacjbvlvxfl.supabase.co/functions/v1/envelope-api. All requests and responses are JSON. Every capability the console has is available here — it authenticates against the same API. Errors are always { "error": "…" } with a 4xx/5xx status.

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

The full machine-readable contract is published as an OpenAPI 3.1 spec — generated from the deployed code, not aspiration.

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

POST/envelopes

One JSON body: base64-encoded PDF documents (max 15 MB each, 40 MB per envelope), recipients, and fields placed by index into those two arrays. Set verification to require an emailed one-time passcode before each signer can open the document. Invalid input is rejected before any writes — you never get a half-built envelope.

BASE=https://oesufgbdyhacjbvlvxfl.supabase.co/functions/v1/envelope-api

curl "$BASE/envelopes" \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Client engagement letter",
    "recipients": [
      { "name": "Eleanor Hartley", "email": "eleanor@hartley.co.uk" }
    ],
    "documents": [
      { "file_name": "engagement-letter.pdf",
        "content_base64": "'"$(base64 -i engagement-letter.pdf)"'" }
    ],
    "fields": [
      { "document_index": 0, "recipient_index": 0, "type": "signature",
        "page": 1, "x": 0.62, "y": 0.78, "width": 0.28, "height": 0.06,
        "required": true }
    ],
    "verification": { "required": true, "type": "otp_email" }
  }'

Returns 201 with the envelope in prepared — nothing is emailed until you send it.

Send for signature

POST/envelopes/{id}/send

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

Retrieve & list

GET/envelopes

GET/envelopes/{id}

GET/envelopes/{id}/audit

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

GET/envelopes/{id}/signed-pdf

GET/envelopes/{id}/certificate

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

POST/envelopes/{id}/remind

POST/envelopes/{id}/correct

POST/envelopes/{id}/void

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();

envelope.sentAn envelope is sent

envelope.viewedA recipient opens it

envelope.recipient_signedA recipient signs

envelope.completedEveryone has signed

envelope.declinedA recipient declines

envelope.expiredIt expires unsigned

envelope.voidedYou void it

envelope.artifacts_readySigned PDF + certificate sealed

envelope.artifacts_failedSealing failed (needs attention)

Rajoka Connect

Portfolio apps don’t need to hold a Pactivo API key. Pactivo is a resource server on Rajoka Connect: your app requests access with OAuth 2.0 (Authorization Code + PKCE), the workspace owner approves the exact scopes on Connect’s consent screen, and the minted access token calls this same API — same routes, same shapes.

pactivo.envelopes:readList and read envelopes, audit trails, and artifacts

pactivo.envelopes:manageCreate, send, remind, correct, and void envelopes

Access is revocable by the workspace owner at any time from Connect’s Connections page, and every resource server re-checks the token, so revocation takes effect within a minute.

Embedded signing

Today, signers complete the ceremony on Pactivo’s hosted, mobile-first signing page — your app creates and sends over the API, then listens for webhooks. An in-app embedded signing surface (an isolated frame your code can’t reach into, because the integrity of what the signer saw is the product) is on the roadmap; it is not available yet. If you need it, tell us: hello@pactivo.com.

Get your API key

Create a key in the console and send your first envelope.

Start signing