API reference

Getting started

Create a key in Settings, Developers. A test key works on every plan and signs for real without emailing anyone; a live key comes with the Pro and Business plans. Pro includes a monthly allowance of documents sent through the API; Business has no monthly API limit. Then send a document from a template in one call:

curl -X POST https://sharesign.co/api/v1/templates/{template_id}/documents \
  -H "Authorization: Bearer $SHARESIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{ "roles": { "Tenant": { "name": "Nora Whelan", "email": "nora@example.com" } }, "send": true }'

The response is the document, with a url to it in the dashboard. Without a template, POST a PDF as multipart with recipients and fields placed in points from the top-left of the page as it is displayed. The Developers page shows both, filled in with your own template.

SDKs

Official clients for TypeScript and Python are generated from this API's OpenAPI document, so their types are the API's types. They add what a client should: automatic idempotency keys, retries that honour Retry-After, iterators over lists and events, a file helper that picks inline or upload, typed errors with the request id, and webhook verification.

npm install @sharesign/sdk        # Node 18+, Deno, Bun, edge runtimes
pip install sharesign             # Python 3.10+, sync and async

import ShareSign from "@sharesign/sdk";
const sharesign = new ShareSign({ apiKey: process.env.SHARESIGN_API_KEY! });

const doc = await sharesign.templates.createDocument(templateId, {
  roles: { Tenant: { name: "Nora Whelan", email: "nora@example.com" } },
  send: true,
});
for await (const d of sharesign.documents.iterate({ status: "completed" })) console.log(d.title);

from sharesign import ShareSign
sharesign = ShareSign(api_key=os.environ["SHARESIGN_API_KEY"])

doc = sharesign.templates.create_document(template_id, {"roles": {"Tenant": {"name": "Nora Whelan", "email": "nora@example.com"}}, "send": True})
for d in sharesign.documents.iterate(status="completed"):
    print(d["title"])

Source and issues: github.com/prasants/sharesign/sdk.

Authentication

Send the key as a bearer token on every request. Keys belong to the workspace and act as the member who made them, or as the workspace owner once that member has left, so an integration outlives the person who set it up. Each key carries scopes:

Keys can expire on a date you set, and are revoked instantly. The Developers page shows when each was last used. The optional ShareSign-Version header pins the API shape; the only value today is 2026-09-09, echoed back on every response.

Errors

Every error is JSON with a stable code, a sentence for a person, the parameter at fault when there is one, and a request id to quote to support.

{ "error": { "code": "VALIDATION", "message": "fields[0].page: the file has 2 pages.", "param": "fields[0].page" }, "request_id": "req_…" }

Idempotency

Add an Idempotency-Key header (any string up to 255 characters, unique per operation) to a POST, PATCH, or DELETE. If the connection drops and you retry with the same key and body, you get the original response back, marked Idempotent-Replayed: true, and nothing happens twice. A reused key with a different body is refused. Keys are remembered for 24 hours. A 5xx frees the key so the retry runs.

Rate limits

Each key may make a set number of requests a minute, which depends on the plan. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; a 429 carries Retry-After in seconds. Documents sent by API count against the plan's monthly allowance exactly as the dashboard's do.

Pagination

Lists return data, has_more, and next_cursor. Pass the cursor back to get the next page. Cursors are stable: a document created while you page never shifts the rest. Events page by sequence instead, so a consumer can ask for everything after the last one it saw.

Test mode

A test key (ss_test_…) creates test documents: they render, sign, seal, and audit exactly like live ones, but no email is sent, nothing counts against the plan, and they appear in the dashboard marked Test. Two helpers exist only in test mode: sign or decline as any recipient, so a test suite can drive a document to completion and assert on the webhooks it receives. Test events go only to test-mode endpoints and say livemode: false.

Webhooks

Add an endpoint in Settings or by API and choose events. Each delivery is a POST with a JSON event and a signature header:

POST https://example.com/sharesign
Content-Type: application/json
ShareSign-Signature: t=1757404800,v1=5f8c…
ShareSign-Event-Type: document.completed
ShareSign-Delivery-Id: 6b1e…

{ "id": "…", "object": "event", "type": "document.completed", "sequence": 1042, "livemode": true,
  "created_at": "2026-09-09T08:00:00.000Z", "api_version": "2026-09-09",
  "data": { "document": { … the document as it was … }, "recipient": { … when one is involved … } } }

Verify the signature before trusting the body. The SDKs do it in one call: constructEvent(rawBody, header, secret) in TypeScript, construct_event(raw_body, header, secret) in Python. By hand: the signed string is the timestamp, a dot, and the raw body; the digest is HMAC-SHA256 with your endpoint's secret, hex encoded. Reject anything older than five minutes to stop replays.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=") as [string, string]));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const sigs = header.split(",").filter((kv) => kv.startsWith("v1=")).map((kv) => kv.slice(3));
  return fresh && sigs.some((s) => s.length === expected.length && timingSafeEqual(Buffer.from(s, "hex"), Buffer.from(expected, "hex")));
}

Answer with any 2xx within ten seconds; do the work afterwards. Anything else is retried 9 more times over about three days. Deliveries are not guaranteed to arrive in order: use sequence, or fetch the document, before acting on state. An endpoint that fails 30 times in a row is paused and the workspace's owners are emailed; turning it back on, replaying events, and sending a test ping are all one click in Settings. Rotating the secret keeps both secrets valid for 24 hours. Event types:

Embedded signing

To let someone sign inside your own product, ask for a signing session naming the origin that will frame it. The URL you get back may be placed in an iframe on that origin, and nowhere else, until it expires. The page tells the parent window what happened:

const res = await fetch(`https://sharesign.co/api/v1/documents/${docId}/recipients/${recipientId}/signing_session`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ allowed_origin: "https://app.example.com" }),
});
const { url } = await res.json();
// <iframe src={url} style="width:100%;height:100vh;border:0"></iframe>

window.addEventListener("message", (e) => {
  if (e.origin !== "https://sharesign.co" || e.data?.source !== "sharesign") return;
  // e.data.event is "viewed", "signed", "declined", "handed_off", or "completed"
});

Agents

ShareSign is a Model Context Protocol server at https://sharesign.co/mcp, so Claude, ChatGPT, or an agent you wrote yourself can work with your documents from wherever it already runs. There are two ways to connect, and which one you use decides what the agent is.

As you. In claude.ai, Claude Desktop or ChatGPT, add https://sharesign.co/mcp as a custom connector. You are sent to sign in to ShareSign and shown exactly what the agent is asking for; once you allow it, the agent acts as you, in the workspace you last used in the dashboard, with your role’s permissions. It can read, draft and prepare; it can never send, remind, void or delete. You press Send. To end its access, disconnect ShareSign in the app: a token it already holds is good for at most 24 hours and cannot be renewed after that.

With a key. Claude Code, Cursor, and anything you write yourself can carry an API key as the bearer token instead. The key’s scopes apply exactly as they do here: an agent sees only the tools its key allows, and nothing it cannot do through this API becomes possible through an agent.

{
  "mcpServers": {
    "sharesign": {
      "url": "https://sharesign.co/mcp",
      "headers": { "Authorization": "Bearer ss_live_..." }
    }
  }
}

With documents:read and templates:read (or, as you, a role that can read) an agent can list templates and their roles, list documents by status, read a document’s recipients and fields, read its activity to say where it stalled, get a fifteen-minute download link, and ask where the document itself asks to be signed — the same detection the editor offers as ghost fields, returned as fields to place with the recipient each one matched, so an agent never invents a coordinate.

With documents:write it can also draft: create a document from a template by naming who plays each role, or from its own PDF through an upload URL; edit a draft’s recipients, fields and message; and prepare it for sending. Preparing runs the same checks Send does and leaves the draft in ShareSign marked prepared by an agent, with the recipients read back — a person presses Send. No tool sends, reminds, voids or deletes unless the key also carries agent:send beside documents:send. That scope is off by default, is granted to one key for one automation, and cannot be granted to a connection made as you; with it, the agent can send a document it prepared (naming the version it prepared, so nothing that changed in between goes out), remind signers, void, and delete. Without it, the person is the Send button.

Every write takes an idempotency_key so a retried call is answered with the first call’s result rather than done twice, and every edit names the version it read, so an agent never overwrites a person’s edit: if the document changed in between, the edit is refused and the agent reads again. What an agent does lands in the document’s audit trail beside what people do, naming the key or the app. A test key works throughout: documents sign for real and email nobody.

Two things an agent never receives, by design: a signing link, and the document’s own text. A signing link is a recipient’s identity; the text of a contract can carry instructions to a model. Status, recipients, fields and activity are what an agent needs.

Endpoints

Base URL https://sharesign.co/api. Ids are UUIDs. Times are ISO 8601 in UTC.