--- url: https://docs.codefox.ai/connect/corsac-api.md --- # Use the Corsac API This page lets you send documents for signature from your own code with Corsac's REST API: upload a PDF, add signers and fields, send it, follow its progress and download the signed copy. For what Corsac is, see [Corsac](/apps/corsac/). The API lives on Corsac's own address under `/api/v1`, for example `https://sign.example.com/api/v1`. Its full description is an OpenAPI 3.1 document at `GET /api/v1/openapi.json` (it needs a key, like every other call). ## Before you start * Someone who **can manage** Corsac creates the key: the API keys page is in Corsac's settings, under **Server**. * To let signers receive their invitations by email, email must be set up on the server (see [email on the server](/self-host/email)). Without it Corsac sends no email: fetch each signer's link with the API and share it yourself (see [Get a signing link](#get-a-signing-link)). ## Create a key 1. In Corsac's settings, select **API keys**. 2. Under **Create a key**, fill in **Label** with what will use the key, such as "Zapier". 3. Choose a **Scope**: **Read-only (GET requests)** or **Full access (create, send, void, manage webhooks)**. 4. Choose when it **Expires**: **In 30 days**, **In 90 days** (the default), **In a year** or **Never**. 5. Select **Create key**. The key starts with `csk_` and is shown once: copy it now. A key acts as the person who made it and reaches only the documents, templates and webhooks that person owns. It stops working (401) when it expires, while that person is switched off or has lost access to Corsac, and at once when it is revoked. For an [agent identity](/connect/agent-identities), use **Keys for agents** on the same page (it shows once there is an agent): that key acts as the agent and reaches the agent's own documents and the templates shared with the whole company. Send the key on every request: ```bash export CORSAC=https://sign.example.com/api/v1 export KEY=csk_... curl -s "$CORSAC/me" -H "Authorization: Bearer $KEY" ``` `GET /me` answers with the key's owner: `id`, `name`, `email`, `kind` (`person` or `agent`). ## Send a document for signature 1. Create a draft from a PDF. The request is a form upload with `title` and `file`: ```bash curl -s "$CORSAC/documents" -H "Authorization: Bearer $KEY" \ -F title="Service agreement" -F file=@agreement.pdf ``` The answer is the document, with its `id` and `status: "draft"`. 2. Add each recipient: ```bash curl -s "$CORSAC/documents/$DOC/recipients" -H "Authorization: Bearer $KEY" \ -H "content-type: application/json" \ -d '{"name":"Ada Lovelace","email":"ada@example.com","role":"signer"}' ``` `role` is `signer` (fills fields and signs), `approver` (approves or declines), `viewer` (confirms having read it) or `cc` (receives the sealed copy). `authMethod` can ask for an emailed code (`email_link_otp`), and `accessCode` (4 to 32 characters) makes the person enter a code you share with them yourself. 3. Place a field for each signer. `page` starts at 1; `x`, `y`, `w` and `h` are fractions of the page (0 to 1) from its top-left corner: ```bash curl -s "$CORSAC/documents/$DOC/fields" -H "Authorization: Bearer $KEY" \ -H "content-type: application/json" \ -d '{"recipientId":"'$RCP'","type":"signature","page":1,"x":0.1,"y":0.8,"w":0.3,"h":0.06}' ``` Field types: `signature`, `initials`, `date`, `name`, `email`, `text`, `checkbox`, `dropdown`, `radio`. 4. Send it: ```bash curl -s -X POST "$CORSAC/documents/$DOC/send" -H "Authorization: Bearer $KEY" \ -H "content-type: application/json" -d '{"ordering":"sequential"}' ``` The body is optional. It can set `ordering` (`parallel` or `sequential`), `emailSubject`, `emailMessage`, `otpRequired`, `signersMayDelegate`, reminders (`reminderCadenceDays`, `reminderCap`) and `expiresAt`. The status becomes `pending` and the invitations are queued; `emailed` in the answer is `false` when the server sends no email. To start from a template instead of a PDF, call `POST /templates/{id}/documents` with `bindings` (each template role's `roleName`, `name` and `email`) and optional `prefill`. The answer is a new draft. `POST /templates/{id}/bulk-send` takes up to 500 `rows`, each the same body, and sends one document per row; follow it with `GET /bulk-batches/{id}`. ## Check a document's status ```bash curl -s "$CORSAC/documents/$DOC" -H "Authorization: Bearer $KEY" ``` `status` is `draft`, `pending`, `completed`, `declined`, `voided` or `expired`. Each recipient shows when it was sent, opened, viewed, completed or declined, and a decline reason. `GET /documents` lists documents, 25 a page by default (`limit` up to 100, then `cursor` from `nextCursor`). To stop a live document, `POST /documents/{id}/void` with an optional `reason`. To delete a draft, `DELETE /documents/{id}`. ## Download the signed copy Once the document is completed, Corsac seals the PDF. Then: ```bash curl -s "$CORSAC/documents/$DOC/download" -H "Authorization: Bearer $KEY" -o signed.pdf curl -s "$CORSAC/documents/$DOC/certificate" -H "Authorization: Bearer $KEY" -o certificate.pdf ``` `download` and `certificate` answer 409 while the document is not sealed yet. `GET /documents/{id}/audit-log` exports the document's audit chain. Every download is recorded. ## Get a signing link `GET /recipients/{id}/signing-url` returns `{ "url": ... }`, the link that recipient signs with. Use it when you send links yourself (for example when the server sends no email). A link works only while the document is `pending`; a `cc` recipient has none. To show the signing page inside your own app, see [Embed forms, signing and chat on your site](/connect/embed). ## Direct links A direct link is a public address anyone can open to sign their own copy of a template. `POST /templates/{id}/direct-link` returns its `slug` and `url` (calling it again returns the same one), and `DELETE` on the same path turns it off. It works only for a template with exactly one signer role and no approver or viewer. ## Test mode Create a draft with `-F test_mode=true` to try things out. A test document: * is left out of `GET /documents` unless you add `?include_test=true`; * sends email only to people who have an account in Corsac; * gets no trusted timestamp, and its verify page says it is a test document not intended for execution. ## Get told when something changes Register a webhook with `POST /webhooks`, giving `url` and the `events` you want: `document.sent`, `document.completed`, `document.sealed`, `document.declined`, `document.voided`, `document.expired`, `recipient.viewed`, `recipient.signed`, `recipient.declined`. The answer holds the signing secret, shown once. People who can manage Corsac can also do this in its settings, under **Webhooks**. Each delivery is a JSON POST with `event`, `timestamp`, `documentId` and `title` (and `test_mode` for a test document). `recipient.*` events add `recipientId`, `name` and `email`; `document.sealed` adds `status`, `signedPdfUrl` and `certificateUrl`. It is signed with `X-Corsac-Signature: sha256=`, the HMAC-SHA256 of the raw body under your secret. Verify it over the raw bytes before parsing. A failed delivery is tried up to eight times. `GET /webhooks/{id}/deliveries` lists the attempts, and `POST /webhooks/{id}/rotate-secret` makes a new secret. The address must be public: private and internal addresses are refused. Corsac also sends `corsac.document.completed` to the suite's event feed: see [Receive suite events by webhook](/connect/events). ## Requests and errors * **Retries.** Calls that create, change or send a document or template take an `Idempotency-Key` header (the OpenAPI document marks each one). Repeating a request with the same key returns the first answer; reusing the key for a different request is a 422. * **Errors** are `application/problem+json` (RFC 9457) with `title`, `status` and a `detail` that says what to fix. 401 means the key is missing, unknown, revoked or expired, or its owner is switched off; 403 with a read-only key means the call needs **Full access**. Agents connected through [the AI gateway](/connect/gateway) reach the same actions as tools: see [Corsac agent tools](/reference/agent-tools/corsac).