Send agreements from your own software

Overview

Base URL https://api.airesdocs.com/api/v1. JSON in, JSON out, over HTTPS. Authenticate with an API key created in Settings → API keys. For server-to-server use without keeping the key on the server, register a public key against it (RS256 or ES256) and exchange a short signed JWT at POST /api/v1/oauth/token (grant type urn:ietf:params:oauth:grant-type:jwt-bearer) for a one-hour token that acts as that key, with the same or fewer scopes. Most integrations need three things: create a contract from a template, send it, and receive the contract.completed webhook. Everything your integration does is recorded in the contract's audit trail like any other action, and the sealed file, certificate and public verification are the same as for contracts sent by hand.

Authentication and scopes

Send the key as Authorization: Bearer ad_live_…. Keys are shown once and stored hashed; each has a recognisable prefix, a last-used time and can be revoked instantly. Scopes limit what a key can do:

A key acts for the person who created it, and only they can see, change or revoke it. On Team, contracts a key creates belong to the team like any other. GET /api/v1/me tells you which account and scopes a key has.

Contracts

A create request from a template looks like the example above: a title, the templateId, one entry per role with name and email (and optionally its roleKey, otherwise roles are filled in order, plus phone, language, identity method and a private message), prefill values keyed by field key or label, and send: true. The contract is made exactly as Use template makes it in the app: every file in the template, every field with its rules, and the template's locked fields. Locked fields, and the fields they depend on, cannot be pre-filled, fields cannot be added to a template contract, and a draft whose locked field was changed is refused when it is sent. Send a file together with the templateId to use the template's fields on a document of your own: fields the template placed by text (anchors) are found again on the new file, the rest keep their page and position. For a contract made from a template, each recipient's role and signing order come from the template role they fill, not from role or order in the request. The response is the contract with its ID, status and recipients. Signature, initials, date-signed, name, email, attachment and stamp fields belong to the signer and cannot be pre-filled; GET /api/v1/templates marks every field that can.

Collecting a payment. Add payment to the create request: { "amountMinor": 95000, "currency": "GBP", "description": "Deposit", "recipient": 0 }, where recipient is the index of the signer who pays. mode can be fixed (the default), optional or adjustable (with minMinor and maxMinor, the signer chooses the amount). Payments need Pro or Team and your Stripe account connected in Settings, Payments; if anything is missing the request is refused and nothing is created.

Signing in person. Give a recipient the role in_person: they are not emailed. When it is their turn, call POST /api/v1/contracts/{id}/recipients/{rid}/in-person and open the URL it returns on the tablet or laptop in front of them.

Templates

Most teams create and edit templates in the app, where the people who own the agreement can place fields and set routing. An integration can also create one from a PDF with POST /api/v1/templates: the roles, each field's role, type and position (fractions of the page), and settings such as the default subject and expiry. It is checked exactly as the app checks it, and plan limits apply. Each field has a stable key: pre-fill by that key (or by the field's label) when you create a contract.

Bulk send

Send one template to many people: POST /api/v1/bulk with the templateId and either rows (one per contract: the people by role key, optional phone and accessCode, and pre-fill fields) or a csv. You get back a preview with every row checked (names, email addresses, mobile numbers in international form, access codes of 4 to 64 characters, pre-fill values); nothing is sent until you call POST /api/v1/bulk/{id}/start. To do both in one call pass start: true: it sends only when every row is valid, and otherwise answers 409 with the problems. Access codes are stored only hashed and never returned. The bulk.completed webhook tells you when a batch has finished. Bulk send needs Pro or Team and a live key.

Webhooks

Register an endpoint and choose events. Every delivery is a POST with a JSON body { id, type, created, data }, where data always carries the contractId and title, and an X-AiresDocs-Signature header (t=…,v1=…, an HMAC-SHA256 with the endpoint's secret over the time and the raw body). Verify before acting; respond with a 2xx quickly and do the work afterwards. Endpoints must be public HTTPS URLs; redirects are not followed. Each endpoint has its own secret. When you rotate it you choose how long the old one keeps working (up to 7 days); until then every delivery is signed with both, so your receiver keeps working while you switch, and you can stop the old one early.

Failed deliveries are retried six times over about a day and a half, and every attempt is logged with your endpoint's response code. Each delivery carries an ID so redeliveries are easy to ignore.

Embedded signing

Add the origins of your site to the API key, create the contract with that key and send it, then ask for a signing URL for one recipient with POST /api/v1/contracts/{id}/recipients/{rid}/embed-url. Open it in an iframe on one of those origins. Creating the URL replaces the link that was emailed to that recipient, so your page now owns their session. The signing page posts messages only to your allowed origins: { type: "airesdocs:signing", event, contractId, recipientId, status }, where event is ready, viewed, signed, declined, completed or error. Check that the message comes from the AiresDocs app origin, and confirm the final state with the API or the webhooks. Identity methods, the seal and the certificate are identical to normal signing.

Only the origins on the key can frame the signing page, and only for links made with that key; every other page of the app refuses to be framed. Each allowed origin must be a plain https:// origin (scheme, host and optional port, no path), up to ten per key. A minimal page: <iframe src="{url}" title="Sign the contract" allow="clipboard-write" style="width:100%;height:90vh;border:0"></iframe>, then window.addEventListener("message", (e) => { if (e.origin !== "https://app.airesdocs.com") return; /* e.data.event */ }). Pass { "view": "focused" } when creating the URL for the minimal page. If your page cannot use an iframe, open the same URL in a pop-up window; the messages work there too.

Webhooks, not polling

Please do not poll each contract for its status. Register a webhook for contract.completed (and any other events you need) and act when it arrives; deliveries are signed, retried for about a day and a half, and logged, so you can retry any you missed from the delivery log. If you need a safety net, run one catch-up query at most every 15 minutes: GET /api/v1/contracts?changedSince=<time of your last run> returns only the contracts that changed since then. Stop following a contract once it is completed, declined, voided or expired; nothing changes after that. The API itself only enforces the per-key rate limit (below), but integrations that poll every contract will run into it.

AI agents (MCP)

AI assistants that speak the Model Context Protocol, such as Claude Code, or the Claude and OpenAI APIs, can connect to https://api.airesdocs.com/mcp with an API key as a Bearer token. A key with read scopes lets an agent list and look up contracts and templates; it can send, remind or void only if the key also has contracts:send or contracts:void. The agent sees only the tools its key allows, and everything it does appears in the contract's activity like any API call. Connectors that sign in with OAuth (claude.ai, the ChatGPT app) are not supported yet.

Limits and errors

• Requests are rate-limited per key (120 a minute unless you set another limit on the key, up to 600). Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; over the limit you get 429 with Retry-After.
• Every request is validated against a schema; failures return 400 with the field and the problem in plain English. Errors always look like { "error": { "code", "message", "issues"? } }.
• A key whose account is no longer on Pro or Team gets 402; a missing scope is 403; someone else's contract is 404; files over the size or page limits are 413.
• Creating a contract is idempotent when you send an Idempotency-Key header (up to 255 characters): repeating the same request with the same key within 24 hours returns the first contract with Idempotent-Replayed: true instead of making and sending another, and the same key with a different body is refused with 409.

Reference

The authoritative reference with request and response schemas is published with the API source as API.md; it is the document this page summarises, and the changelog records API changes. Until the public URL is live, email support@airesdocs.com and we will send it. Security questions, including responsible disclosure, are on the security page; data-protection terms for what your integration sends are in the DPA.

Questions