eSignature API for Sending Documents From Code

Overview

Send documents for signature from your own code. Design the template once in the app — the API fills in real people, prefills your own fields, and sends. Part of the Business plan.

Base URL

https://signibility.com/public/v1

Auth header

Authorization: Bearer sk_live_…

Keys are created on the Developers page and act as the whole workspace. The secret is shown once; revoking a key cuts its access immediately, and it stops working if the person who created it is removed or demoted.

Your first call

curl https://signibility.com/public/v1/documents \
  -H "Authorization: Bearer sk_live_…"

Track progress by polling GET /documents/{id} — it carries every signer's live status.

Quickstart

Template → signed in three calls. First, in the app: create a template with a role (say Client) and place its fields.

1
Find your template
Request
```
curl https://signibility.com/public/v1/templates \
  -H "Authorization: Bearer sk_live_…"
```
GET /templates/{id} adds the placed fields — including the ones you can prefill.

Fill the roles — by name

Request

curl -X POST https://signibility.com/public/v1/templates/{id}/use \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"recipients": [{"role": "Client",
        "name": "James Bennett", "email": "[email protected]"}]}'

Returns a fresh draft with every field already placed on the right people.

Send it

Request

curl -X POST https://signibility.com/public/v1/documents/{id}/send \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"acknowledged": true, "message": "Please review and sign."}'

Poll GET /documents/{id} for signer statuses; download the sealed bundle once completed.

Errors & limits

Every error is one envelope: a machine-readable code plus a human sentence.

Error shape

{"error": {"code": "unknown_role",
  "message": "Unknown role 'Signer'. This template's roles: Client."}}

Status codes

400: A business rule was broken — the code names which one (below).
401: Missing, invalid, or revoked API key.
402: The workspace's plan no longer includes API access.
403: Not yours to touch — e.g. prefilling another signer's field.
404: Not in this workspace. Keys never see other workspaces.
409: Wrong state for this action: already sent, already voided, not completed yet.
422: The request itself is malformed — a missing or wrong-typed field.
429: Rate limited, or a cooldown (reminders) — back off and retry.

Common codes

upload_invalid: Empty, corrupted, wrong type, or over the size/page limit.
too_many_recipients: Over 20 signers on one document.
no_recipients: Nothing to send — add a signer first.
missing_fields: A signer has no field placed for them.
not_acknowledged: "acknowledged" must be true to send.
phone_required: SMS verification is on for a signer with no number.
viewer_has_fields: A viewer (CC) can't hold signable fields.
unknown_role: A template fill named a role the template doesn't have.
ambiguous_role: The template has two roles with the same name, so a fill can't name one.
not_your_field: Prefill touched a field that belongs to a signer.
envelope_not_editable: The document has already been sent.
envelope_not_completed: Only a completed document has a sealed bundle.
not_voidable: Only documents awaiting signature can be voided.
reminder_cooldown: A reminder just went out — give signers an hour.

Limits

Uploads: PDF, Word (.docx), PNG, or JPG, checked by content · 50 MB · 500 pages
Signers: 20 per document
List page size: 25 by default, clamped 10–100
Rate limit: 120 requests / minute per API key (plus a wider per-IP wall)
Heavy operations: 30 / minute per API key for upload, send, and template use — the same budget the app gets for the same work

Documents

Upload, track, and fetch — the same documents the app shows.

GET /documents

List the workspace's documents, newest first.

Query parameters

statusoptional: Only documents in this status: draft, processing, awaiting, completed, declined, voided, or expired.
qoptional: Search query.
pageoptional: Page number.
page_sizeoptional: 25 by default, clamped 10–100.

POST /documents

Upload a file as multipart form data. Creates a draft.

Parameters

filerequired: PDF, Word (.docx), PNG, or JPG — detected from its bytes, not the filename. Up to 50 MB and 500 pages.
nameoptional: The document's title, up to 255 characters.

GET /documents/{id}

Detail with every recipient and their signing status — poll this to track progress.

PATCH /documents/{id}

Rename a draft. Out of draft the title is part of what was agreed — refused with envelope_not_editable.

Parameters

namerequired: The new title.

DELETE /documents/{id}

Move to trash — restorable in the app for 30 days.

GET /documents/{id}/download

A completed document downloads its sealed bundle — the signed PDF, zipped together with its audit certificate (a bare PDF if the workspace has the audit trail turned off). Anything still in draft or awaiting signatures downloads the current working file instead — there's nothing sealed yet.

Content-Type is application/zip or application/pdf to match.

Sending

Add people to a draft, send it, and manage it in flight. Every signer needs at least one placed field — place them in the app, or start from a template.

POST /documents/{id}/recipients

Add a recipient to a draft. Up to 20 signers per document.

Parameters

namerequired: The recipient's name.
emailrequired: Where the signing request goes.
kindoptional: signer (default) or viewer — viewers just receive the completed copy.
verify_emailoptional: Require a code sent to their email address before they can sign.
verify_phoneoptional: Require an SMS code before they can sign. Send phone with it.
phoneoptional: International format (+15550001234). Required when verify_phone is set.

Verification is per party and returned on every recipient, so what you set is what you can read back. Senders and viewers never verify — the flags are cleared for them, not refused.

POST /documents/{id}/send

Send the draft to everyone on it.

Parameters

acknowledgedrequired: Must be true — your attestation that this isn't a document type e-signatures can't cover (wills, deeds, powers of attorney…), recorded in the audit trail.
messageoptional: A note carried in the signing request email.
sequentialoptional: Signers asked one at a time, in order.
reminders_enabledoptional: Automatic reminders until everyone signs. On by default; a plan without reminders clears it rather than failing.
expires_onoptional: YYYY-MM-DD. The document expires at the end of that day, UTC. Answers 402 on a plan without expiry dates.

Response

{"status": "awaiting",
 "signing_links": [{"name": "James Bennett",
   "email": "[email protected]", "url": "https://signibility.com/sign/…"}]}

Signing links are minted at send and never stored — capture them from this response to deliver in your own channel.

POST /documents/{id}/remind

Nudge everyone currently able to sign. Reminders re-mint the signing links (the newest email is always the live one), so the fresh links ride back in the response. At most one reminder an hour — sooner answers 429 reminder_cooldown.

POST /documents/{id}/void

Kill an in-flight document. Everyone already asked to sign is told; open signing pages are blocked at submit. Only awaiting documents can be voided — anything else answers 409.

Parameters

reasonrequired: Why — shown to recipients.

Templates

Designed in the app — roles and field placement are visual work. The API turns them into ready-to-send drafts, with your own fields already filled.

GET /templates

Every template with its roles — names, signer/viewer kind, which role is the sender's own slot, and each role's verify_email / verify_phone requirement. A role with verify_phone is the one that makes phone mandatory when you fill it.

GET /templates/{id}

One template with its placed fields: each field's kind, page, owning role_name, and sender_field — true means use may prefill it. This is where the field_ids for prefill come from.

POST /templates/{id}/use

Turn a template into a ready-to-send draft: fill each role with a real person, and optionally prefill your own fields with the data your system already knows — amounts, references, dates.

Parameters

recipients[].rolerequired: The role to fill, by name, case-insensitively — "client" fills Client. Sender roles fill themselves from the key's owner. An unknown role answers 400 listing the template's actual roles.
recipients[].namerequired: The person filling the role.
recipients[].emailrequired: If the role was given email-code verification in the app, this is the address it verifies.
recipients[].phoneoptional: International format. Required when the role carries SMS-code verification — without it the send fails with phone_required.
prefill[].field_idoptional: A sender-owned text, date, or checkbox field, addressed by the ids from GET /templates/{id}. A signer's field answers 403 not_your_field — their fields are theirs to sign.
prefill[].valueoptional: The field's value; checkboxes take "checked" or "".

Fill roles + prefill sender fields

{"recipients": [{"role": "Client",
    "name": "James Bennett", "email": "[email protected]",
    "phone": "+15550001234"}],
  "prefill": [{"field_id": "3f6c…", "value": "$120,000.00"}]}

The API, documented.

Overview

Quickstart

Errors & limits

Documents

Sending

Templates

Start with a workspace.

The API, documented.

Overview

Quickstart

Errors & limits

Documents

Sending

Templates

Start with a workspace.

Cookies on Signibility