API reference

Current user, active org, and all memberships

Delete the account (App Store requirement)

Deletes the user and everything keyed to them (sessions, memberships, device tokens). Refused while the user is the sole owner of a workspace that still has other members — ownership must be transferred first. Workspaces where they were the only member are left orphaned rather than destroyed: signed documents are legal artifacts with an audit chain that other parties rely on.

Resend the email-verification link to the signed-in user

List the organizations the user belongs to

Create a workspace and set it active (new-user onboarding)

Takes a JSON request body — see the schema in openapi.json.

Set the active organization for this session

Revoke the current session token

Register this device's APNs token for push notifications

Takes a JSON request body — see the schema in openapi.json.

Unregister a device token

Value-weighted pipeline KPIs for the active org

List documents (cursor-paginated, newest first)

Document detail with recipients

Builder blocks + variables (the reduced mobile editor's read)

Update a draft's blocks (server re-validates; totals recomputed at render)

Takes a JSON request body — see the schema in openapi.json.

Per-recipient timeline and per-page view stats

Replace the recipients on a draft

Takes a JSON request body — see the schema in openapi.json.

Send a draft for signature

Takes a JSON request body — see the schema in openapi.json.

Re-mint a recipient's signing link and re-email it

Mint a recipient's signing link without emailing it

For a partner that embeds the signing ceremony in its own product, where the signer is already on the page and needs a URL rather than a message. Sends no email and is not rate-limited as an expensive endpoint, which is what separates it from `resend` — use that one for "email it to them again". Tokens are stored hashed, so a link can only be minted and never fetched: this rotates the recipient's token, and any link previously emailed to them stops working. The recipient's own status is left as it stands.

Mint a fresh signing link for the caller's own recipient row

For a sender who is also a signer, so they can sign in-app without the email. Only ever returns the link for the recipient whose email matches the authenticated user; it cannot be used to obtain anyone else's link. Rotates the token, so any link previously emailed to that recipient stops working.

Void a draft or in-flight document

Takes a JSON request body — see the schema in openapi.json.

Manually nudge a recipient (or all outstanding signers)

Takes a JSON request body — see the schema in openapi.json.

Create a document from a PDF, place a signature field, add the signer, and send

One call that uploads a PDF, adds a single signer, places their signature field, and (unless `send:false`) sends it — returning the signing link. Ideal for machine integrations that supply a ready-made PDF (e.g. a Letter of Authorization).

Takes a JSON request body — see the schema in openapi.json.

Create a draft document from a PDF

Uploads a PDF and leaves it as a DRAFT with no recipients or fields. Returns per-page geometry so a client can render the pages and place fields, then call PUT /documents/{id}/fields and POST /documents/{id}/send.

Takes a JSON request body — see the schema in openapi.json.

List the fields on a document

Every field with its id, placement and — where it carries one — the prefilled value currently stored. The ids are the point. `PATCH /documents/{id}/field-values` names the fields it corrects, and until now nothing handed them back except the response to the `PUT` that created them: an integration wanting to correct a value months later either had to have stored those ids at send time — a mapping of its own that goes stale the moment the fields are set again — or could not do it at all. Reading them back makes this resource the source of truth rather than something every caller keeps a copy of.

Replace the fields on a draft

Coordinates are normalized 0..1 with a top-left origin, matching the signing ceremony's renderer. Drafts only.

Takes a JSON request body — see the schema in openapi.json.

Correct prefilled values on a document already out for signature

Changes what the prefilled boxes say, and nothing else — not the placements, not the recipients, not which fields exist. This is the operation to reach for when the sender's own records move after the envelope has gone out: a name corrected, an address updated. Without it the only remedy is to void the document and send a second copy, which costs the signer a dead link and a duplicate email over a spelling. **Refused once anybody has signed.** A signature is a statement about the document as that person saw it, so changing a word on the page afterwards would make it evidence of something never displayed. The check is for a signer who has finished rather than the document's own status: a parallel envelope sits at `PENDING` with one of three already done, and that signature binds exactly as the last one would. Only fields that were ever the sender's to fill. Naming a SIGNATURE or INITIALS field is refused rather than ignored — a caller who believes they have updated a signature should be told they have not.

Takes a JSON request body — see the schema in openapi.json.

Suggest where fields belong on an uploaded PDF

Reads the PDF's text layer and proposes signature/initials/date/text placements for a human to review. Nothing is saved — send what you accept to PUT /documents/{id}/fields. Costs 1 AI credit only when the model runs; the deterministic heuristics are free. A PDF with no text layer (a photo or flat scan) returns no suggestions.

Download the document's current PDF

The rendered PDF for a builder document, or the uploaded file for an upload — what the signer sees, before any signatures are applied. For the executed copy, use `/documents/{id}/sealed`.

Download the document as it currently stands, values and all

The source PDF with every answer so far drawn onto it: the values the sender prefilled, and anything a signer has completed. This is what the signer is actually looking at. `/documents/{id}/source` hands back the blank file the document was built from, which is the right answer for re-rendering a ceremony and the wrong one for showing a human what went out — an integration displaying it sees an empty form and reasonably concludes the prefill did not work. **Not a substitute for `/sealed`.** Nothing here is certified: no certificate of completion, no digital signature, and it is generated fresh on each request rather than archived. It is a picture of an unfinished document, and it says so — a completed document is refused with a `409` pointing at the sealed copy, which is the one worth keeping and the only one that proves anything.

Download the sealed, certified PDF

The executed document: every signature applied, the certificate of completion appended, and the whole file digitally signed. This is the copy worth keeping — under a workspace-per-customer setup it is the only way the integration holds its customers' executed documents, since those workspaces have no sign-in of their own. Available once the document reaches `COMPLETED` and the seal job has run, which is shortly after the last signer finishes. Poll on `409`: it means not yet. A `404` means the document is not in this workspace, so stop. The response carries `X-Sealed-SHA256`, the same digest as `sealedSha256` on `GET /documents/{id}` — hash the bytes you received and compare, and you have proof the archived copy is the one that was signed.

Generate a proposal from an intake and create a draft document

Takes a JSON request body — see the schema in openapi.json.

Plan + usage snapshot for the active org

The plan catalog (display copy + prices)

Start a Stripe Checkout to upgrade; returns a URL to open externally

Takes a JSON request body — see the schema in openapi.json.

Apply a verified App Store subscription transaction

Takes the signed transaction (JWS) from StoreKit and verifies Apple's signature server-side before granting anything — the client's own verification result is not trusted. Idempotent: StoreKit re-delivers transactions until they are finished, and renewals arrive unprompted.

Takes a JSON request body — see the schema in openapi.json.

Open the Stripe customer portal; returns a URL to open externally

List users across all workspaces

Impersonate a user — returns a session token to use as the bearer

Takes a JSON request body — see the schema in openapi.json.

Stop impersonating — returns the original admin session token

List the active org's API keys (secrets never returned)

Create an API key; the full secret is returned exactly once

Takes a JSON request body — see the schema in openapi.json.

Revoke an API key

List the caller's workspaces and the plan's workspace allowance

For a signed-in user, the workspaces they are a member of. For an API key, every workspace in its billing group — a key has no memberships, and the workspaces it provisions have no members either. Use the returned `id` as `X-FolioSign-Org` on the document endpoints.

Create a workspace under the same billing account

It bills through the same subscription while documents, templates and members stay separate. Refused when the plan's workspace allowance is already used, which on every plan but Corporate is one. Send `externalId` — your own id for this customer — to make the call idempotent: a repeat returns the workspace the first call created rather than a second one with the same name. There is no delete endpoint, so a duplicate cannot be undone through the API. A signed-in owner or admin becomes the new workspace's owner. An API key needs the `workspaces:write` scope; the workspace it creates has no members, and is reached by passing its `id` as `X-FolioSign-Org`.

Takes a JSON request body — see the schema in openapi.json.

Delete an empty workspace

For undoing a duplicate — a provisioning call that was retried before you started sending `externalId`, say. It is not a way to close an account. Refused when the workspace holds **any** document, even a draft: a sent document's audit trail is evidence, and a cascade would destroy it silently. Delete or void the documents first. Also refused for the account's main workspace, which holds the subscription the others bill through. An API key needs the `workspaces:delete` scope, which is separate from `workspaces:write` and never granted by default.

Origins allowed to embed this workspace's signing pages

Signing pages refuse framing by default — the ceremony is where a signature is produced, and a page that can frame it can overlay it and collect a signature on a document the signer never read. Listing an origin here permits that origin, and only for documents this workspace sent. See https://foliosign.com/docs/embedding.

Replace the origins allowed to embed this workspace's signing pages

Signing pages refuse framing by default — the ceremony is where a signature is produced, and a page that can frame it can overlay it and collect a signature on a document the signer never read. Listing an origin here permits that origin, and only for documents this workspace sent. See https://foliosign.com/docs/embedding. The list is replaced wholesale, so send the full set every time and send `[]` to close it again. Origins take effect within a minute — they are read per request, not baked into signing links, so removing one revokes it for links already out there. A bare hostname is read as https. Wildcards are refused: `*.example.com` would re-open the clickjack the default exists to prevent, so a multi-tenant integration lists each customer hostname on that customer's own workspace.

Takes a JSON request body — see the schema in openapi.json.

Whether this workspace's ceremonies offer the signer an account

Whether a signer who finishes a ceremony in this workspace is offered a free FolioSign account. On by default, which is right for a link FolioSign sent. Turn it off where the ceremony is embedded inside your own flow — the panel ends that flow on our call to action rather than yours, at the moment the signer should be moving on to your next step.

Turn the end-of-ceremony account panel on or off

Whether a signer who finishes a ceremony in this workspace is offered a free FolioSign account. On by default, which is right for a link FolioSign sent. Turn it off where the ceremony is embedded inside your own flow — the panel ends that flow on our call to action rather than yours, at the moment the signer should be moving on to your next step. Read per request rather than baked into signing links, so a change reaches links already out there.

Takes a JSON request body — see the schema in openapi.json.

The workspace's brand colour

Set the workspace's brand colour

Send null to clear it back to the FolioSign default. Owner or admin only.

Takes a JSON request body — see the schema in openapi.json.

Health of the OAuth grant this token belongs to

Reports whether the calling token's grant is live, what it was granted, which billing account it acts on, and when each half of the credential expires. Intended to be polled (hourly is plenty) so an integration can surface connection health to its own operators rather than discovering a lapsed grant through documents silently not being sent. Requires an OAuth access token; an API key has no grant and gets a 403. No scope is required — a grant whose scopes have been narrowed must still be able to report that.