LimeDocsAPI Reference
LimeDocs Developer API

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.

Base path. Every endpoint below lives under /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.
Getting started

Base URL

All API traffic goes to a single host over HTTPS. Prepend it to every path in this reference.

Production
https://api.limebase.app
Emails are delivered to real inboxes; envelopes, sealed PDFs, and certificates are retained. Manage keys and envelopes in the dashboard.
Keys & dashboard: https://limebase.app

Every path below is relative to this base URL — for example, POST /v1/envelopes means POST https://api.limebase.app/v1/envelopes.

Getting started

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
Store it immediately. LimeDocs keeps only a hash and a short prefix of each key — the full secret is displayed once and can never be retrieved again. If you lose it, revoke the key and create a new one. Treat keys like passwords: never commit them or expose them in a browser.

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.

Getting started

Conventions

TopicDetail
FormatRequests and responses are JSON (Content-Type: application/json), except document upload, which takes a raw application/pdf body.
IdentifiersAll resource IDs are UUIDs. A malformed ID in a path returns 404, never 400.
ListsCollection endpoints wrap results in { "data": [ … ] }.
Field coordinatesField 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.
ErrorsNon-2xx responses return { "error": "message" }. See Errors.
TenancyEvery request is scoped to the key's organization automatically. You never pass an org ID.

Guide

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.

Before you can send, the envelope must be a 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.

Retries. Send an 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.

Guide

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).

typeWhat the signer does
signatureApplies their adopted signature (typed or drawn).
initialApplies their initials.
datePicks a date.
date_signedNothing: fills itself in with the date they sign.
textTypes free text.
checkboxChecks or clears a box.
dropdownSelects from a list you give in the field's options.
email · phone · addressEnters their contact details, checked for format.
ssnEnters a Social Security Number. Stored encrypted; you see only the last four digits.
business_entityPicks their business structure, in the words of Form W-9.
einEnters an Employer ID Number. Stored encrypted; you see only the last four digits.
bank_account_owner · business_bank_account_ownerNames who owns the bank account.
bank_routing_number · bank_account_numberEnters 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).

Guide

Envelope lifecycle

statusMeaning
draftBeing assembled. Documents and fields can be added; not yet sent.
sentOut for signature. One or more signers have been notified.
completedEvery signer has signed. The sealed PDF and certificate are available.
declinedA signer declined. The envelope is stopped.
voidedThe 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": [ … ] }
Guide

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": [ … ] }
Guide

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.

Override, not additive. When an account has its own endpoint, its envelopes deliver only to that endpoint, not also to the org default — so you never get duplicate deliveries.

Events

EventFires when
envelope.sentAn envelope is sent for signature.
signer.signedAn individual signer completes their part.
envelope.completedAll signers are done; the sealed PDF + certificate are ready.
envelope.declinedA signer declines; the envelope stops.
envelope.voidedThe sender voids the envelope, in the dashboard or through the API.
recipient.copy_deliveredA 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 2xx within 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.ping and 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.
Guide

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:

The server isn't on npm yet; ask us for a build until it is. Anything on npm under @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

ToolWhat it does
list_envelopes · get_envelopeBrowse your envelopes and their status.
create_envelopeCreate a draft with a title and signers.
add_documentUpload a local PDF to a draft.
place_fields · list_fieldsPlace and review signature/date/text fields.
send_envelopeSend a draft for signature.
list_templatesList templates with their roles.
create_from_templateCreate an envelope from a template, and send it if asked.
download_sealed · download_certificateSave the sealed PDF and Certificate of Completion.
Try: "Create an envelope titled Mutual NDA, add ~/nda.pdf, place a signature and date field for Ada on page 1, and send it to ada@example.com." The assistant chains the tools for you.

Reference

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.


Reference

Errors

Errors return a non-2xx status and a JSON body of the shape { "error": "message" }.

StatusMeaning
400The request was malformed or failed a rule (bad field, missing document, coverage gap). The message says what.
401Missing, malformed, or invalid/revoked API key.
404Resource not found in your organization — or a malformed ID in the path.
409Conflict with current state, e.g. sending an envelope that's already sent.
500An unexpected server error. Safe to retry idempotent reads.