MacoSign for developers
Agreements as an API
A versioned REST API, scoped keys, signed webhooks and embedded signing, so your product can send, sign and verify agreements without anyone leaving your app.
REST API v1
Predictable JSON resources for documents, templates, envelopes, recipients, fields, downloads, usage and verification. OpenAPI 3.1 spec included.
Scoped keys
documents:read, envelopes:write and more. Keys act for the member who created them and never exceed their role.
Idempotent by design
Signing actions take an Idempotency-Key header, so retries never sign twice.
Signed webhooks
HMAC-SHA256 with timestamps, seven retries with backoff, delivery logs and one-click redelivery.
Embedded signing
Short-lived signing URLs that can only be framed by the HTTPS origins you register.
Clear errors
Stable error codes such as not_your_turn, limit_reached and envelope_not_ready, with details.
Quick start
Send your first envelope
- 1Create a test keySettings → API & webhooks → New key. Choose the scopes you need.
- 2Upload a documentPOST /documents (multipart). Poll until status is ready.
- 3Create and sendPOST /envelopes with recipients and fields, then POST /envelopes/{id}/send.
- 4Listen for completionSubscribe to envelope.completed and download the signed PDF and certificate.
Create an envelope
POST /api/v1/envelopes
Authorization: Bearer msk_test_…
Content-Type: application/json
{
"title": "Order form #1042",
"documents": ["01j9w3…"],
"recipients": [
{ "ref": "c", "name": "Ada Okafor", "email": "ada@example.com", "role": "signer" }
],
"fields": [
{ "recipient_ref": "c", "document_id": "01j9w3…", "type": "signature",
"page": 1, "x": 0.12, "y": 0.78, "width": 0.3, "height": 0.06 }
]
}Verify webhook signatures
// Node.js — verify a MacoSign webhook
import crypto from "node:crypto";
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (Math.abs(Date.now() / 1000 - t) > 300) return false; // replay window
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return header.split(",").filter((p) => p.startsWith("v1="))
.some((p) => crypto.timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(expected)));
}Webhooks
React to every agreement event
envelope.sent, recipient.viewed, recipient.signed, recipient.declined, envelope.completed, envelope.expired, envelope.cancelled and subscription.updated.
- Payloads never include signing links, storage paths or IP addresses.
- Use the event id to de-duplicate: delivery is at-least-once.
Embedded signing
Keep customers inside your product
Request a signing URL for the recipient whose turn it is, pass your HTTPS origins, and render it in an iframe. The URL expires in minutes and refuses to load anywhere else.
POST /envelopes/{id}/recipients/{recipientId}/embedded-session
{ "allowed_origins": ["https://portal.example.com"] }
Start building today
API access is included on Business and Enterprise plans. Test keys let you integrate safely before going live.