> ## Documentation Index > Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt > Use this file to discover all available pages before exploring further. # One of a template’s documents, filled in with your values, as it would be sealed. > SEE A BINDING BEFORE YOU SEND IT. Takes the `values` and `subjects` you would send to `POST /api/v1/envelopes` for this template and answers with one of its documents as a PDF, every value drawn exactly as the sealed copy would draw it — a value split across printed boxes one character per cell, a date in the form the field prints, the option of a question ticked, long text wrapped in its box — and PREVIEW across every page. Nothing is stored, sent, recorded or billed, and there is no envelope and nobody to sign. ⚠️ A PREVIEW THAT RENDERS IS ONE THE SEND WOULD ACCEPT. The values are judged by the same check as `POST /api/v1/templates/{templateId}/validate-values` and create, and the first one create would refuse is refused here with create’s code and create’s message — ask validate-values for every entry’s verdict at once. A `template_etag` that is no longer current is refused `template_changed`, as create refuses it. The send’s own checks on the answers it would fix are asked too, of every document of the template, and refused with the send’s code and sentence: a locked, required box left empty (`locked_answer_missing`), or a locked answer its own box refuses (`locked_answer_unusable`) — the template’s own fixed answers included. It also refuses, with `cannot_be_drawn`, a value too long for its box even at the smallest size the sealed copy prints: create accepts that value, and the envelope would then fail to seal after every signature. ⚠️ THERE ARE NO RECIPIENTS, SO EVERY ROLE IS DRAWN AS IF IT IS ON THE ENVELOPE, held by one person — an optional role included, so you see the whole form. For the send’s checks your `values` stand in for the recipients: an optional role is on the envelope when one of them fills one of its boxes, and left out otherwise, as a send leaves out an optional role nobody is named for; a left-out role’s boxes are drawn but not checked, and leaving out a role whose box decides another role’s box is refused as the send refuses it. A title or company box filled from a recipient’s details is neither drawn nor checked here. Boxes nobody gave a value stay blank, except an answer the template fixes itself. Boxes filled by signing — a signature, initials, the date of signing, the signer’s name and email — show whose they are, as `Signature: Employee`. `document` is the 1-based position of the document in `documents` on `GET /api/v1/templates/{templateId}`, and is required when the template holds more than one. ⚠️ IT IS A RENDER, AND IT SHARES A CEILING. Each preview that renders counts against your organisation’s per-minute ceiling on renders, which draft renders (`GET /api/v1/envelopes/{envelopeId}/documents/{position}/draft`) count against too; past it the answer is `rate_limited` with `Retry-After`. ⚠️ EVERY REQUEST PAST THE CREDENTIAL AND BODY CHECKS IS COUNTED, before the template is read — one refused for a value or a stale etag, and a `rate_limited` one, included. To check values without spending the ceiling, use validate-values, which renders nothing. ⚠️ IT NEEDS `documents:read` AS WELL AS `templates:read` (`x-additional-required-scopes`): what it answers with is the template’s document itself, which `templates:read` alone never grants. A key missing either is refused `insufficient_scope`. A test key and a live key get the same answer: a template has no environment. It is a POST only because the body can be large, and takes no `Idempotency-Key`. ## OpenAPI ````yaml /openapi.json post /api/v1/templates/{templateId}/preview openapi: 3.1.0 info: title: Vumasign API version: 0.2.0 description: >- The Vumasign API. South African e-signature: templates, the addresses an integration writes values to, an idempotent send, and webhooks. **This document describes what exists today and nothing else.** It is not a roadmap, and there is deliberately no entry here for anything that has not shipped — a spec you can generate a client from and then discover was aspirational is worse than no spec at all. ## Authentication Authorization: Bearer vsk_live_… One header, one step. Keys are minted in Settings. `vsk_live_` and `vsk_test_` are different keys; the prefix is stored in clear so a leaked key is greppable and traceable to an organisation, while the secret is stored only as a hash. ## Errors Every refusal the API returns deliberately, at every status, is `{ "error": { "code", "message" } }`, and such a response is a failure **if and only if** it carries an `error` key — that test is correct even for a client that ignores the status line. An unexpected server failure may not have this shape: treat a 5xx without an `error` key as an `internal_error`, which is retryable. `code` is the contract and is stable forever; `message` is prose for a developer reading a log and may be reworded in any release. The root of this document carries **`x-error-codes`**: the closed enum, with `status`, `retryable`, `backoff`, `emitted` and `guidance` for each code. Branch on that rather than on our prose. ## Rate limits **600 requests a minute on any paid plan, 60 on the free plan — and a test key gets the same number as a live one.** Per key, not per organisation, so a batch job and an interactive integration can be given a key each and neither can starve the other. The ceiling follows the PLAN rather than the kind of key, because the plan is what says whether this is production traffic or somebody evaluating us. On the API plan it is sized so that no honest workload meets it: a thousand envelopes with a status read each is two thousand requests, which is three and a half minutes rather than seventeen. The sandbox deliberately gets the *same* number rather than a larger one — an integration that passes in rehearsal is then an integration that passes live, and your `429` handling is exercised where meeting a `429` is free. Every successful authenticated response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the window closes, at most 60). Read them on your successes and you will never need to be refused. A 429 carries them too, and additionally carries `Retry-After`, which you should honour. A 401 carries none of them; a 403 may not, depending on whether it was decided before the request was counted. Each operation's responses say which others do. ⚠️ **A refused request still counts.** Retrying inside the window pushes the counter higher rather than holding it at the ceiling — which is why the backoff in `x-error-codes` is exponential and why `Retry-After` is worth reading rather than guessing at. ⚠️ The limits are **per minute**, and the window is fixed rather than sliding. Spending a whole window at the end of one minute and a whole window at the start of the next is possible; it is bounded at two windows' worth, which is a burst rather than an incident. ## Webhooks Register an endpoint with `POST /api/v1/webhooks`; the response carries the signing secret, **once**. The root of this document carries **`x-webhooks`**: the body we POST, the signature recipe (including the two mistakes that make a verifier look correct and be worthless), the published retry ladder, and the auto-disable rule. Read that before writing a receiver. ## What is not here yet No organisation-level email exists, so an auto-disabled webhook endpoint is discovered by polling rather than by being told. There is no way to change an envelope after it is created and before it is sent — `PATCH /v1/envelopes/{id}` is designed and not built — so a draft is created complete or not at all. Both are stated because a gap named is a gap somebody can plan around. ⚠️ **The rate limit above counts authenticated requests only.** A request carrying no key, or a key we cannot recognise, is refused before any counter is touched — a per-key ceiling cannot defend against a caller who has not presented a key, and pretending otherwise would be a promise we could not keep. That half belongs to the edge rather than to this API. (This section has twice described as missing something that now exists: the `uri` on every webhook body, which was `null` until `GET /api/v1/envelopes/{envelopeId}` gave it somewhere to point, and the rate limiter, which nothing enforced until the per-key ceiling above. Both were named here as gaps first, which is the point of naming them.) servers: - url: https://app.vumasign.com security: - ApiKey: [] tags: - name: Templates description: >- A template is a document with its signing roles and field placements authored once. Every envelope is made from one, or from a one-off pack. - name: Documents description: >- The pages of a template’s documents, served as PDF so that a client which has to show the paper can do so without rendering it itself. - name: Envelopes description: >- An envelope is one sending of a document to named people. Creating one is not sending it: a draft emails nobody until it is sent. - name: Webhooks description: >- Endpoints we POST signed events to when an envelope changes, with the health of each endpoint and a secret you can rotate without a gap. - name: Standing authorisations description: >- A grantor’s signed, brand-wide authority for your organisation to apply their signature to documents you send under that brand. Requested here; it takes effect only when the grantor signs the mandate and it is sealed. See /concepts/standing-authorisations. - name: Specification description: >- This document, served without a credential so that anybody can read what the API does before they hold a key. paths: /api/v1/templates/{templateId}/preview: post: tags: - Templates summary: >- One of a template’s documents, filled in with your values, as it would be sealed. description: >- SEE A BINDING BEFORE YOU SEND IT. Takes the `values` and `subjects` you would send to `POST /api/v1/envelopes` for this template and answers with one of its documents as a PDF, every value drawn exactly as the sealed copy would draw it — a value split across printed boxes one character per cell, a date in the form the field prints, the option of a question ticked, long text wrapped in its box — and PREVIEW across every page. Nothing is stored, sent, recorded or billed, and there is no envelope and nobody to sign. ⚠️ A PREVIEW THAT RENDERS IS ONE THE SEND WOULD ACCEPT. The values are judged by the same check as `POST /api/v1/templates/{templateId}/validate-values` and create, and the first one create would refuse is refused here with create’s code and create’s message — ask validate-values for every entry’s verdict at once. A `template_etag` that is no longer current is refused `template_changed`, as create refuses it. The send’s own checks on the answers it would fix are asked too, of every document of the template, and refused with the send’s code and sentence: a locked, required box left empty (`locked_answer_missing`), or a locked answer its own box refuses (`locked_answer_unusable`) — the template’s own fixed answers included. It also refuses, with `cannot_be_drawn`, a value too long for its box even at the smallest size the sealed copy prints: create accepts that value, and the envelope would then fail to seal after every signature. ⚠️ THERE ARE NO RECIPIENTS, SO EVERY ROLE IS DRAWN AS IF IT IS ON THE ENVELOPE, held by one person — an optional role included, so you see the whole form. For the send’s checks your `values` stand in for the recipients: an optional role is on the envelope when one of them fills one of its boxes, and left out otherwise, as a send leaves out an optional role nobody is named for; a left-out role’s boxes are drawn but not checked, and leaving out a role whose box decides another role’s box is refused as the send refuses it. A title or company box filled from a recipient’s details is neither drawn nor checked here. Boxes nobody gave a value stay blank, except an answer the template fixes itself. Boxes filled by signing — a signature, initials, the date of signing, the signer’s name and email — show whose they are, as `Signature: Employee`. `document` is the 1-based position of the document in `documents` on `GET /api/v1/templates/{templateId}`, and is required when the template holds more than one. ⚠️ IT IS A RENDER, AND IT SHARES A CEILING. Each preview that renders counts against your organisation’s per-minute ceiling on renders, which draft renders (`GET /api/v1/envelopes/{envelopeId}/documents/{position}/draft`) count against too; past it the answer is `rate_limited` with `Retry-After`. ⚠️ EVERY REQUEST PAST THE CREDENTIAL AND BODY CHECKS IS COUNTED, before the template is read — one refused for a value or a stale etag, and a `rate_limited` one, included. To check values without spending the ceiling, use validate-values, which renders nothing. ⚠️ IT NEEDS `documents:read` AS WELL AS `templates:read` (`x-additional-required-scopes`): what it answers with is the template’s document itself, which `templates:read` alone never grants. A key missing either is refused `insufficient_scope`. A test key and a live key get the same answer: a template has no environment. It is a POST only because the body can be large, and takes no `Idempotency-Key`. operationId: previewTemplate parameters: - name: templateId in: path required: true description: The template’s `id`, as returned by the list endpoint. schema: type: string format: uuid examples: - 01960000-0000-4000-8000-0000000007e1 description: A template id. requestBody: required: true description: >- The `values` and `subjects` you would send to create, and optionally `template_etag` and `document`. content: application/json: schema: $ref: '#/components/schemas/TemplatePreviewRequest' description: The values to draw. examples: example: summary: A made-up employee, against the template as it was read value: values: - subject: employee key: staff.full_name value: Thandi Mokoena template_etag: >- "53d359af89429682ddcbf8915f330bd61d2e40fb48f6bc94a76010bea48bba1f" document: 1 responses: '200': description: >- The document, filled in and marked PREVIEW on every page. `Content-Disposition: attachment; filename="