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

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.

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

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.