# Vumasign

> The Vumasign API: templates, envelopes, embedded signing and signed webhooks.

- [Introduction](https://docs.vumasign.com/index.md): Everything your own software needs to talk to Vumasign.
- [Authentication](https://docs.vumasign.com/authentication.md): One bearer header, and the scopes a key is minted with.
- [Rate limits](https://docs.vumasign.com/rate-limits.md): Per key, per minute, set by the plan.
- [Errors](https://docs.vumasign.com/errors.md): One refusal shape, and a closed enum of codes with retry semantics for each.
- [AI tools](https://docs.vumasign.com/ai-tools.md): Let an agent read these docs instead of guessing at the API.
- [Roles and recipients](https://docs.vumasign.com/concepts/roles-and-recipients.md): A template declares roles; an envelope names the people who fill them.
- [Getting fields onto a page](https://docs.vumasign.com/concepts/placing-fields.md): The document chooses, not the request: text tags or detection, never both.
- [Text tags](https://docs.vumasign.com/concepts/text-tags.md): Write the field into the document where it goes.
- [Field detection](https://docs.vumasign.com/concepts/field-detection.md): With no tags in the document, the page is measured instead.
- [Test keys and live keys](https://docs.vumasign.com/concepts/test-and-live.md): What a test key can and cannot do, in all three respects.
- [Sealing](https://docs.vumasign.com/concepts/sealing.md): What happens when the last recipient finishes.
- [Embedded signing](https://docs.vumasign.com/guides/embedded-signing.md): The host page contract: what to register, what to mint, and what not to trust.
- [Webhooks](https://docs.vumasign.com/guides/webhooks.md): Register an endpoint, verify every delivery, and deduplicate on the event id.
- [This document, the machine-readable description of the API.](https://docs.vumasign.com/api-reference/get-openapi-document.md): The machine-readable description of everything above, served to anybody who asks. ⚠️ NO CREDENTIAL, AND THAT IS THE POINT: an integrator evaluating this API, or an agent writing against it, should not have to hold a key to learn what the endpoints are. It discloses no customer data — it is the same…
- [List live templates, newest first.](https://docs.vumasign.com/api-reference/list-templates.md): Walked by keyset cursor rather than by offset. ⚠️ OFFSET WOULD BE WRONG HERE, not merely unfashionable: this list is ordered newest first, so a template created between page 1 and page 2 shifts every row down — the caller receives one row twice and never sees another. The thing an integration does b…
- [Upload a PDF or a Word document and get a template with its fields already placed.](https://docs.vumasign.com/api-reference/create-template.md): THE ENDPOINT THIS API EXISTS FOR. Send a document and a list of roles; get back a template whose signature boxes, date fields, ID-number combs and marital-status questions are already on the page, each carrying the `id` you need to address it. Nobody opens an editor.
- [One template, with every field address on it.](https://docs.vumasign.com/api-reference/get-template.md): THE ENDPOINT THAT SHOWS THE ADDRESSES. Read it once, by hand, before writing the code that sends anything: it is where you learn which `(subject, data_key)` pair each box on the paper answers to, and which boxes have no address at all.
- [One page of a document, as a PDF, to look at.](https://docs.vumasign.com/api-reference/get-document-page.md): THE PAGE ITSELF. `GET /api/v1/templates/{templateId}` tells you where every field is; this is the picture those coordinates are measured against. Fetch it, render it, and every `Field.rect` on this page lands on its box.
- [List envelopes, newest first, optionally filtered by status.](https://docs.vumasign.com/api-reference/list-envelopes.md): `GET /api/v1/envelopes/{envelopeId}` reads one envelope by an id you already hold; this is how you find out which ids exist. The webhook delivery ladder gives up after 7 attempts, so an integrator who dropped a delivery has no way to learn what was missed except by asking here.
- [Create an envelope from a template, and optionally send it.](https://docs.vumasign.com/api-reference/create-envelope.md): THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason `Idempotency-Key` is required rather than optional.
- [Send a document that is not a template, and optionally send it.](https://docs.vumasign.com/api-reference/create-one-off-envelope.md): THE ENDPOINT FOR A DOCUMENT THAT EXISTS ONCE — a Letter of Authority, an offer of employment, anything addressed to one person and never reused.
- [Create and send many envelopes from one template, in one request.](https://docs.vumasign.com/api-reference/create-envelope-batch.md): ONE REQUEST, ONE `Idempotency-Key`, UP TO 100 ENVELOPES. What this saves is not our time but your error handling: a thousand loops of `POST /api/v1/envelopes` is a thousand keys to mint and persist, a thousand timeouts to resolve, and a thousand places to be halfway through.
- [One envelope, as it stands right now.](https://docs.vumasign.com/api-reference/get-envelope.md): ⚠️ **THIS IS WHAT EVERY WEBHOOK BODY’S `uri` POINTS AT, AND WHY THAT FIELD EXISTS.** A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than…
- [Get an envelope’s document, and its certificate once sealed.](https://docs.vumasign.com/api-reference/list-envelope-documents.md): THE BYTES `GET /api/v1/envelopes/{envelopeId}` COULD NOT REACH. That endpoint answers with status and recipients; this is where the contract itself lives — the one route an integrator who embedded signing and received `envelope.completed` needs and, until now, did not have.
- [The document as it stands, mid-flight, stamped DRAFT.](https://docs.vumasign.com/api-reference/get-envelope-document-draft.md): THE DOCUMENT WITH EVERY ANSWER SO FAR ON IT, WHILE IT IS STILL OUT FOR SIGNATURE. The operation above serves the document as originally sent and, once sealing has landed, the executed copy — and between those two moments there was nothing to fetch. This is that gap: the pages carry every signature,…
- [Withdraw a sent envelope.](https://docs.vumasign.com/api-reference/void-envelope.md): STOPS AN ENVELOPE THAT IS OUT FOR SIGNATURE. Every outstanding signing link is revoked, the envelope moves to `voided`, and the reason is kept on the record and in the audit trail.
- [Send a draft envelope to its recipients.](https://docs.vumasign.com/api-reference/send-envelope.md): THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. `POST /api/v1/envelopes` with `"send": false` makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangemen…
- [Mint a short-lived, single-use URL for an embedded signer.](https://docs.vumasign.com/api-reference/create-signing-url.md): THE ONE ENDPOINT IN THIS API THAT RETURNS A BEARER CREDENTIAL FOR A LEGAL ACT. Anyone holding the `url` can open the document as that signer. **Do not log it, cache it, store it or put it in a support ticket** — put it in an `iframe src` and nowhere else.
- [Every registered endpoint, with its health.](https://docs.vumasign.com/api-reference/list-webhooks.md): Newest first. ⚠️ NO `secret` ON ANY OF THEM — a secret is returned by the registration and by a rotation, and by nothing else, ever.
- [Register an endpoint and mint its signing secret.](https://docs.vumasign.com/api-reference/create-webhook.md): THE ENDPOINT THAT MAKES MULTI-TENANT ONBOARDING PROGRAMMATIC. BoldSign has no webhook management API at all — theirs is configured in a dashboard, by a human — which means a customer who resells to their own tenants cannot onboard one without somebody clicking. This is the same resource with the sam…
- [One endpoint, with its health.](https://docs.vumasign.com/api-reference/get-webhook.md): ⚠️ THREE SITUATIONS ANSWER WITH THE SAME 404: no such endpoint; one belonging to another organisation; an id that is not a uuid. "This exists but is not yours" is itself the secret, and the handler could not distinguish them if it wanted to — the read runs inside a transaction already scoped to the…
- [Remove an endpoint. ⚠️ Queued deliveries go with it.](https://docs.vumasign.com/api-reference/delete-webhook.md): ⚠️ **EVERY DELIVERY STILL QUEUED FOR THIS ENDPOINT IS DISCARDED.** That is a decision, stated here because a customer who expected the queue to drain deserves to have been told rather than to find out.
- [Change the URL, the subscription, the brand filter or the active flag.](https://docs.vumasign.com/api-reference/update-webhook.md): A PARTIAL BODY, and one path for every property this resource will ever have. BoldSign minted one endpoint per property — `addTags`, `changeAccessCode`, `extendExpiry`, eight ways to edit a document — and has 87 paths and a casing typo they can never fix.
- [Mint a new signing secret, keeping the old one alive briefly.](https://docs.vumasign.com/api-reference/rotate-webhook-secret.md): THE SECOND AND LAST TIME A SECRET IS RETURNED.

## OpenAPI Specs

- [openapi](/openapi.json)