API Reference
A REST API for electronic signatures. Create an envelope, attach PDF documents, place signature and data fields, and send it — LimeBase emails each signer a secure link, collects their input in order, and seals the finished PDF with a certificate of completion.
/v1 and speaks
JSON (documents are the one exception — you upload raw PDF bytes). Take the base URL
from the next section and prepend it to each path.Base URL
All API traffic goes to a single host over HTTPS. Prepend it to every path in this reference.
https://limebase.appEvery path below is relative to this base URL — for example, POST /v1/envelopes means
POST https://api.limebase.app/v1/envelopes.
Authentication
The API authenticates with a secret API key sent as a bearer token. Keys are organization-scoped: one key represents your whole organization, and every request it makes reads and writes that organization's data.
Getting a key
Sign in to the dashboard and open Organization Settings → Developer
(/settings). Create a key, give it a name, and copy the secret:
# A key looks like this — shown in full only once, at creation: lsk_live_9f2c… # lsk_live_ followed by 32 url-safe characters
Making an authenticated request
Send the key in the Authorization header on every /v1 request:
curl https://api.limebase.app/v1/envelopes \ -H "Authorization: Bearer lsk_live_9f2c…"
A missing or malformed token returns 401 missing bearer token; an unknown or revoked key
returns 401 invalid api key. The /healthz and /readyz probes are the
only unauthenticated endpoints.
Conventions
| Topic | Detail |
|---|---|
| Format | Requests and responses are JSON (Content-Type: application/json), except document upload, which takes a raw application/pdf body. |
| Identifiers | All resource IDs are UUIDs. A malformed ID in a path returns 404, never 400. |
| Lists | Collection endpoints wrap results in { "data": [ … ] }. |
| Field coordinates | Field positions are page-ratios in the range [0,1] — fractions of the page width/height, so they render correctly at any zoom or page size. See Field types. |
| Errors | Non-2xx responses return { "error": "message" }. See Errors. |
| Tenancy | Every request is scoped to the key's organization automatically. You never pass an org ID. |
The signing workflow
Sending a document for signature is a four-step sequence. Each step is a single API call, and the order matters — you place fields after the document exists, and you can only send once every signer has at least one field.
1 · Create an envelope
An envelope is the unit that gets signed: a title, one or more signers, and (optionally)
a signing order. POST /v1/envelopes returns the envelope plus its signers, each with a generated ID.
2 · Add a document
Upload a PDF with POST /v1/envelopes/:id/documents. LimeDocs records it, hashes it, and
rasterizes each page to an image so signers can view it on any device. The response includes the
document's id and pageCount.
3 · Place fields
Tell LimeDocs where each signer signs. POST /v1/envelopes/:id/fields takes a batch of
fields, each tying a signerId and documentId to a type and a position on a page.
4 · Send
POST /v1/envelopes/:id/send validates the envelope, flips it to sent, and emails
the first signing group a secure link. As each signer finishes, the next group is notified automatically.
draft, have at
least one document, and have every signer covered by at least one field. Otherwise send returns
400 with a message naming what's missing.Full example
# 1. Create an envelope with two signers ENV=$(curl -s https://api.limebase.app/v1/envelopes \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{"title":"Mutual NDA","signers":[ {"name":"Ada Lovelace","email":"ada@example.com","signingOrder":1}, {"name":"Alan Turing","email":"alan@example.com","signingOrder":2}]}') ENV_ID=$(echo "$ENV" | jq -r .id) SIGNER1=$(echo "$ENV" | jq -r '.signers[0].id') # 2. Upload the PDF (raw bytes) DOC=$(curl -s https://api.limebase.app/v1/envelopes/$ENV_ID/documents \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/pdf" \ -H "X-Document-Name: nda.pdf" \ --data-binary @nda.pdf) DOC_ID=$(echo "$DOC" | jq -r .id) # 3. Place a signature field for the first signer on page 1 curl -s https://api.limebase.app/v1/envelopes/$ENV_ID/fields \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d "{\"fields\":[{\"documentId\":\"$DOC_ID\",\"signerId\":\"$SIGNER1\", \"type\":\"signature\",\"page\":1,\"x\":0.6,\"y\":0.1,\"w\":0.25,\"h\":0.06}]}" # 4. Send it curl -s https://api.limebase.app/v1/envelopes/$ENV_ID/send \ -H "Authorization: Bearer $KEY" -X POST # → {"status":"sent","notified":1}
In one request
The same envelope can be built and sent with a single call. Put the files in documents
(base64), the fields in fields, and set send to true. Nothing has an id
yet, so a field names its document and signer by position in the request: documentIndex and
signerIndex, counting from 0.
curl -s -X POST "https://api.limebase.app/v1/envelopes" -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: order-1042" \
-d '{
"title": "Mutual NDA",
"signers": [ { "name": "Ada Lovelace", "email": "ada@example.com" } ],
"documents": [ { "name": "nda.pdf", "content": "JVBERi0xLjcK…" } ],
"fields": [ { "documentIndex": 0, "signerIndex": 0, "type": "signature",
"page": 1, "x": 0.6, "y": 0.8, "w": 0.25, "h": 0.06 } ],
"send": true
}'
# → the whole envelope: status "sent", its documents and fields, and each signer's signingUrl
The request is all-or-nothing: if a file is not a PDF, a field is off its page, or a signer has no field,
the answer is 400 and nothing is created. The body may be up to 26 MB, about 19 MB of
files once encoded; for larger files use the upload endpoint.
Idempotency-Key header with a value unique to
the request. If the call times out and you send it again with the same key, you get the envelope it already
made (status 200, header Idempotent-Replayed: true) and nothing is sent twice. A
replayed answer has no signing links, since a link is shown only when it is issued: get a fresh one from the
issue-link endpoint.From a template
When you send the same document repeatedly, build it once as a template in the dashboard (documents, fields, and a named role for each recipient) and create each envelope from it. You send no file and no coordinates, only who fills each role.
curl -s "https://api.limebase.app/v1/templates" -H "Authorization: Bearer $KEY" # ids, roles, documents curl -s -X POST "https://api.limebase.app/v1/templates/$TEMPLATE/envelopes" -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" -H "Idempotency-Key: lease-7" \ -d '{ "title": "Lease for 12 Elm St", "signers": [ { "role": "Tenant", "name": "Ada Lovelace", "phone": "+13055104015", "channel": "none" } ], "send": true }'
Every role in the template needs exactly one person, named by the role's name or id. The template sets what
each role does and the signing order; title, accountId,
linkExpiresInHours and redirectUrl can be set per envelope.
Field types
A field is a rectangle on a page, assigned to one signer. Its position is given as page-ratios:
x/y is the top-left corner and w/h the size, each a
fraction of the page. All four are in [0,1], and x+w and y+h must
not exceed 1 (the field has to fit on the page).
| type | What the signer does |
|---|---|
signature | Applies their adopted signature (typed or drawn). |
initial | Applies their initials. |
date | Picks a date. |
date_signed | Nothing: fills itself in with the date they sign. |
text | Types free text. |
checkbox | Checks or clears a box. |
dropdown | Selects from a list you give in the field's options. |
email · phone · address | Enters their contact details, checked for format. |
ssn | Enters a Social Security Number. Stored encrypted; you see only the last four digits. |
business_entity | Picks their business structure, in the words of Form W-9. |
ein | Enters an Employer ID Number. Stored encrypted; you see only the last four digits. |
bank_account_owner · business_bank_account_owner | Names who owns the bank account. |
bank_routing_number · bank_account_number | Enters bank details. The account number is stored encrypted; you see only the last four digits. |
Each field also takes an optional required boolean (defaults to true).
Envelope lifecycle
| status | Meaning |
|---|---|
draft | Being assembled. Documents and fields can be added; not yet sent. |
sent | Out for signature. One or more signers have been notified. |
completed | Every signer has signed. The sealed PDF and certificate are available. |
declined | A signer declined. The envelope is stopped. |
voided | The sender cancelled it, in the dashboard or with POST /v1/envelopes/:id/void. Outstanding signing links no longer work. |
Your own reference. Set externalId (up to 255 characters) and
metadata (up to 50 string values) when you create an envelope, and both come back on the
envelope and in every webhook about it, so you can match it to your own record without keeping a lookup table.
GET /v1/envelopes?externalId=deal_4821 lists the envelopes with that reference, newest first.
It isn't unique: when you regenerate a document, void the old envelope and send the new one with the same
externalId.
{ "title": "Mutual NDA", "externalId": "deal_4821", "metadata": { "crmId": "0065g00000Xyz" }, "signers": [ … ] }
Signing order. Each signer has a signingOrder integer. Signers who share a
number are notified together (parallel); distinct numbers go one group at a time (sequential). When you
omit signingOrder, signers are numbered in the order you supply them — i.e. sequential by default.
Link expiry. A signing link works for 14 days unless the envelope says otherwise. Set
linkExpiresInHours (a whole number from 1 to 2160) when you create the envelope to change that —
8 for a link that lasts eight hours. The clock starts when a link is issued, so a reminder or a
link from the issue-link endpoint gets the full lifetime again. Every link the API returns comes with
signingUrlExpiresAt. An expired link shows the recipient a "Link expired" page; the envelope
stays open, and you can issue a fresh link.
{ "title": "Return authorization", "linkExpiresInHours": 8, "signers": [ … ] }
Delivering the link yourself. Give a signer "channel": "none" and LimeBase
sends them nothing — no invitation, reminder, completion note or void notice. Sending the envelope returns
their signingUrl for you to deliver over your own channel; for a later signing group, call the
issue-link endpoint when their turn comes (the signer.signed webhook tells you). Such a signer
needs an email or a phone, but not both: it is how the Certificate of Completion
names them.
{ "title": "Return authorization", "signers": [
{ "name": "Jordan Rivera", "phone": "+13055104015", "channel": "none" } ] }
Texting the link. Give a signer with a phone "channel": "sms" and
LimeBase texts them instead of emailing; "both" does both. The first text asks the recipient to
reply and opt in, as the law requires; the signing link follows their reply, and the
envelope.sent webhook fires as usual. Texting is not offered to a cc or viewer, who are emailed
their copy.
{ "title": "Return authorization", "signers": [
{ "name": "Jordan Rivera", "email": "jordan@example.com", "phone": "+13055104015", "channel": "both" } ] }
Redirect after signing. Set redirectUrl when you create the envelope to choose
where its signers land once they finish. It overrides the account's redirect URL for that envelope; leave it
out and the account's applies.
{ "title": "Return authorization", "redirectUrl": "https://acme.com/thank-you-signed", "signers": [ … ] }
Accounts & branding
An account is a sending profile inside your organization — it controls the branding a signer sees: the logo and accent color on the signing screen, and the sender name, reply-to address, subject, and body of the notification emails.
Pass an accountId when creating an envelope to send under that profile. Omit it and LimeDocs
uses your organization's default account. Accounts are created and branded in the dashboard; the API
selects among them per envelope.
{ "title": "Order form", "accountId": "a1b2c3d4-…", "signers": [ … ] }
Webhooks
Instead of polling, let LimeDocs notify your server when an envelope changes. You register an HTTPS endpoint in the dashboard, and LimeDocs POSTs a signed JSON event to it as things happen.
Configuring endpoints
Webhooks are managed in the dashboard under Organization Settings → Webhooks. Endpoints you add there are your organization defaults — every account uses them. You almost never need more than that. If a particular account needs to route elsewhere, add a webhook on that account to override the default for its envelopes; accounts with no webhook of their own keep inheriting the org default.
Events
| Event | Fires when |
|---|---|
envelope.sent | An envelope is sent for signature. |
signer.signed | An individual signer completes their part. |
envelope.completed | All signers are done; the sealed PDF + certificate are ready. |
envelope.declined | A signer declines; the envelope stops. |
envelope.voided | The sender voids the envelope, in the dashboard or through the API. |
recipient.copy_delivered | A CC recipient was sent the completed copy. |
A webhook.ping event is also sent when you click Send test in the dashboard.
Workspaces with LimeCert can subscribe the same endpoints to its events — certificate.issued,
certificate.claimed, footprint.closed, consent.failed,
risk.high, snippet.silent — whose payload is about a lead rather than an envelope;
see the LimeCert guide.
Payload
The body carries the event, an envelope summary (status + signers), and authenticated API links to pull the full documents, sealed PDF, and certificate — LimeDocs never puts file bytes in the webhook.
{
"id": "3f1a…", // unique delivery id — dedupe on this
"type": "envelope.completed",
"createdAt": "2026-08-19T14:03:22.000Z",
"envelope": {
"id": "e7c1…", "title": "Mutual NDA", "status": "completed", "accountId": null,
"externalId": "deal_4821", "metadata": { "crmId": "0065g00000Xyz" },
"signers": [ { "id": "9a3b…", "name": "Ada", "email": "ada@x.com",
"status": "signed", "signingOrder": 1, "signedAt": "2026-08-19T14:03:20Z" } ]
},
"signer": null, // set for signer.* events
"links": {
"self": "https://api.limebase.app/v1/envelopes/e7c1…",
"documents": "https://api.limebase.app/v1/envelopes/e7c1…/documents",
"certificate": "https://api.limebase.app/v1/envelopes/e7c1…/certificate"
}
}
Verifying the signature
Every request carries an X-LimeBase-Signature: t=<unix>,v1=<hmac> header. The
signature is HMAC-SHA256 over "{timestamp}.{rawBody}" using your endpoint's signing
secret (whsec_…, shown once when you create or rotate the endpoint). Recompute it and compare
in constant time; reject if the timestamp is old to prevent replays.
import crypto from "node:crypto"; function verify(rawBody, header, secret) { const { t, v1 } = Object.fromEntries(header.split(",").map(kv => kv.split("="))); if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay guard const expected = crypto.createHmac("sha256", secret) .update(`${t}.${rawBody}`).digest("hex"); return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)); }
Other headers: X-LimeBase-Event (the event type) and X-LimeBase-Delivery
(the delivery id, same as payload.id). Each is also sent under its older
X-LimeSign- name, so receivers written against either keep working.
Custom headers and allowlisting
If your endpoint sits behind a tunnel, gateway or firewall that wants a header of its own — an
Authorization token, an API key — add it to the endpoint under Custom headers,
one Name: value per line. It's sent with every delivery. LimeBase's own headers
(Content-Type, User-Agent, X-LimeBase-*) can't be overridden.
Requests come from LimeBase's servers on AWS (us-east-1), whose addresses change, so there is
no fixed IP range to allowlist. Authenticate requests by their signature, or by a custom header your
endpoint checks.
Delivery & retries
- Respond
2xxwithin 10 seconds to acknowledge. Any other status (or a timeout) is a failure. - Failures are retried with exponential backoff (up to 6 attempts, ~2m → 6h) before the delivery is marked failed.
- Each endpoint has a delivery log in the dashboard: every delivery, what your endpoint
answered (status, time taken, the start of the response body), and a Resend button.
Filter it by outcome or event, look a delivery up by its id or by the envelope's, and page back through
history. Send test sends a
webhook.pingand shows the answer right away. History is kept for 30 days for deliveries that succeeded and 90 days for ones that failed. - Deliveries to one endpoint are sent in order, one at a time; different endpoints are sent in parallel, so a slow receiver delays only its own events.
- When an endpoint fails four attempts in a row, the workspace's owners and admins are emailed, once; the next success re-arms the alert. Test pings don't count.
- Delivery is at-least-once — the same event may arrive more than once, so make your
handler idempotent by keying on
payload.id. - Endpoints must be
https://. Return quickly and do slow work asynchronously.
MCP server
LimeDocs ships a Model Context Protocol server, so an AI assistant (Claude Desktop, Claude Code, or any MCP client) can create, prepare, and send envelopes on your behalf — using the same API key and permissions as everything else here.
Workspaces with LimeCert get read-only tools over certificates and leads from the same server; see the LimeCert guide.
Configure
Create an API key under Organization Settings → Developer, then add the server to your
client. For Claude Desktop, edit claude_desktop_config.json:
@limebase/mcp before this page says so isn't from us, so don't give it your API key.{
"mcpServers": {
"limebase": {
"command": "node",
"args": ["/path/to/limebase-mcp/dist/index.js"],
"env": { "LIMEBASE_API_KEY": "lsk_live_…" }
}
}
}
It talks to https://api.limebase.app. Set LIMEBASE_API_BASE_URL only to point it
somewhere else.
Tools
| Tool | What it does |
|---|---|
list_envelopes · get_envelope | Browse your envelopes and their status. |
create_envelope | Create a draft with a title and signers. |
add_document | Upload a local PDF to a draft. |
place_fields · list_fields | Place and review signature/date/text fields. |
send_envelope | Send a draft for signature. |
list_templates | List templates with their roles. |
create_from_template | Create an envelope from a template, and send it if asked. |
download_sealed · download_certificate | Save the sealed PDF and Certificate of Completion. |
API reference
Every endpoint — its request, response, status codes, and field‑level schemas — lives in the interactive reference, generated from our OpenAPI spec (the single source of truth), so it stays in lockstep with the live API.
Open the API reference → Download the OpenAPI spec
Import openapi.json into Postman, Insomnia, or your codegen tool to scaffold a client in minutes.
Errors
Errors return a non-2xx status and a JSON body of the shape { "error": "message" }.
| Status | Meaning |
|---|---|
400 | The request was malformed or failed a rule (bad field, missing document, coverage gap). The message says what. |
401 | Missing, malformed, or invalid/revoked API key. |
404 | Resource not found in your organization — or a malformed ID in the path. |
409 | Conflict with current state, e.g. sending an envelope that's already sent. |
500 | An unexpected server error. Safe to retry idempotent reads. |