Skip to content
New: Agreement Copilot explains contracts in plain language, with every answer cited.

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.

01

REST API v1

Predictable JSON resources for documents, templates, envelopes, recipients, fields, downloads, usage and verification. OpenAPI 3.1 spec included.

02

Scoped keys

documents:read, envelopes:write and more. Keys act for the member who created them and never exceed their role.

03

Idempotent by design

Signing actions take an Idempotency-Key header, so retries never sign twice.

04

Signed webhooks

HMAC-SHA256 with timestamps, seven retries with backoff, delivery logs and one-click redelivery.

05

Embedded signing

Short-lived signing URLs that can only be framed by the HTTPS origins you register.

06

Clear errors

Stable error codes such as not_your_turn, limit_reached and envelope_not_ready, with details.

Quick start

Send your first envelope

  1. 1Create a test keySettings → API & webhooks → New key. Choose the scopes you need.
  2. 2Upload a documentPOST /documents (multipart). Poll until status is ready.
  3. 3Create and sendPOST /envelopes with recipients and fields, then POST /envelopes/{id}/send.
  4. 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.