Skip to content
Markdown
GuideForDeveloperWith or without Foxden Admin

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.

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). Without it Corsac sends no email: fetch each signer's link with the API and share it yourself (see 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, 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 /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.

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=<hex>, 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.

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 reach the same actions as tools: see Corsac agent tools.

Foxden is open source under Apache-2.0.