> ## 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. # What creating an envelope would say about your values, without creating one. > CHECK A BINDING BEFORE YOU SEND. Takes the `values` and `subjects` you would send to `POST /api/v1/envelopes` for this template and answers, for EVERY entry, what create would do with it — where create stops at the first refusal. It writes nothing and needs no `Idempotency-Key`; it is a POST only because the body can be large. ⚠️ 200 WHENEVER THE REQUEST ITSELF IS WELL FORMED, whatever the verdicts. `ok` in the body is the answer. Each refused entry carries the `status` and the sentence create would refuse it with, and when several are refused, create answers the first `duplicate_address` if there is one, and otherwise the lowest `index`. ⚠️ IT ASKS ONLY WHAT CREATE ASKS OF `values`. It does not check `validation_type` or masks (create does not), the recipients (they are a property of a send, not of a binding), or whether the template can make an envelope at all. A `subjects` map the template refuses is answered `invalid_request`, with create’s sentence. A test key and a live key get the same answer: a template has no environment. ## OpenAPI ````yaml /openapi.json post /api/v1/templates/{templateId}/validate-values 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}/validate-values: post: tags: - Templates summary: >- What creating an envelope would say about your values, without creating one. description: >- CHECK A BINDING BEFORE YOU SEND. Takes the `values` and `subjects` you would send to `POST /api/v1/envelopes` for this template and answers, for EVERY entry, what create would do with it — where create stops at the first refusal. It writes nothing and needs no `Idempotency-Key`; it is a POST only because the body can be large. ⚠️ 200 WHENEVER THE REQUEST ITSELF IS WELL FORMED, whatever the verdicts. `ok` in the body is the answer. Each refused entry carries the `status` and the sentence create would refuse it with, and when several are refused, create answers the first `duplicate_address` if there is one, and otherwise the lowest `index`. ⚠️ IT ASKS ONLY WHAT CREATE ASKS OF `values`. It does not check `validation_type` or masks (create does not), the recipients (they are a property of a send, not of a binding), or whether the template can make an envelope at all. A `subjects` map the template refuses is answered `invalid_request`, with create’s sentence. A test key and a live key get the same answer: a template has no environment. operationId: validateTemplateValues 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 nothing else. content: application/json: schema: $ref: '#/components/schemas/ValidateValuesRequest' description: The values to judge. examples: example: summary: One address right, and the same key without its subject value: values: - subject: employee key: full_name value: Thandi Mokoena - subject: null key: full_name value: Thandi Mokoena responses: '200': description: >- A verdict for every entry of `values`, in the order sent, and `ok` saying whether create would accept them all. A refused entry is still a 200: the request was well formed. content: application/json: schema: $ref: '#/components/schemas/ValidateValuesResponse' description: The verdicts. examples: example: summary: The second would be refused at create value: ok: false results: - index: 0 status: ok fields: 1 - index: 1 status: value_address_unknown message: >- `values[1]`: no field of this template is addressed (null, "full_name"). A value that matches nothing would leave the box blank and report success, so it is refused instead. Nothing was created. headers: RateLimit-Limit: description: >- How many requests this key may make per minute: 600 on any paid plan and 60 on the free plan, the same in both environments. Per key, not per organisation — a second key has its own allowance. ⚠️ READ IT RATHER THAN ASSUMING IT: it is the number the database applied to this request, so it is right even when this description is out of date. schema: type: integer description: Requests permitted in the current minute. RateLimit-Remaining: description: >- How many of them are left, this one already counted. Zero on the request that is refused, and zero on every further request of that minute — ⚠️ a refused request still counts. schema: type: integer description: Requests remaining in the current minute. RateLimit-Reset: description: >- Seconds until the current minute closes and the allowance returns. At most 60, which is what makes the published exponential backoff converge in about six doublings rather than eleven. schema: type: integer description: Seconds until the window resets. '400': description: >- `invalid_request` — The request is malformed, or breaks a rule about its own shape: a body that is not JSON or does not match the operation’s schema (a missing or mistyped property, a value out of range), a document that is not a PDF or a Word file we can read, a text tag that cannot be placed, an `Idempotency-Key` that is present but not a valid key, a query parameter outside its range, or a cursor that names nothing. The `message` says which, and for a body names the property path (`recipients[0].email`) — there is no separate `param` field. Fix the request; retrying it unchanged will fail identically. content: application/json: schema: $ref: '#/components/schemas/Error' description: The refusal. '401': description: >- `unauthenticated` — The credential was absent, unreadable, unknown, wrong or revoked — this answer is deliberately identical for all of them, so it cannot be used to probe which keys exist. Retrying the same request changes nothing. Check the key in Settings or issue a new one. content: application/json: schema: $ref: '#/components/schemas/Error' description: The refusal. '403': description: >- `forbidden` — The key is valid and the organisation’s plan does not grant what this operation does. Nothing about the credential needs to change, and it is deliberately MORE specific than 401 because the caller has already proved they hold the key. TWO SITUATIONS PRODUCE IT. (1) THE PLAN EXCLUDES THE OPERATION: `POST /api/v1/templates` on the Free plan, which does not include authoring templates. A template that already exists stays readable at `GET /api/v1/templates`; authoring one needs a plan that includes templates. (2) WE CANNOT ESTABLISH WHAT THE PLAN INCLUDES, on any operation, so nothing is granted. That one is ours rather than yours, an ordinary account does not meet it, and it means ask us. `insufficient_scope` — This key is scoped and does not hold the scope this operation requires — `x-required-scope` on the operation names it, and the `WWW-Authenticate` header on the refusal repeats it (RFC 6750 §3.1). ⚠️ Retrying cannot help and neither can editing the key: scopes are fixed when a key is minted and no endpoint or screen can widen them. Issue a new key with the access it needs. A key created before scopes existed carries an empty scope list, which means EVERY capability, so this refusal cannot reach an integration that was already working. content: application/json: schema: $ref: '#/components/schemas/Error' description: The refusal. '404': description: >- `not_found` — No such resource — or none this key’s organisation can see, or one that has been archived, or an id that is not a uuid. Those four are one answer on purpose: "it exists but is not yours" is itself a disclosure. Do not retry; check the id against the list endpoint. content: application/json: schema: $ref: '#/components/schemas/Error' description: The refusal. '429': description: >- `rate_limited` — This key has spent its minute. The limit is per KEY and per minute, and it follows your PLAN rather than the kind of key — 600 requests a minute on every paid plan, 60 on the free plan, and the sandbox gets the same number as production so that an integration which passes in rehearsal passes live. Every successful authenticated response, and this one, carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds), so a client can slow down before it is made to. TWO OPERATIONS ALSO ANSWER IT FOR A REASON OF THEIR OWN. `POST /api/v1/envelopes/batches` costs one request per row and is refused WHOLE when its rows do not fit what is left of the key’s minute — `RateLimit-Remaining` says how many would. `GET /api/v1/envelopes/{envelopeId}/documents/{position}/draft` has its own per-envelope and per-organisation ceilings on renders each minute, and the `message` says which one refused; there `Retry-After` is that ceiling’s, while the `RateLimit-*` headers still describe the key. `Retry-After` on this refusal is at most 60 and is read from the stored window rather than computed, so two of our instances refusing the same key quote the same instant. ⚠️ A REFUSED REQUEST STILL COUNTS: hammering a limit you have already exceeded pushes the counter higher rather than holding it. Honour `Retry-After`. If one key genuinely needs more throughput, issue a second one in Settings — the ceiling is a fairness and blast-radius control, not a commercial meter. content: application/json: schema: $ref: '#/components/schemas/Error' description: The refusal. headers: RateLimit-Limit: description: >- How many requests this key may make per minute: 600 on any paid plan and 60 on the free plan, the same in both environments. Per key, not per organisation — a second key has its own allowance. ⚠️ READ IT RATHER THAN ASSUMING IT: it is the number the database applied to this request, so it is right even when this description is out of date. schema: type: integer description: Requests permitted in the current minute. RateLimit-Remaining: description: >- How many of them are left, this one already counted. Zero on the request that is refused, and zero on every further request of that minute — ⚠️ a refused request still counts. schema: type: integer description: Requests remaining in the current minute. RateLimit-Reset: description: >- Seconds until the current minute closes and the allowance returns. At most 60, which is what makes the published exponential backoff converge in about six doublings rather than eleven. schema: type: integer description: Seconds until the window resets. Retry-After: description: >- Seconds to wait before retrying, from the stored end of the window. Always present on a 429, and never more than 60. On the per-key limit it equals `RateLimit-Reset`; a narrower limit, such as the draft render allowance, has a window of its own and may ask for a different wait. `x-error-codes` tells you to honour it; this is it. schema: type: integer description: Seconds to wait before retrying. '500': description: >- `internal_error` — Ours, not yours. ⚠️ RETRY WITH THE SAME `Idempotency-Key` YOU SENT THE FIRST TIME, on any operation that takes one — that is what makes a retry safe here, and sending a NEW key would create a second envelope or send the same one twice. The safe GETs in this document can be retried freely. (This entry used to say every operation here was a GET; the write endpoints have since shipped, and the reasoning moved with them.) content: application/json: schema: $ref: '#/components/schemas/Error' description: The refusal. security: - ApiKey: [] components: schemas: ValidateValuesRequest: type: object description: >- The `values` and `subjects` you would send to `POST /api/v1/envelopes`, exactly as you would send them, and nothing else. properties: values: type: array description: >- Optional. Values to prefill, as triples. Omitted means none. ⚠️ A signature, a `date_signed`, a `signer_name` and a `signer_email` may not be prefilled — they are acts, or they are written by this system. items: $ref: '#/components/schemas/ValueInput' description: One value at one address. subjects: type: object additionalProperties: type: boolean description: '`true` if this subject is on the envelope, `false` if not.' examples: - spouse: true dependant_2: false description: >- Optional. WHO THIS ENVELOPE IS ABOUT, as a map from a subject `key` the template declares to `true` (on this envelope) or `false` (not). A field addressed to a subject that is not on the envelope is hidden from the signer and not required. A subject you do not name takes the template’s own rule: a `required` subject is on every envelope, and a `conditional` one is absent unless somebody says otherwise. Omitting `subjects` altogether opens the same sections as naming nobody — but see the next paragraph, because the two are not the same request. A key the template does not declare is refused, and so is `false` for a `required` subject — both `invalid_request`, and nothing is created. ⚠️ IT SETS WHAT THE DOCUMENT OPENS WITH, NOT WHAT IT MUST STAY. The signer can switch a `conditional` subject on or off on the signing page, in either direction, and every such change is recorded in the envelope’s audit history. ⚠️ NAME AS `true` EVERY `conditional` SUBJECT YOU PREFILL. A value in `values` for a `conditional` subject you did not name as present is handled in one of two ways, depending on whether `subjects` is in the request at all: - **`subjects` sent** (even `{}`): the subject is absent — by `false`, or by the template’s rule when unnamed — so the value contradicts the request and is refused with `invalid_request`. Nothing is created. - **`subjects` omitted**: the value is accepted and stored, but the subject is absent by the template’s rule when the envelope is sent, so the prefilled section opens HIDDEN until the signer switches it on. See [Subjects](https://docs.vumasign.com/concepts/subjects). ValidateValuesResponse: type: object description: Every entry’s verdict, in the order sent. properties: ok: type: boolean description: >- `true` only when every entry is `ok`: create would accept these values. results: type: array description: One result per entry of `values`, in the same order. items: $ref: '#/components/schemas/ValueResult' description: One entry’s verdict. required: - ok - results Error: type: object description: >- The body of every refusal the API returns deliberately, at every status, from every endpoint. 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, which is a thing real clients do. An unexpected server failure may not have this shape: treat a 5xx without an `error` key as an `internal_error`, which is retryable. properties: error: type: object description: The refusal. Anything added in future is added INSIDE this object. properties: code: type: string description: >- A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code. enum: - unauthenticated - forbidden - insufficient_scope - not_found - invalid_request - rate_limited - internal_error - service_unavailable - idempotency_key_required - idempotency_key_reused - request_in_progress - template_archived - template_unusable - template_has_no_fields - recipient_role_unknown - recipient_role_missing - recipient_role_duplicated - value_subject_unknown - value_address_unknown - value_not_writable - value_not_lockable - locked_answer_missing - locked_answer_unusable - cannot_be_drawn - send_allowance_exhausted - test_key_cannot_send - test_key_cannot_read_documents - test_key_cannot_mint - webhook_url_invalid - webhook_events_invalid - webhook_brand_unknown - webhook_limit_reached - api_key_owner_removed - envelope_sender_removed - recipient_not_embedded - recipient_not_yet_turn - recipient_cannot_sign - envelope_not_sent - envelope_not_draft - brand_has_no_embed_origins - recipient_cannot_be_embedded - recipient_verification_unavailable - recipient_mobile_unused - recipient_verification_not_allowed - batch_interrupted - brand_unknown - draft_not_available - standing_authorisations_not_enabled - authorisation_text_rejected - authorisation_validity_invalid - authorisation_not_revocable - authorisation_not_pending - authorisation_resend_limited - authorisation_not_renewable - authorisation_already_renewed - authorisation_unknown - authorisation_not_granted - authorisation_revoked - authorisation_expired - authorisation_not_yet_valid - authorisation_invalidated - authorisation_brand_mismatch - authorisation_environment_mismatch - authorisation_role_is_witness - authorisation_role_not_signing - authorisation_recipient_altered - authorisation_used_twice - authorisation_grantor_twice - authorisation_field_unsupported - authorisation_value_forbidden - authorisation_value_missing - authorisation_value_unlocked - authorisation_mark_too_small - authorisation_mark_unplaced - authorisation_without_signer - authorisation_mark_unavailable - authorisation_expires_during_batch message: type: string description: >- ⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design. required: - code - message required: - error ValueInput: type: object description: One value, at one address. See the note above about triples. required: - subject - key - value properties: subject: type: - string - 'null' examples: - tenant description: >- A `key` from the template’s `subjects` — WHOSE datum this is — or `null` for a field belonging to nobody in particular. Required as a property: `null` and "I did not say" must not be two spellings of one thing. key: type: string examples: - full_name description: The field’s `data_key`, exactly as the template endpoint reports it. value: type: string examples: - Thandi Mokoena description: >- What to write. It lands in EVERY field at this address, which is the point. An address that matches nothing is refused rather than dropped. locked: type: boolean examples: - true description: >- Optional. `true` fixes this answer: the signer reads it and cannot change it, and a submission that tries is refused. Use it when your own records are the authority and a signed form contradicting them would help nobody. ⚠️ IT RIDES ON THE VALUE ON PURPOSE, so you cannot lock an address without saying in the same breath what it is locked TO. To hand a field back to the signer, send `{"value": "", "locked": false}`: the empty string already means *clear this*. ⚠️ `{"value": "", "locked": true}` IS ACCEPTED, and it means "this box stays empty and the signer may not fill it". It is the spelling a grouped tickbox needs — five locked, empty options of a Race question, each saying *not this one* — so it is not refused. Earlier versions of this text said it could not be expressed at all; that was wrong. ⚠️ A LOCKED ANSWER SURVIVES BEING HIDDEN AND SHOWN AGAIN. A signer can make a section disappear — by answering the question a condition reads, or by declaring that a `subject` is not on the document — and the answers under it are removed, so nothing unasked is printed. A locked answer is yours rather than theirs, so it is kept separately and comes back the moment the section does. You do not have to re-send it, and no gesture available to the signer can destroy it. ⚠️ ON A TICKBOX, AN EMPTY VALUE IS RECORDED AS `false`. The two already mean the same thing to everything that reads or draws a tickbox; storing one spelling is what keeps *not this one* a single sentence. Every other type keeps exactly what you sent. ⚠️ OMITTING IT LEAVES THE FIELD AS THE TEMPLATE HAD IT, which is not the same as sending `false`. A sender can lock a field in the editor; absence respects that, `false` overrides it. ⚠️ AN ADDRESS MAY NAME SEVERAL BOXES AND THIS LOCKS ALL OF THEM — the same rule `value` follows. Two shapes of empty lock refuse the SEND with `locked_answer_missing`, because nobody left could supply the answer: a field that is locked, `required` and carries no value; and a QUESTION whose `min_selected` is out of reach because its options are locked and unticked. An optional, ungrouped box that is locked and empty is neither, and seals blank as it says. ⚠️ AND NEITHER REFUSAL LOOKS AT A BOX ABOUT SOMEBODY THIS ENVELOPE IS NOT ABOUT. A field carrying a `subject` you declared absent in `subjects` — or one the template marks optional and nobody declared — is hidden from the signer and cannot block the document, so a lock on it moved no demand and there is nothing to refuse. This is what lets one template carry a locked spouse section and still send to somebody who has no spouse: `subjects` decides who the envelope is about, and these refusals are about the people it IS about. ValueResult: type: object description: >- What create would say about one entry of `values`. An `ok` entry carries `fields`; every other entry carries `message`. properties: index: type: integer minimum: 0 description: The entry’s position in the `values` you sent. status: type: string enum: - ok - duplicate_address - value_subject_unknown - subject_declared_absent - value_address_unknown - value_not_writable - value_not_lockable - cannot_be_drawn description: >- `ok`: Create would accept this entry. `fields` counts the boxes it would fill. `duplicate_address` (create answers `invalid_request`): An earlier entry already gave a value for this address. One address takes one value, however many boxes it fills. `value_subject_unknown`: The template declares no subject with this key. `subject_declared_absent` (create answers `invalid_request`): The `subjects` map says this subject is not on the envelope — by `false`, or by the template’s rule for a `conditional` subject it does not name — and this entry gives a value for them. `value_address_unknown`: No field of the template carries this `(subject, key)` address. `value_not_writable`: A field at this address is of a type nobody may prefill (`signature`, `initial`, `attachment`, `date_signed`, `signer_name`, `signer_email`), or it is a dropdown that has options and the value is not one of them. A dropdown with no options is not checked, and takes any value. `value_not_lockable`: `locked: true` on a field of a type whose answer belongs to whoever fills the role rather than to the box (`signer_title`, `signer_company`). `cannot_be_drawn`: The value has a character the document’s font cannot draw, so the sealed document could not show it. fields: type: integer minimum: 1 description: >- On an `ok` entry only: how many boxes the value would fill. One address may fill several. message: type: string description: 'On a refused entry only: the sentence create would refuse it with.' required: - index - status securitySchemes: ApiKey: type: http scheme: bearer description: >- `Authorization: Bearer vsk_live_…`. Chosen over a bespoke `X-API-KEY` header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see `x-scopes` at the root of this document and `x-required-scope` on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for `oauth2` and `openIdConnect` and requires it to be empty for an `http` scheme. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.