Upload a PDF or a Word document and get a template with its fields already placed.
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.
⚠️ FIRST, CHECK THIS IS THE RESOURCE YOU WANT. A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in GET /api/v1/templates and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want POST /api/v1/envelopes/one-off instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: template_id comes back null. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused template_has_no_fields there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted.
⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE.
⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured.
Text tags — write the field into the document where it goes, and it arrives placed and already assigned to the right signer:
<<sig:Main Member>> a signature for the role named<<text:Witness:Home address>> a labelled text box<<title:Main Member>> the signer’s job title, prefilled<<datesigned:Main Member>> the date they signed, stamped<<text:Witness:optional>> a box they may leave empty<<text:Witness:validate(email)>> checked as an email address<<sig:Main Member:dimension(60x15mm)>> say the size, do not pad the tag<<text:Employee:key(employment.employee_number)>> the api name a value addresses<<check:Employee:question(medical_aid.plan):option(classic_smart):Classic Smart>> one box of a question; each box says it<<check:Employee:question(benefits.extras):option(dental):select(0-3):Dental>> on any one box: up to three ticked<<text:Employee:ID number:cells(13)>> thirteen printed boxes, one character each<<dateinput:Employee:Date of birth (DD/MM/YYYY):cells(8)>> a date in eight printed boxes, day first<<text:Employee:Mobile number:key(person.mobile_number):cells(3):part(1)>> one answer in two sets of boxes,<<text:Employee:Mobile number:key(person.mobile_number):cells(7):part(2)>> filled part(1) first
Types: sig, signature, initial, text, dateinput, check, checkbox, title, company, name, email, datesigned. <<sig:Main Member>> names the role EXACTLY and case-sensitively; <<sig:signerN>> names it BY POSITION — signer1 is the first entry in your roles array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: optional, validate(<type>), dimension(WxH mm|pt) and key(<name>) — which sets the field’s data_key, stored lower-cased, so address it in lower case when you prefill; the name is a core key (GET /api/v1/vocabulary) or follows the naming grammar, namespace.attribute, and any other refuses the request. A QUESTION is declared on its tickbox tags: every box of it says question(<key>) — the question’s data_key, a choice key of the core (only its own options) or one in the grammar — and option(<value>), its option_value; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says select(0-3), select(2) or select(1-*) (* is every box), and named by ask(<wording>) on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no key(...) and no optional. PRINTED BOXES:cells(<n>) on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a key(...) and a subject, each with cells(<n>) and part(<k>), are ONE field filled in k order — part(1) first — returned with cells and continuations; a part needs both cells(...) and key(...), and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with dimension(...). A DATE IN PRINTED BOXES is a dateinput tag with cells(8), or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: order(DD/MM/YYYY), order(MM/DD/YYYY) or order(YYYY/MM/DD) on the tag or one part, or in the label, as Date of birth (DD/MM/YYYY). It is a date field whose value is its digits in the order the boxes print them — 16082026 for 16 August 2026, day first; a value sent as YYYY-MM-DD is accepted too and laid into the boxes in that order — and a date tag with cells(...) and no order refuses the request. Detection names nothing: a detected field arrives with no data_key, and a detected question with none either, each box with a proposed option_value; name them with PATCH .../fields. A segment shaped like name(...) is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without cells(...), a condition, a dropdown’s options or a validate(regex) pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards.
⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows.
⚠️ BUT THAT SAYS NOTHING ABOUT WHICH ENDPOINT, and this paragraph used to be read as though it did. POST /api/v1/envelopes/one-off accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient.
⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 invalid_request, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print <<sig:Main Member>> on a document somebody signs.
⚠️ WHO A FIELD IS ABOUT — subject(dependant_2). Declare the people the document asks about in subjects, then address a field to one of them. A field addressed to somebody who is not on a given envelope is hidden and not required, automatically, with no condition to write:
<<text:Employee:subject(dependant_2):Surname>>
The argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does.
⚠️ AND THE SUBJECT MUST BE conditional FOR ANY OF IT TO MATTER. A required subject is on every envelope and can never be absent, which is the safe default; conditional is the one the caller or the signer decides about. A medical-aid application declaring spouse and dependant_1..3 as conditional asks for none of them until somebody says that person exists — which is the whole point.
⚠️ WHERE THE FIELD LANDS, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is centred vertically on the tag’s line — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. dimension() replaces both, and is placed the same way.
⚠️ SO WRITE THE TAG ON THE LINE ABOVE A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew:
<<sig:Employee>> <<datesigned:Employee>>______________________ ______________________Employee name Date
The signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; dimension() sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it.
Sizes by tag: sig or signature 40pt tall, at least 120pt wide; initial 40pt tall, at least 40pt wide; dateinput 18pt tall, at least 80pt wide; text 18pt tall, at least 80pt wide; check or checkbox 14pt tall, at least 14pt wide; title 15.2pt tall, at least 131pt wide; company 15.2pt tall, at least 131pt wide; name 15.2pt tall, at least 131pt wide; email 15.2pt tall, at least 166.6pt wide; datesigned 15.2pt tall, at least 89pt wide.
⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well.
⚠️ AND THE DELIMITER IS << >> BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every {-based templating engine destroys a {{ }} tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. << >> is untouched by all three, so your merge fields ({employee.full_name}, {#clause}…{/}) and your tags coexist with nothing to reconfigure. A {{type:Role}} tag is refused by name rather than ignored, as is Dropbox Sign’s [sig|req|signer1], so neither can be uploaded silently and printed on a signed document.
✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. file takes a Word .docx as well as a PDF — decided by the BYTES, so there is no content_type to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the .docx. We render it, and the tags survive that render, which is the whole reason they are text.
A Word document (.docx) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later GET refer to, and it is what a signer sees. The .docx you sent is retained unchanged and is not what anybody signs.
⚠️ THE OLDER .doc IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a .docx.
Detection, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-cc role, for you to reassign.
⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. fields being empty is how you tell.
The document travels base64-encoded inside the JSON body rather than as multipart/form-data, so one media type and one HTTP client serve every endpoint of this API. See file for what that costs and what it bounds.
A vsk_test_ key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.
POST
/
api
/
v1
/
templates
Upload a PDF or a Word document and get a template with its fields already placed.
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.
Headers
Idempotency-Key
string
required
Any string that identifies this request; a UUID is the usual choice, and at most 255 characters. ⚠️ REQUIRED, because an upload is the request most likely to lose its answer — the body is the largest this API accepts and the reply comes after the document has been parsed twice. Retrying with the same key returns the same template rather than authoring a second one from the same document.
⚠️ AND IT IS ANSWERED CONSERVATIVELY IN ONE CASE. If a previous request under this key stopped partway and this API cannot establish whether it created a template, you are told so with request_in_progress and asked to look — it will not guess, because a wrong guess is a second template. Call GET /api/v1/templates; if it is not there, retry with a NEW key.
The caller’s own request identifier.
Example:
"01960000-0000-4000-8000-00000000ffff"
Body
application/json
The document, base64-encoded, and who signs it.
The document and its roles.
file
string
required
⚠️ THE WHOLE DOCUMENT, BASE64-ENCODED, AND THE EXAMPLE ABOVE IS A TRUNCATED STUB — replace it with your own document’s bytes or the request is refused as unreadable. A PDF or a Word .docx; the BYTES decide which, so there is no content_type field to get wrong, and a .docx is converted to PDF on our side. Standard alphabet only: no data: prefix, no whitespace, no line wrapping, and not the URL-safe -/_ variant. Base64 is about a third larger than the file it carries, and the whole request body is bounded at 8388608 bytes — so roughly 6291456 bytes of document, whatever its format or page count.
Who signs it, in order, at least one and at most 20. ⚠️ THE ORDER IS LOAD-BEARING: it is a role’s position in the recipient list and its colour in the editor. When each role is asked is its step: from role_steps when given, otherwise one at a time in this order under signing_mode: sequential, or all together. Every field detected in the document is allocated to the first role that is not a cc, because a page cannot say which of three signers writes in a box; reassign them in the editor afterwards. Each comes back with an id, but nothing accepts it as input today — see Field.id.
One role’s name.
filename
string
Optional. Used only to NAME the template when name is absent and the document has no title we can read, exactly as the upload box suggests a name from the file you dropped on it: the extension goes, underscores become spaces, and a slug such as offer-of-employment-for-sales-staff.pdf reads “Offer of employment for sales staff”. Other hyphens are kept. It never reaches storage — the object key is the content hash.
Example:
"employment-contract.pdf"
name
string
Optional. What to call the template. Absent or blank falls back to the title printed at the top of the document’s first page, when it clearly has one; then to filename; and then to “Untitled document”. A name you send is never replaced. ⚠️ A name that is SENT and cannot be stored is refused, while a name that is not sent is not — a template’s name is editable afterwards, and refusing an upload over one would be a wall in front of the thing this endpoint exists to make free.
Example:
"Employment contract"
routing_types
enum<string>[]
Optional. One entry per role, in the same order. ⚠️ IF YOU SEND IT AT ALL IT MUST HAVE EXACTLY ONE ENTRY PER ROLE — a short list is refused rather than padded, because from an API caller a short list is far more likely to be an off-by-one than an intention. Omit it entirely and every role signs. A cc is never asked to fill anything in, which is why detected fields skip past one. ⚠️ IT IS SENT THE FINISHED COPY ONLY WHEN WE SEND THE COMPLETION NOTICES — completion_delivery: vumasign, the default for an envelope sent from the dashboard. Under integrator, the default for an envelope sent with an API key, nobody is sent anything at completion, a cc included: telling them is yours.
What this role is asked to do.
Available options:
sign,
approve,
cc
role_kinds
enum<string>[]
Optional. One entry per role, in the same order: party (the default) or witness. A short list is refused rather than padded, as routing_types is. A role marked witness is pre-signed under a standing authorisation only under one granted for witness use. A role whose name contains “witness” or “getuie” anywhere, in any case is treated as a witness for that purpose whatever its kind.
What this role is.
Available options:
party,
witness
role_presences
enum<string>[]
Optional. One entry per role, in the same order: required (every envelope needs somebody for it) or optional (an envelope may be sent without it: omit its recipient and the role is left out, with every field it holds). A short list is refused rather than padded, as role_kinds is. Omit it and every role is required. Ignored for a cc role. Read back as Role.presence.
Whether this role can be left out.
Available options:
required,
optional
role_steps
integer[]
Optional. One entry per role, in the same order: when that role is asked. Everyone in the lowest step that still has something to do is asked together, and the next step opens when that one is finished; roles may share a step, and steps may skip numbers. A short list is refused rather than padded, as routing_types is. ⚠️ NOT WITH signing_mode: giving both is refused as step_with_signing_mode. Omit it and signing_mode decides. Each role’s step is read back as Role.step. A send does not use these unless it passes them: see step on a recipient.
When this role is asked.
Required range: 1 <= x <= 2147483647
signing_mode
enum<string>
Optional, default parallel — everybody is asked at once. sequential asks them in the order roles is written, each invitation going out only when the one before it is finished. ⚠️ NOT WITH role_steps.
Available options:
parallel,
sequential
Example:
"parallel"
name_fields
boolean
Optional. true starts a naming run as the template is created, and the 201 carries its naming_run_id; template.named says when it is ready. ⚠️ ONLY FOR A LIVE KEY THAT ALSO NAMES templates:name: otherwise the upload is refused (insufficient_scope or test_key_cannot_edit_templates) and nothing is created. templates:write alone never starts a run.
subjects
object[]
Optional. The people this document is ABOUT, as opposed to the roles who act on it — a spouse or a dependant on an application the main member signs — so that a subject(...) tag can address a field to one of them. A subject is a record of who the document describes, separate from the recipient records of who acts on it, and one person can be both. See Subjects. Omitted means none, and every subject(...) tag is then refused. At most 200. Two subjects with the same key, or with labels that differ only in case, are refused.
Maximum array length: 200
Show child attributes
Response
The template, in exactly the shape GET /api/v1/templates/{templateId} returns — same fields, same ids, same everything, because it is read back through the same function rather than assembled separately. Idempotency-Replayed says whether this request authored it (false) or is being shown an earlier one’s result (true); the status is 201 either way, deliberately, so a client branching on it behaves identically on a retry.
It also carries warnings: what the upload found worth telling you — today, personal information already printed on the document, which every envelope sent from the template would carry.
The template, with every field’s id, the upload’s warnings and, with name_fields, its naming run.
id
string<uuid>
required
The template’s id. A bare uuid, no prefix.
name
string
required
What the sender called it.
created_at
string<date-time>
required
ISO 8601, UTC. Also the order this list is in — newest first.
warnings
object[]
required
What the template’s upload warned about, kept with the template: on the create response and on every read, so a template somebody uploaded on the dashboard says here what its upload said. Empty when there was nothing to say, and always present. A retry of the create’s Idempotency-Key answers with the same list.
Maximum array length: 10
Show child attributes
documents
object[]
required
The pack, in the order it is stacked.
Show child attributes
pages
object[]
required
⚠️ THE DENOMINATOR FOR EVERY Field.rect, and a client doing field matching cannot skip it: a rectangle of fractions is dimensionless without the page it is a fraction of. Join on (document_id, page), the same pair fields is joined by.
Every page of every document of the pack, in the pack’s order and then by page number — the order a signer scrolls.
Show child attributes
roles
object[]
required
The signing roles, in the template’s order. When each is asked is its step.
Show child attributes
subjects
object[]
required
The people whose data this template collects.
Show child attributes
questions
object[]
required
The tickbox questions and how many answers each takes.
Show child attributes
fields
object[]
required
⚠️ A FLAT LIST, NOT A MAP KEYED BY ADDRESS. Several fields sharing one (subject, data_key) pair is NORMAL — real forms ask for an ID number on the application and again on the declaration, and initials in the footer of all nine pages. A value supplied for an address means it for every box that asks.
Show child attributes
coverage
object
required
How much of the template your integration can address, counted by the same code as the editor’s coverage line, so the two always agree. Part of the body, so the template’s ETag changes when it does.
Show child attributes
naming_run_id
string<uuid>
Present only when name_fields was true: the run naming the template. Read it, or wait for template.named.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Vumasign","description":"The Vumasign API: templates, envelopes, embedded signing and signed webhooks.","colors":{"primary":"#00827B","light":"#30B3AB","dark":"#00827B"},"logo":{"light":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/vumasign.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=f5e34bf1faf4c64eaa58dee0553702d6","dark":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/vumasign-dark.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=6288e3bd6e02af7f9ef27aa71b7df32c","href":"https://vumasign.com"},"favicon":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/favicon.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=ca1830bf11181e8ce259f0ca820ba7a9","api":{"openapi":"openapi.json","playground":{"display":"interactive"},"examples":{"defaults":"required","languages":["curl","python","javascript","go"],"prefill":true}},"background":{"color":{"light":"#F7F7F8","dark":"#0F1419"}},"navbar":{"primary":{"type":"button","label":"Get an API key","href":"https://app.vumasign.com/settings/api-keys"}},"fonts":{"family":"Inter"},"icons":{"library":"lucide"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"vumasign","hasAudioNarration":false,"actualSubdomain":"vumasign","customDomains":["docs.vumasign.com"],"gitSource":{"type":"github","owner":"hellocrowd","repo":"vumasign","deployBranch":"main","contentDirectory":"docs-site","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6afa8fa53b9b1d7bae84e26b","clientVersion":"0.0.4160","searchFilterCounts":[{"language":"default","tag":"API reference","count":49},{"language":"default","tag":"Guides","count":34},{"language":"default","tag":"Concepts","count":17},{"language":"default","tag":"Templates","count":17},{"language":"default","tag":"Envelopes","count":12},{"language":"default","tag":"Standing authorisations","count":7},{"language":"default","tag":"Webhooks","count":6},{"language":"default","tag":"Get started","count":5},{"language":"default","tag":"Brands","count":4},{"language":"default","tag":"Documents","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/create-template","slug":"/api-reference/create-template","pageMetadata":{"title":"Upload a PDF or a Word document and get a template with its fields already placed.","description":"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.\n\n⚠️ **FIRST, CHECK THIS IS THE RESOURCE YOU WANT.** A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in `GET /api/v1/templates` and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want `POST /api/v1/envelopes/one-off` instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: `template_id` comes back `null`. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused `template_has_no_fields` there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted.\n\n⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE.\n\n⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured.\n\n**Text tags** — write the field into the document where it goes, and it arrives placed and already assigned to the right signer:\n\n```\n\u003c\u003csig:Main Member>> a signature for the role named\n\u003c\u003ctext:Witness:Home address>> a labelled text box\n\u003c\u003ctitle:Main Member>> the signer’s job title, prefilled\n\u003c\u003cdatesigned:Main Member>> the date they signed, stamped\n\u003c\u003ctext:Witness:optional>> a box they may leave empty\n\u003c\u003ctext:Witness:validate(email)>> checked as an email address\n\u003c\u003csig:Main Member:dimension(60x15mm)>> say the size, do not pad the tag\n\u003c\u003ctext:Employee:key(employment.employee_number)>> the api name a value addresses\n\u003c\u003ccheck:Employee:question(medical_aid.plan):option(classic_smart):Classic Smart>> one box of a question; each box says it\n\u003c\u003ccheck:Employee:question(benefits.extras):option(dental):select(0-3):Dental>> on any one box: up to three ticked\n\u003c\u003ctext:Employee:ID number:cells(13)>> thirteen printed boxes, one character each\n\u003c\u003cdateinput:Employee:Date of birth (DD/MM/YYYY):cells(8)>> a date in eight printed boxes, day first\n\u003c\u003ctext:Employee:Mobile number:key(person.mobile_number):cells(3):part(1)>> one answer in two sets of boxes,\n\u003c\u003ctext:Employee:Mobile number:key(person.mobile_number):cells(7):part(2)>> filled part(1) first\n```\n\nTypes: `sig`, `signature`, `initial`, `text`, `dateinput`, `check`, `checkbox`, `title`, `company`, `name`, `email`, `datesigned`. `\u003c\u003csig:Main Member>>` names the role EXACTLY and case-sensitively; `\u003c\u003csig:signerN>>` names it BY POSITION — `signer1` is the first entry in your `roles` array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: `optional`, `validate(\u003ctype>)`, `dimension(WxH mm|pt)` and `key(\u003cname>)` — which sets the field’s `data_key`, stored lower-cased, so address it in lower case when you prefill; the name is a core key (`GET /api/v1/vocabulary`) or follows the naming grammar, `namespace.attribute`, and any other refuses the request. **A QUESTION** is declared on its tickbox tags: every box of it says `question(\u003ckey>)` — the question’s `data_key`, a choice key of the core (only its own options) or one in the grammar — and `option(\u003cvalue>)`, its `option_value`; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says `select(0-3)`, `select(2)` or `select(1-*)` (`*` is every box), and named by `ask(\u003cwording>)` on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no `key(...)` and no `optional`. **PRINTED BOXES:** `cells(\u003cn>)` on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a `key(...)` and a subject, each with `cells(\u003cn>)` and `part(\u003ck>)`, are ONE field filled in k order — part(1) first — returned with `cells` and `continuations`; a part needs both `cells(...)` and `key(...)`, and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with `dimension(...)`. **A DATE IN PRINTED BOXES** is a `dateinput` tag with `cells(8)`, or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: `order(DD/MM/YYYY)`, `order(MM/DD/YYYY)` or `order(YYYY/MM/DD)` on the tag or one part, or in the label, as `Date of birth (DD/MM/YYYY)`. It is a `date` field whose value is its digits in the order the boxes print them — `16082026` for 16 August 2026, day first; a value sent as `YYYY-MM-DD` is accepted too and laid into the boxes in that order — and a date tag with `cells(...)` and no order refuses the request. Detection names nothing: a detected field arrives with no `data_key`, and a detected question with none either, each box with a proposed `option_value`; name them with `PATCH .../fields`. A segment shaped like `name(...)` is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without `cells(...)`, a condition, a dropdown’s options or a `validate(regex)` pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards.\n\n⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows.\n\n⚠️ BUT THAT SAYS NOTHING ABOUT **WHICH ENDPOINT**, and this paragraph used to be read as though it did. `POST /api/v1/envelopes/one-off` accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient.\n\n⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 `invalid_request`, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print `\u003c\u003csig:Main Member>>` on a document somebody signs.\n\n⚠️ **WHO A FIELD IS ABOUT** — `subject(dependant_2)`. Declare the people the document asks about in `subjects`, then address a field to one of them. A field addressed to somebody who is not on a given envelope is **hidden and not required, automatically**, with no condition to write:\n\n```\n\u003c\u003ctext:Employee:subject(dependant_2):Surname>>\n```\n\nThe argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does.\n\n⚠️ AND THE SUBJECT MUST BE `conditional` FOR ANY OF IT TO MATTER. A `required` subject is on every envelope and can never be absent, which is the safe default; `conditional` is the one the caller or the signer decides about. A medical-aid application declaring `spouse` and `dependant_1..3` as conditional asks for none of them until somebody says that person exists — which is the whole point.\n\n⚠️ **WHERE THE FIELD LANDS**, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is **centred vertically on the tag’s line** — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. `dimension()` replaces both, and is placed the same way.\n\n⚠️ SO WRITE THE TAG ON THE LINE **ABOVE** A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew:\n\n```\n\u003c\u003csig:Employee>> \u003c\u003cdatesigned:Employee>>\n______________________ ______________________\nEmployee name Date\n```\n\nThe signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; `dimension()` sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it.\n\nSizes by tag: `sig` or `signature` 40pt tall, at least 120pt wide; `initial` 40pt tall, at least 40pt wide; `dateinput` 18pt tall, at least 80pt wide; `text` 18pt tall, at least 80pt wide; `check` or `checkbox` 14pt tall, at least 14pt wide; `title` 15.2pt tall, at least 131pt wide; `company` 15.2pt tall, at least 131pt wide; `name` 15.2pt tall, at least 131pt wide; `email` 15.2pt tall, at least 166.6pt wide; `datesigned` 15.2pt tall, at least 89pt wide.\n\n⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well.\n\n⚠️ AND THE DELIMITER IS `\u003c\u003c >>` BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every `{`-based templating engine destroys a `{{ }}` tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. `\u003c\u003c >>` is untouched by all three, so your merge fields (`{employee.full_name}`, `{#clause}…{/}`) and your tags coexist with nothing to reconfigure. A `{{type:Role}}` tag is refused by name rather than ignored, as is Dropbox Sign’s `[sig|req|signer1]`, so neither can be uploaded silently and printed on a signed document.\n\n✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. `file` takes a Word `.docx` as well as a PDF — decided by the BYTES, so there is no `content_type` to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the `.docx`. We render it, and the tags survive that render, which is the whole reason they are text.\n\nA Word document (`.docx`) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later `GET` refer to, and it is what a signer sees. The `.docx` you sent is retained unchanged and is not what anybody signs.\n\n⚠️ THE OLDER `.doc` IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a `.docx`.\n\n**Detection**, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-`cc` role, for you to reassign.\n\n⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. `fields` being empty is how you tell.\n\nThe document travels base64-encoded inside the JSON body rather than as `multipart/form-data`, so one media type and one HTTP client serve every endpoint of this API. See `file` for what that costs and what it bounds.\n\nA `vsk_test_` key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.","deprecated":null,"version":null,"sidebarTitle":"Create template","openapi":"/openapi.json post /api/v1/templates","href":"/api-reference/create-template","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n pre: \"pre\",\n span: \"span\",\n strong: \"strong\",\n ..._provideComponents(),\n ...props.components\n }, {CodeBlock} = _components;\n if (!CodeBlock) _missingMdxReference(\"CodeBlock\", true);\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"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 \", _jsx(_components.code, {\n children: \"id\"\n }), \" you need to address it. Nobody opens an editor.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ \", _jsx(_components.strong, {\n children: \"FIRST, CHECK THIS IS THE RESOURCE YOU WANT.\"\n }), \" A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in \", _jsx(_components.code, {\n children: \"GET /api/v1/templates\"\n }), \" and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want \", _jsx(_components.code, {\n children: \"POST /api/v1/envelopes/one-off\"\n }), \" instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: \", _jsx(_components.code, {\n children: \"template_id\"\n }), \" comes back \", _jsx(_components.code, {\n children: \"null\"\n }), \". ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused \", _jsx(_components.code, {\n children: \"template_has_no_fields\"\n }), \" there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Text tags\"\n }), \" — write the field into the document where it goes, and it arrives placed and already assigned to the right signer:\"]\n }), \"\\n\", _jsx(CodeBlock, {\n numberOfLines: \"15\",\n language: \"text\",\n children: _jsx(_components.pre, {\n className: \"shiki shiki-themes github-light-default dark-plus\",\n style: {\n backgroundColor: \"#ffffff\",\n \"--shiki-dark-bg\": \"#0B0C0E\",\n color: \"#1f2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n language: \"text\",\n children: _jsxs(_components.code, {\n language: \"text\",\n numberOfLines: \"15\",\n children: [_jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003csig:Main Member>> a signature for the role named\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctext:Witness:Home address>> a labelled text box\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctitle:Main Member>> the signer’s job title, prefilled\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003cdatesigned:Main Member>> the date they signed, stamped\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctext:Witness:optional>> a box they may leave empty\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctext:Witness:validate(email)>> checked as an email address\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003csig:Main Member:dimension(60x15mm)>> say the size, do not pad the tag\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctext:Employee:key(employment.employee_number)>> the api name a value addresses\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ccheck:Employee:question(medical_aid.plan):option(classic_smart):Classic Smart>> one box of a question; each box says it\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ccheck:Employee:question(benefits.extras):option(dental):select(0-3):Dental>> on any one box: up to three ticked\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctext:Employee:ID number:cells(13)>> thirteen printed boxes, one character each\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003cdateinput:Employee:Date of birth (DD/MM/YYYY):cells(8)>> a date in eight printed boxes, day first\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctext:Employee:Mobile number:key(person.mobile_number):cells(3):part(1)>> one answer in two sets of boxes,\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctext:Employee:Mobile number:key(person.mobile_number):cells(7):part(2)>> filled part(1) first\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {})\n })]\n })\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Types: \", _jsx(_components.code, {\n children: \"sig\"\n }), \", \", _jsx(_components.code, {\n children: \"signature\"\n }), \", \", _jsx(_components.code, {\n children: \"initial\"\n }), \", \", _jsx(_components.code, {\n children: \"text\"\n }), \", \", _jsx(_components.code, {\n children: \"dateinput\"\n }), \", \", _jsx(_components.code, {\n children: \"check\"\n }), \", \", _jsx(_components.code, {\n children: \"checkbox\"\n }), \", \", _jsx(_components.code, {\n children: \"title\"\n }), \", \", _jsx(_components.code, {\n children: \"company\"\n }), \", \", _jsx(_components.code, {\n children: \"name\"\n }), \", \", _jsx(_components.code, {\n children: \"email\"\n }), \", \", _jsx(_components.code, {\n children: \"datesigned\"\n }), \". \", _jsx(_components.code, {\n children: \"\u003c\u003csig:Main Member>>\"\n }), \" names the role EXACTLY and case-sensitively; \", _jsx(_components.code, {\n children: \"\u003c\u003csig:signerN>>\"\n }), \" names it BY POSITION — \", _jsx(_components.code, {\n children: \"signer1\"\n }), \" is the first entry in your \", _jsx(_components.code, {\n children: \"roles\"\n }), \" array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: \", _jsx(_components.code, {\n children: \"optional\"\n }), \", \", _jsx(_components.code, {\n children: \"validate(\u003ctype>)\"\n }), \", \", _jsx(_components.code, {\n children: \"dimension(WxH mm|pt)\"\n }), \" and \", _jsx(_components.code, {\n children: \"key(\u003cname>)\"\n }), \" — which sets the field’s \", _jsx(_components.code, {\n children: \"data_key\"\n }), \", stored lower-cased, so address it in lower case when you prefill; the name is a core key (\", _jsx(_components.code, {\n children: \"GET /api/v1/vocabulary\"\n }), \") or follows the naming grammar, \", _jsx(_components.code, {\n children: \"namespace.attribute\"\n }), \", and any other refuses the request. \", _jsx(_components.strong, {\n children: \"A QUESTION\"\n }), \" is declared on its tickbox tags: every box of it says \", _jsx(_components.code, {\n children: \"question(\u003ckey>)\"\n }), \" — the question’s \", _jsx(_components.code, {\n children: \"data_key\"\n }), \", a choice key of the core (only its own options) or one in the grammar — and \", _jsx(_components.code, {\n children: \"option(\u003cvalue>)\"\n }), \", its \", _jsx(_components.code, {\n children: \"option_value\"\n }), \"; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says \", _jsx(_components.code, {\n children: \"select(0-3)\"\n }), \", \", _jsx(_components.code, {\n children: \"select(2)\"\n }), \" or \", _jsx(_components.code, {\n children: \"select(1-*)\"\n }), \" (\", _jsx(_components.code, {\n children: \"*\"\n }), \" is every box), and named by \", _jsx(_components.code, {\n children: \"ask(\u003cwording>)\"\n }), \" on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no \", _jsx(_components.code, {\n children: \"key(...)\"\n }), \" and no \", _jsx(_components.code, {\n children: \"optional\"\n }), \". \", _jsx(_components.strong, {\n children: \"PRINTED BOXES:\"\n }), \" \", _jsx(_components.code, {\n children: \"cells(\u003cn>)\"\n }), \" on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a \", _jsx(_components.code, {\n children: \"key(...)\"\n }), \" and a subject, each with \", _jsx(_components.code, {\n children: \"cells(\u003cn>)\"\n }), \" and \", _jsx(_components.code, {\n children: \"part(\u003ck>)\"\n }), \", are ONE field filled in k order — part(1) first — returned with \", _jsx(_components.code, {\n children: \"cells\"\n }), \" and \", _jsx(_components.code, {\n children: \"continuations\"\n }), \"; a part needs both \", _jsx(_components.code, {\n children: \"cells(...)\"\n }), \" and \", _jsx(_components.code, {\n children: \"key(...)\"\n }), \", and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with \", _jsx(_components.code, {\n children: \"dimension(...)\"\n }), \". \", _jsx(_components.strong, {\n children: \"A DATE IN PRINTED BOXES\"\n }), \" is a \", _jsx(_components.code, {\n children: \"dateinput\"\n }), \" tag with \", _jsx(_components.code, {\n children: \"cells(8)\"\n }), \", or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: \", _jsx(_components.code, {\n children: \"order(DD/MM/YYYY)\"\n }), \", \", _jsx(_components.code, {\n children: \"order(MM/DD/YYYY)\"\n }), \" or \", _jsx(_components.code, {\n children: \"order(YYYY/MM/DD)\"\n }), \" on the tag or one part, or in the label, as \", _jsx(_components.code, {\n children: \"Date of birth (DD/MM/YYYY)\"\n }), \". It is a \", _jsx(_components.code, {\n children: \"date\"\n }), \" field whose value is its digits in the order the boxes print them — \", _jsx(_components.code, {\n children: \"16082026\"\n }), \" for 16 August 2026, day first; a value sent as \", _jsx(_components.code, {\n children: \"YYYY-MM-DD\"\n }), \" is accepted too and laid into the boxes in that order — and a date tag with \", _jsx(_components.code, {\n children: \"cells(...)\"\n }), \" and no order refuses the request. Detection names nothing: a detected field arrives with no \", _jsx(_components.code, {\n children: \"data_key\"\n }), \", and a detected question with none either, each box with a proposed \", _jsx(_components.code, {\n children: \"option_value\"\n }), \"; name them with \", _jsx(_components.code, {\n children: \"PATCH .../fields\"\n }), \". A segment shaped like \", _jsx(_components.code, {\n children: \"name(...)\"\n }), \" is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without \", _jsx(_components.code, {\n children: \"cells(...)\"\n }), \", a condition, a dropdown’s options or a \", _jsx(_components.code, {\n children: \"validate(regex)\"\n }), \" pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ BUT THAT SAYS NOTHING ABOUT \", _jsx(_components.strong, {\n children: \"WHICH ENDPOINT\"\n }), \", and this paragraph used to be read as though it did. \", _jsx(_components.code, {\n children: \"POST /api/v1/envelopes/one-off\"\n }), \" accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 \", _jsx(_components.code, {\n children: \"invalid_request\"\n }), \", naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print \", _jsx(_components.code, {\n children: \"\u003c\u003csig:Main Member>>\"\n }), \" on a document somebody signs.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ \", _jsx(_components.strong, {\n children: \"WHO A FIELD IS ABOUT\"\n }), \" — \", _jsx(_components.code, {\n children: \"subject(dependant_2)\"\n }), \". Declare the people the document asks about in \", _jsx(_components.code, {\n children: \"subjects\"\n }), \", then address a field to one of them. A field addressed to somebody who is not on a given envelope is \", _jsx(_components.strong, {\n children: \"hidden and not required, automatically\"\n }), \", with no condition to write:\"]\n }), \"\\n\", _jsx(CodeBlock, {\n numberOfLines: \"2\",\n language: \"text\",\n children: _jsx(_components.pre, {\n className: \"shiki shiki-themes github-light-default dark-plus\",\n style: {\n backgroundColor: \"#ffffff\",\n \"--shiki-dark-bg\": \"#0B0C0E\",\n color: \"#1f2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n language: \"text\",\n children: _jsxs(_components.code, {\n language: \"text\",\n numberOfLines: \"2\",\n children: [_jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003ctext:Employee:subject(dependant_2):Surname>>\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {})\n })]\n })\n })\n }), \"\\n\", _jsx(_components.p, {\n children: \"The argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ AND THE SUBJECT MUST BE \", _jsx(_components.code, {\n children: \"conditional\"\n }), \" FOR ANY OF IT TO MATTER. A \", _jsx(_components.code, {\n children: \"required\"\n }), \" subject is on every envelope and can never be absent, which is the safe default; \", _jsx(_components.code, {\n children: \"conditional\"\n }), \" is the one the caller or the signer decides about. A medical-aid application declaring \", _jsx(_components.code, {\n children: \"spouse\"\n }), \" and \", _jsx(_components.code, {\n children: \"dependant_1..3\"\n }), \" as conditional asks for none of them until somebody says that person exists — which is the whole point.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ \", _jsx(_components.strong, {\n children: \"WHERE THE FIELD LANDS\"\n }), \", which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is \", _jsx(_components.strong, {\n children: \"centred vertically on the tag’s line\"\n }), \" — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. \", _jsx(_components.code, {\n children: \"dimension()\"\n }), \" replaces both, and is placed the same way.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ SO WRITE THE TAG ON THE LINE \", _jsx(_components.strong, {\n children: \"ABOVE\"\n }), \" A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew:\"]\n }), \"\\n\", _jsx(CodeBlock, {\n numberOfLines: \"4\",\n language: \"text\",\n children: _jsx(_components.pre, {\n className: \"shiki shiki-themes github-light-default dark-plus\",\n style: {\n backgroundColor: \"#ffffff\",\n \"--shiki-dark-bg\": \"#0B0C0E\",\n color: \"#1f2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n language: \"text\",\n children: _jsxs(_components.code, {\n language: \"text\",\n numberOfLines: \"4\",\n children: [_jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"\u003c\u003csig:Employee>> \u003c\u003cdatesigned:Employee>>\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"______________________ ______________________\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n children: \"Employee name Date\"\n })\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {})\n })]\n })\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; \", _jsx(_components.code, {\n children: \"dimension()\"\n }), \" sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Sizes by tag: \", _jsx(_components.code, {\n children: \"sig\"\n }), \" or \", _jsx(_components.code, {\n children: \"signature\"\n }), \" 40pt tall, at least 120pt wide; \", _jsx(_components.code, {\n children: \"initial\"\n }), \" 40pt tall, at least 40pt wide; \", _jsx(_components.code, {\n children: \"dateinput\"\n }), \" 18pt tall, at least 80pt wide; \", _jsx(_components.code, {\n children: \"text\"\n }), \" 18pt tall, at least 80pt wide; \", _jsx(_components.code, {\n children: \"check\"\n }), \" or \", _jsx(_components.code, {\n children: \"checkbox\"\n }), \" 14pt tall, at least 14pt wide; \", _jsx(_components.code, {\n children: \"title\"\n }), \" 15.2pt tall, at least 131pt wide; \", _jsx(_components.code, {\n children: \"company\"\n }), \" 15.2pt tall, at least 131pt wide; \", _jsx(_components.code, {\n children: \"name\"\n }), \" 15.2pt tall, at least 131pt wide; \", _jsx(_components.code, {\n children: \"email\"\n }), \" 15.2pt tall, at least 166.6pt wide; \", _jsx(_components.code, {\n children: \"datesigned\"\n }), \" 15.2pt tall, at least 89pt wide.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ AND THE DELIMITER IS \", _jsx(_components.code, {\n children: \"\u003c\u003c >>\"\n }), \" BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every \", _jsx(_components.code, {\n children: \"{\"\n }), \"-based templating engine destroys a \", _jsx(_components.code, {\n children: \"{{ }}\"\n }), \" tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. \", _jsx(_components.code, {\n children: \"\u003c\u003c >>\"\n }), \" is untouched by all three, so your merge fields (\", _jsx(_components.code, {\n children: \"{employee.full_name}\"\n }), \", \", _jsx(_components.code, {\n children: \"{#clause}…{/}\"\n }), \") and your tags coexist with nothing to reconfigure. A \", _jsx(_components.code, {\n children: \"{{type:Role}}\"\n }), \" tag is refused by name rather than ignored, as is Dropbox Sign’s \", _jsx(_components.code, {\n children: \"[sig|req|signer1]\"\n }), \", so neither can be uploaded silently and printed on a signed document.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. \", _jsx(_components.code, {\n children: \"file\"\n }), \" takes a Word \", _jsx(_components.code, {\n children: \".docx\"\n }), \" as well as a PDF — decided by the BYTES, so there is no \", _jsx(_components.code, {\n children: \"content_type\"\n }), \" to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the \", _jsx(_components.code, {\n children: \".docx\"\n }), \". We render it, and the tags survive that render, which is the whole reason they are text.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A Word document (\", _jsx(_components.code, {\n children: \".docx\"\n }), \") is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later \", _jsx(_components.code, {\n children: \"GET\"\n }), \" refer to, and it is what a signer sees. The \", _jsx(_components.code, {\n children: \".docx\"\n }), \" you sent is retained unchanged and is not what anybody signs.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ THE OLDER \", _jsx(_components.code, {\n children: \".doc\"\n }), \" IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a \", _jsx(_components.code, {\n children: \".docx\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Detection\"\n }), \", when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-\", _jsx(_components.code, {\n children: \"cc\"\n }), \" role, for you to reassign.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. \", _jsx(_components.code, {\n children: \"fields\"\n }), \" being empty is how you tell.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"The document travels base64-encoded inside the JSON body rather than as \", _jsx(_components.code, {\n children: \"multipart/form-data\"\n }), \", so one media type and one HTTP client serve every endpoint of this API. See \", _jsx(_components.code, {\n children: \"file\"\n }), \" for what that costs and what it bounds.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A \", _jsx(_components.code, {\n children: \"vsk_test_\"\n }), \" key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Upload a PDF or a Word document and get a template with its fields already placed.","description":"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.\n\n⚠️ **FIRST, CHECK THIS IS THE RESOURCE YOU WANT.** A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in `GET /api/v1/templates` and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want `POST /api/v1/envelopes/one-off` instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: `template_id` comes back `null`. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused `template_has_no_fields` there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted.\n\n⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE.\n\n⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured.\n\n**Text tags** — write the field into the document where it goes, and it arrives placed and already assigned to the right signer:\n\n```\n\u003c\u003csig:Main Member>> a signature for the role named\n\u003c\u003ctext:Witness:Home address>> a labelled text box\n\u003c\u003ctitle:Main Member>> the signer’s job title, prefilled\n\u003c\u003cdatesigned:Main Member>> the date they signed, stamped\n\u003c\u003ctext:Witness:optional>> a box they may leave empty\n\u003c\u003ctext:Witness:validate(email)>> checked as an email address\n\u003c\u003csig:Main Member:dimension(60x15mm)>> say the size, do not pad the tag\n\u003c\u003ctext:Employee:key(employment.employee_number)>> the api name a value addresses\n\u003c\u003ccheck:Employee:question(medical_aid.plan):option(classic_smart):Classic Smart>> one box of a question; each box says it\n\u003c\u003ccheck:Employee:question(benefits.extras):option(dental):select(0-3):Dental>> on any one box: up to three ticked\n\u003c\u003ctext:Employee:ID number:cells(13)>> thirteen printed boxes, one character each\n\u003c\u003cdateinput:Employee:Date of birth (DD/MM/YYYY):cells(8)>> a date in eight printed boxes, day first\n\u003c\u003ctext:Employee:Mobile number:key(person.mobile_number):cells(3):part(1)>> one answer in two sets of boxes,\n\u003c\u003ctext:Employee:Mobile number:key(person.mobile_number):cells(7):part(2)>> filled part(1) first\n```\n\nTypes: `sig`, `signature`, `initial`, `text`, `dateinput`, `check`, `checkbox`, `title`, `company`, `name`, `email`, `datesigned`. `\u003c\u003csig:Main Member>>` names the role EXACTLY and case-sensitively; `\u003c\u003csig:signerN>>` names it BY POSITION — `signer1` is the first entry in your `roles` array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: `optional`, `validate(\u003ctype>)`, `dimension(WxH mm|pt)` and `key(\u003cname>)` — which sets the field’s `data_key`, stored lower-cased, so address it in lower case when you prefill; the name is a core key (`GET /api/v1/vocabulary`) or follows the naming grammar, `namespace.attribute`, and any other refuses the request. **A QUESTION** is declared on its tickbox tags: every box of it says `question(\u003ckey>)` — the question’s `data_key`, a choice key of the core (only its own options) or one in the grammar — and `option(\u003cvalue>)`, its `option_value`; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says `select(0-3)`, `select(2)` or `select(1-*)` (`*` is every box), and named by `ask(\u003cwording>)` on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no `key(...)` and no `optional`. **PRINTED BOXES:** `cells(\u003cn>)` on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a `key(...)` and a subject, each with `cells(\u003cn>)` and `part(\u003ck>)`, are ONE field filled in k order — part(1) first — returned with `cells` and `continuations`; a part needs both `cells(...)` and `key(...)`, and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with `dimension(...)`. **A DATE IN PRINTED BOXES** is a `dateinput` tag with `cells(8)`, or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: `order(DD/MM/YYYY)`, `order(MM/DD/YYYY)` or `order(YYYY/MM/DD)` on the tag or one part, or in the label, as `Date of birth (DD/MM/YYYY)`. It is a `date` field whose value is its digits in the order the boxes print them — `16082026` for 16 August 2026, day first; a value sent as `YYYY-MM-DD` is accepted too and laid into the boxes in that order — and a date tag with `cells(...)` and no order refuses the request. Detection names nothing: a detected field arrives with no `data_key`, and a detected question with none either, each box with a proposed `option_value`; name them with `PATCH .../fields`. A segment shaped like `name(...)` is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without `cells(...)`, a condition, a dropdown’s options or a `validate(regex)` pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards.\n\n⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows.\n\n⚠️ BUT THAT SAYS NOTHING ABOUT **WHICH ENDPOINT**, and this paragraph used to be read as though it did. `POST /api/v1/envelopes/one-off` accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient.\n\n⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 `invalid_request`, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print `\u003c\u003csig:Main Member>>` on a document somebody signs.\n\n⚠️ **WHO A FIELD IS ABOUT** — `subject(dependant_2)`. Declare the people the document asks about in `subjects`, then address a field to one of them. A field addressed to somebody who is not on a given envelope is **hidden and not required, automatically**, with no condition to write:\n\n```\n\u003c\u003ctext:Employee:subject(dependant_2):Surname>>\n```\n\nThe argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does.\n\n⚠️ AND THE SUBJECT MUST BE `conditional` FOR ANY OF IT TO MATTER. A `required` subject is on every envelope and can never be absent, which is the safe default; `conditional` is the one the caller or the signer decides about. A medical-aid application declaring `spouse` and `dependant_1..3` as conditional asks for none of them until somebody says that person exists — which is the whole point.\n\n⚠️ **WHERE THE FIELD LANDS**, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is **centred vertically on the tag’s line** — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. `dimension()` replaces both, and is placed the same way.\n\n⚠️ SO WRITE THE TAG ON THE LINE **ABOVE** A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew:\n\n```\n\u003c\u003csig:Employee>> \u003c\u003cdatesigned:Employee>>\n______________________ ______________________\nEmployee name Date\n```\n\nThe signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; `dimension()` sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it.\n\nSizes by tag: `sig` or `signature` 40pt tall, at least 120pt wide; `initial` 40pt tall, at least 40pt wide; `dateinput` 18pt tall, at least 80pt wide; `text` 18pt tall, at least 80pt wide; `check` or `checkbox` 14pt tall, at least 14pt wide; `title` 15.2pt tall, at least 131pt wide; `company` 15.2pt tall, at least 131pt wide; `name` 15.2pt tall, at least 131pt wide; `email` 15.2pt tall, at least 166.6pt wide; `datesigned` 15.2pt tall, at least 89pt wide.\n\n⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well.\n\n⚠️ AND THE DELIMITER IS `\u003c\u003c >>` BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every `{`-based templating engine destroys a `{{ }}` tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. `\u003c\u003c >>` is untouched by all three, so your merge fields (`{employee.full_name}`, `{#clause}…{/}`) and your tags coexist with nothing to reconfigure. A `{{type:Role}}` tag is refused by name rather than ignored, as is Dropbox Sign’s `[sig|req|signer1]`, so neither can be uploaded silently and printed on a signed document.\n\n✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. `file` takes a Word `.docx` as well as a PDF — decided by the BYTES, so there is no `content_type` to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the `.docx`. We render it, and the tags survive that render, which is the whole reason they are text.\n\nA Word document (`.docx`) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later `GET` refer to, and it is what a signer sees. The `.docx` you sent is retained unchanged and is not what anybody signs.\n\n⚠️ THE OLDER `.doc` IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a `.docx`.\n\n**Detection**, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-`cc` role, for you to reassign.\n\n⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. `fields` being empty is how you tell.\n\nThe document travels base64-encoded inside the JSON body rather than as `multipart/form-data`, so one media type and one HTTP client serve every endpoint of this API. See `file` for what that costs and what it bounds.\n\nA `vsk_test_` key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.","deprecated":null,"version":null,"sidebarTitle":"Create template","openapi":"/openapi.json post /api/v1/templates","href":"/api-reference/create-template","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"createTemplate","tags":["Templates"],"x-mint":{"href":"/api-reference/create-template"},"summary":"Upload a PDF or a Word document and get a template with its fields already placed.","description":"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.\n\n⚠️ **FIRST, CHECK THIS IS THE RESOURCE YOU WANT.** A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in `GET /api/v1/templates` and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want `POST /api/v1/envelopes/one-off` instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: `template_id` comes back `null`. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused `template_has_no_fields` there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted.\n\n⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE.\n\n⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured.\n\n**Text tags** — write the field into the document where it goes, and it arrives placed and already assigned to the right signer:\n\n```\n\u003c\u003csig:Main Member>> a signature for the role named\n\u003c\u003ctext:Witness:Home address>> a labelled text box\n\u003c\u003ctitle:Main Member>> the signer’s job title, prefilled\n\u003c\u003cdatesigned:Main Member>> the date they signed, stamped\n\u003c\u003ctext:Witness:optional>> a box they may leave empty\n\u003c\u003ctext:Witness:validate(email)>> checked as an email address\n\u003c\u003csig:Main Member:dimension(60x15mm)>> say the size, do not pad the tag\n\u003c\u003ctext:Employee:key(employment.employee_number)>> the api name a value addresses\n\u003c\u003ccheck:Employee:question(medical_aid.plan):option(classic_smart):Classic Smart>> one box of a question; each box says it\n\u003c\u003ccheck:Employee:question(benefits.extras):option(dental):select(0-3):Dental>> on any one box: up to three ticked\n\u003c\u003ctext:Employee:ID number:cells(13)>> thirteen printed boxes, one character each\n\u003c\u003cdateinput:Employee:Date of birth (DD/MM/YYYY):cells(8)>> a date in eight printed boxes, day first\n\u003c\u003ctext:Employee:Mobile number:key(person.mobile_number):cells(3):part(1)>> one answer in two sets of boxes,\n\u003c\u003ctext:Employee:Mobile number:key(person.mobile_number):cells(7):part(2)>> filled part(1) first\n```\n\nTypes: `sig`, `signature`, `initial`, `text`, `dateinput`, `check`, `checkbox`, `title`, `company`, `name`, `email`, `datesigned`. `\u003c\u003csig:Main Member>>` names the role EXACTLY and case-sensitively; `\u003c\u003csig:signerN>>` names it BY POSITION — `signer1` is the first entry in your `roles` array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: `optional`, `validate(\u003ctype>)`, `dimension(WxH mm|pt)` and `key(\u003cname>)` — which sets the field’s `data_key`, stored lower-cased, so address it in lower case when you prefill; the name is a core key (`GET /api/v1/vocabulary`) or follows the naming grammar, `namespace.attribute`, and any other refuses the request. **A QUESTION** is declared on its tickbox tags: every box of it says `question(\u003ckey>)` — the question’s `data_key`, a choice key of the core (only its own options) or one in the grammar — and `option(\u003cvalue>)`, its `option_value`; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says `select(0-3)`, `select(2)` or `select(1-*)` (`*` is every box), and named by `ask(\u003cwording>)` on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no `key(...)` and no `optional`. **PRINTED BOXES:** `cells(\u003cn>)` on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a `key(...)` and a subject, each with `cells(\u003cn>)` and `part(\u003ck>)`, are ONE field filled in k order — part(1) first — returned with `cells` and `continuations`; a part needs both `cells(...)` and `key(...)`, and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with `dimension(...)`. **A DATE IN PRINTED BOXES** is a `dateinput` tag with `cells(8)`, or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: `order(DD/MM/YYYY)`, `order(MM/DD/YYYY)` or `order(YYYY/MM/DD)` on the tag or one part, or in the label, as `Date of birth (DD/MM/YYYY)`. It is a `date` field whose value is its digits in the order the boxes print them — `16082026` for 16 August 2026, day first; a value sent as `YYYY-MM-DD` is accepted too and laid into the boxes in that order — and a date tag with `cells(...)` and no order refuses the request. Detection names nothing: a detected field arrives with no `data_key`, and a detected question with none either, each box with a proposed `option_value`; name them with `PATCH .../fields`. A segment shaped like `name(...)` is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without `cells(...)`, a condition, a dropdown’s options or a `validate(regex)` pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards.\n\n⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows.\n\n⚠️ BUT THAT SAYS NOTHING ABOUT **WHICH ENDPOINT**, and this paragraph used to be read as though it did. `POST /api/v1/envelopes/one-off` accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient.\n\n⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 `invalid_request`, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print `\u003c\u003csig:Main Member>>` on a document somebody signs.\n\n⚠️ **WHO A FIELD IS ABOUT** — `subject(dependant_2)`. Declare the people the document asks about in `subjects`, then address a field to one of them. A field addressed to somebody who is not on a given envelope is **hidden and not required, automatically**, with no condition to write:\n\n```\n\u003c\u003ctext:Employee:subject(dependant_2):Surname>>\n```\n\nThe argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does.\n\n⚠️ AND THE SUBJECT MUST BE `conditional` FOR ANY OF IT TO MATTER. A `required` subject is on every envelope and can never be absent, which is the safe default; `conditional` is the one the caller or the signer decides about. A medical-aid application declaring `spouse` and `dependant_1..3` as conditional asks for none of them until somebody says that person exists — which is the whole point.\n\n⚠️ **WHERE THE FIELD LANDS**, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is **centred vertically on the tag’s line** — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. `dimension()` replaces both, and is placed the same way.\n\n⚠️ SO WRITE THE TAG ON THE LINE **ABOVE** A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew:\n\n```\n\u003c\u003csig:Employee>> \u003c\u003cdatesigned:Employee>>\n______________________ ______________________\nEmployee name Date\n```\n\nThe signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; `dimension()` sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it.\n\nSizes by tag: `sig` or `signature` 40pt tall, at least 120pt wide; `initial` 40pt tall, at least 40pt wide; `dateinput` 18pt tall, at least 80pt wide; `text` 18pt tall, at least 80pt wide; `check` or `checkbox` 14pt tall, at least 14pt wide; `title` 15.2pt tall, at least 131pt wide; `company` 15.2pt tall, at least 131pt wide; `name` 15.2pt tall, at least 131pt wide; `email` 15.2pt tall, at least 166.6pt wide; `datesigned` 15.2pt tall, at least 89pt wide.\n\n⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well.\n\n⚠️ AND THE DELIMITER IS `\u003c\u003c >>` BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every `{`-based templating engine destroys a `{{ }}` tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. `\u003c\u003c >>` is untouched by all three, so your merge fields (`{employee.full_name}`, `{#clause}…{/}`) and your tags coexist with nothing to reconfigure. A `{{type:Role}}` tag is refused by name rather than ignored, as is Dropbox Sign’s `[sig|req|signer1]`, so neither can be uploaded silently and printed on a signed document.\n\n✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. `file` takes a Word `.docx` as well as a PDF — decided by the BYTES, so there is no `content_type` to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the `.docx`. We render it, and the tags survive that render, which is the whole reason they are text.\n\nA Word document (`.docx`) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later `GET` refer to, and it is what a signer sees. The `.docx` you sent is retained unchanged and is not what anybody signs.\n\n⚠️ THE OLDER `.doc` IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a `.docx`.\n\n**Detection**, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-`cc` role, for you to reassign.\n\n⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. `fields` being empty is how you tell.\n\nThe document travels base64-encoded inside the JSON body rather than as `multipart/form-data`, so one media type and one HTTP client serve every endpoint of this API. See `file` for what that costs and what it bounds.\n\nA `vsk_test_` key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.","security":["001117df-617e-47ef-97a0-72ed3aba026f"],"x-required-scope":"templates:write","parameters":["5d9d9319-85a2-43a8-9401-ed9809d9da56"],"requestBody":"ca5f576a-7c73-4a6a-aa2a-6398ccf622d6","responses":{"201":"9ab1de1a-b028-4f9b-bd3c-2d494f333d70","400":"b1bf8b53-7dce-48ad-9e51-b14bb9591551","401":"01cefd29-c005-419d-84f6-30096ad30bfd","403":"acb0ad98-1f2f-4789-b572-3d9bc3b50f31","409":"2853b720-b9d0-4232-a5de-df9312ac9448","422":"d7de6fe6-ccab-49de-94d2-e015cdeafa57","429":"05b2115e-40d9-4c65-a814-dcd26249f1f8","500":"7d0e7d97-a80f-4b22-98b8-5d8c0e3763d4","503":"f0b366a0-057d-4c96-b885-231f2e20c294"},"method":"post","type":"path","servers":["2ed67dbf-843b-4ce0-93c8-8c35248fcb3e"],"path":"/api/v1/templates","baseUrlOptions":["https://app.vumasign.com"],"title":"Upload a PDF or a Word document and get a template with its fields already placed.","codeSamples":[],"requestExampleLanguages":["bash","python","javascript","go"],"requiredOnlyExamples":true,"requestExampleType":"generated","responseExampleType":"generated","prefillPlaygroundWithExample":true,"prefillPlaygroundExamples":[{"body.file":"JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAyMTQKPj4Kc3RyZWFtCnicjY9BS0MxEITv+ytyFsTNJpndQCm8vubhwYuQP1BKLRV7qIi/331VD5UWTAgsycx8mROtOnGY9/ueHh53b5+7j8N2c69cLRur1RAR+gtJDv2J4lkaAzion36kRS5YK2PEpBVrFDTNwkiY5kkFEUnzMvRX6nfUOj3T6Ra1uhUmBRZivEqFP52p0OLM0UnNCc5Nw/8YwszGpRpuMsp3szSmUTOKmuY0XPQsM+/aHzT5nWBwhbcWwx+X1DRg5ZlVzLXZfb6k4SerTL9ZrmypXXT6ArXxXt4KZW5kc3RyZWFtCmVuZG9iagoKNiAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQovVHlwZSAvT2JqU3RtCi9OIDQKL0ZpcnN0IDIwCi9MZW5ndGggMjYzCj4+CnN0cmVhbQp4nGVQ0UoDMRB8z1fsD9hNYu4uB6XQllZBRGmFCuJDeheOlJJILyf1783G01IkL9md2ZndEcBBglJwC5UGBaLkMJ0yfPn6sIDPprM9wwfX9vCWUA4beGe4DIOPINhsxi7cpYnmGDr2MwSCyNeMdfCR4XbYx1xSUzBcmN4SAnhvj582usYwXPkmtM53gDvn5753v41rRbIiw5OlfbIjbmwfhlOTViBeVqbPn/hNxWutNK90nY7OIxesrpQstSxK/R+TnHPNi1qXI5ZWwden/cE22YLK1TnebaOJdmxQ79G2zizCOSXI0yvqYiI1aCUmaYOU5tz7ECnfnKyP6RaqijHtJPENHlNyWAplbmRzdHJlYW0KZW5kb2JqCgo3IDAgb2JqCjw8Ci9TaXplIDgKL1Jvb3QgMiAwIFIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL1hSZWYKL0xlbmd0aCAzOQovVyBbIDEgMiAyIF0KL0luZGV4IFsgMCA4IF0KPj4Kc3RyZWFtCnicFcSxEQAwCAOxt3NHnU2yMLsSrELAjClISk5HXJDe5oYPUN4DBgplbmRzdHJlYW0KZW5kb2JqCgpzdGFydHhyZWYKNjY4CiUlRU9G","body.roles.items.0":"Employee","body.filename":"employment-contract.pdf","body.name":"Employment contract","body.routing_types.items.0":"sign","body.signing_mode":"parallel","body.subjects.items.0.key":"employee","body.subjects.items.0.label":"Employee"}]},"dependencies":{"parameters":{"5d9d9319-85a2-43a8-9401-ed9809d9da56":{"name":"Idempotency-Key","in":"header","required":true,"description":"Any string that identifies this request; a UUID is the usual choice, and at most 255 characters. ⚠️ REQUIRED, because an upload is the request most likely to lose its answer — the body is the largest this API accepts and the reply comes after the document has been parsed twice. Retrying with the same key returns the same template rather than authoring a second one from the same document.\n\n⚠️ AND IT IS ANSWERED CONSERVATIVELY IN ONE CASE. If a previous request under this key stopped partway and this API cannot establish whether it created a template, you are told so with `request_in_progress` and asked to look — it will not guess, because a wrong guess is a second template. Call `GET /api/v1/templates`; if it is not there, retry with a NEW key.","schema":{"type":"string","examples":["01960000-0000-4000-8000-00000000ffff"],"description":"Any string that identifies this request; a UUID is the usual choice, and at most 255 characters. ⚠️ REQUIRED, because an upload is the request most likely to lose its answer — the body is the largest this API accepts and the reply comes after the document has been parsed twice. Retrying with the same key returns the same template rather than authoring a second one from the same document.\n\n⚠️ AND IT IS ANSWERED CONSERVATIVELY IN ONE CASE. If a previous request under this key stopped partway and this API cannot establish whether it created a template, you are told so with `request_in_progress` and asked to look — it will not guess, because a wrong guess is a second template. Call `GET /api/v1/templates`; if it is not there, retry with a NEW key.\nThe caller’s own request identifier.","isRequired":true,"uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"description":"The document, base64-encoded, and who signs it.","content":{"application/json":{"schema":{"type":"object","description":"The document and its roles.","properties":{"file":{"type":"string","examples":["JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c+PgplbmRvYmoK"],"description":"⚠️ THE WHOLE DOCUMENT, BASE64-ENCODED, AND THE EXAMPLE ABOVE IS A TRUNCATED STUB — replace it with your own document’s bytes or the request is refused as unreadable. A PDF or a Word `.docx`; the BYTES decide which, so there is no `content_type` field to get wrong, and a `.docx` is converted to PDF on our side. Standard alphabet only: no `data:` prefix, no whitespace, no line wrapping, and not the URL-safe `-`/`_` variant. Base64 is about a third larger than the file it carries, and the whole request body is bounded at 8388608 bytes — so roughly 6291456 bytes of document, whatever its format or page count.","isRequired":true,"uniqueKey":"file","typeLabel":"string"},"roles":{"type":"array","description":"Who signs it, in order, at least one and at most 20. ⚠️ THE ORDER IS LOAD-BEARING: it is a role’s position in the recipient list and its colour in the editor. When each role is asked is its step: from `role_steps` when given, otherwise one at a time in this order under `signing_mode: sequential`, or all together. Every field detected in the document is allocated to the first role that is not a `cc`, because a page cannot say which of three signers writes in a box; reassign them in the editor afterwards. Each comes back with an `id`, but nothing accepts it as input today — see `Field.id`.","items":{"type":"string","examples":["Employee"],"description":"One role’s name.","uniqueKey":"roles.items.[INDEX]","typeLabel":"string"},"isRequired":true,"uniqueKey":"roles","typeLabel":"string[]"},"filename":{"type":"string","examples":["employment-contract.pdf"],"description":"Optional. Used only to NAME the template when `name` is absent and the document has no title we can read, exactly as the upload box suggests a name from the file you dropped on it: the extension goes, underscores become spaces, and a slug such as `offer-of-employment-for-sales-staff.pdf` reads “Offer of employment for sales staff”. Other hyphens are kept. It never reaches storage — the object key is the content hash.","uniqueKey":"filename","typeLabel":"string"},"name":{"type":"string","examples":["Employment contract"],"description":"Optional. What to call the template. Absent or blank falls back to the title printed at the top of the document’s first page, when it clearly has one; then to `filename`; and then to “Untitled document”. A name you send is never replaced. ⚠️ A name that is SENT and cannot be stored is refused, while a name that is not sent is not — a template’s name is editable afterwards, and refusing an upload over one would be a wall in front of the thing this endpoint exists to make free.","uniqueKey":"name","typeLabel":"string"},"routing_types":{"type":"array","description":"Optional. One entry per role, in the same order. ⚠️ IF YOU SEND IT AT ALL IT MUST HAVE EXACTLY ONE ENTRY PER ROLE — a short list is refused rather than padded, because from an API caller a short list is far more likely to be an off-by-one than an intention. Omit it entirely and every role signs. A `cc` is never asked to fill anything in, which is why detected fields skip past one. ⚠️ IT IS SENT THE FINISHED COPY ONLY WHEN WE SEND THE COMPLETION NOTICES — `completion_delivery: vumasign`, the default for an envelope sent from the dashboard. Under `integrator`, the default for an envelope sent with an API key, nobody is sent anything at completion, a `cc` included: telling them is yours.","items":{"type":"string","enum":["sign","approve","cc"],"examples":["sign"],"description":"What this role is asked to do.","uniqueKey":"routing_types.items.[INDEX]","typeLabel":"enum\u003cstring>"},"uniqueKey":"routing_types","typeLabel":"enum\u003cstring>[]"},"role_kinds":{"type":"array","description":"Optional. One entry per role, in the same order: `party` (the default) or `witness`. A short list is refused rather than padded, as `routing_types` is. A role marked `witness` is pre-signed under a standing authorisation only under one granted for witness use. A role whose name contains “witness” or “getuie” anywhere, in any case is treated as a witness for that purpose whatever its kind.","items":{"type":"string","enum":["party","witness"],"examples":["party"],"description":"What this role is.","uniqueKey":"role_kinds.items.[INDEX]","typeLabel":"enum\u003cstring>"},"uniqueKey":"role_kinds","typeLabel":"enum\u003cstring>[]"},"role_presences":{"type":"array","description":"Optional. One entry per role, in the same order: `required` (every envelope needs somebody for it) or `optional` (an envelope may be sent without it: omit its recipient and the role is left out, with every field it holds). A short list is refused rather than padded, as `role_kinds` is. Omit it and every role is required. Ignored for a `cc` role. Read back as `Role.presence`.","items":{"type":"string","enum":["required","optional"],"description":"Whether this role can be left out.","uniqueKey":"role_presences.items.[INDEX]","typeLabel":"enum\u003cstring>"},"uniqueKey":"role_presences","typeLabel":"enum\u003cstring>[]"},"role_steps":{"type":"array","description":"Optional. One entry per role, in the same order: when that role is asked. Everyone in the lowest step that still has something to do is asked together, and the next step opens when that one is finished; roles may share a step, and steps may skip numbers. A short list is refused rather than padded, as `routing_types` is. ⚠️ NOT WITH `signing_mode`: giving both is refused as `step_with_signing_mode`. Omit it and `signing_mode` decides. Each role’s step is read back as `Role.step`. A send does not use these unless it passes them: see `step` on a recipient.","items":{"type":"integer","minimum":1,"maximum":2147483647,"examples":[1],"description":"When this role is asked.","uniqueKey":"role_steps.items.[INDEX]","typeLabel":"integer"},"uniqueKey":"role_steps","typeLabel":"integer[]"},"signing_mode":{"type":"string","enum":["parallel","sequential"],"examples":["parallel"],"description":"Optional, default `parallel` — everybody is asked at once. `sequential` asks them in the order `roles` is written, each invitation going out only when the one before it is finished. ⚠️ NOT WITH `role_steps`.","uniqueKey":"signing_mode","typeLabel":"enum\u003cstring>"},"name_fields":{"type":"boolean","description":"Optional. `true` starts a naming run as the template is created, and the 201 carries its `naming_run_id`; `template.named` says when it is ready. ⚠️ ONLY FOR A LIVE KEY THAT ALSO NAMES `templates:name`: otherwise the upload is refused (`insufficient_scope` or `test_key_cannot_edit_templates`) and nothing is created. `templates:write` alone never starts a run.","uniqueKey":"name_fields","typeLabel":"boolean"},"subjects":{"type":"array","maxItems":200,"description":"Optional. The people this document is ABOUT, as opposed to the `roles` who act on it — a spouse or a dependant on an application the main member signs — so that a `subject(...)` tag can address a field to one of them. A subject is a record of who the document describes, separate from the recipient records of who acts on it, and one person can be both. See [Subjects](https://docs.vumasign.com/concepts/subjects). Omitted means none, and every `subject(...)` tag is then refused. At most 200. Two subjects with the same `key`, or with labels that differ only in case, are refused.","items":{"type":"object","description":"One person the document asks about.","properties":{"key":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9_]+$","examples":["employee"],"description":"The subject’s machine name, and the name a `subject(...)` text tag addresses it by: lower-case `a`–`z`, `0`–`9` and `_` only, at most 100 characters — for example `spouse` or `dependant_1`. Anything else is refused with `invalid_request`, and the message names the key that would be accepted. ⚠️ IT IS NOT LOWER-CASED FOR YOU: `{\"key\": \"Spouse\"}` is refused, not stored as `spouse`, because fields and `values[].subject` refer to a key byte for byte. A tag is case-insensitive, so `subject(Spouse)` names the key `spouse`. Matches `Subject.key` and `Field.subject`.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].key","typeLabel":"string"},"label":{"type":"string","minLength":1,"examples":["Employee"],"description":"What the sender calls this person. Stored in Unicode NFC: a label sent decomposed is composed, and that composed form is what is checked, stored and returned. Not blank (whitespace alone is refused), and at most 200 UTF-16 code units once composed, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane) count as two. No `maxLength` is declared, because JSON Schema counts code points and would admit a label the server refuses.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].label","typeLabel":"string"},"presence":{"type":"string","enum":["required","conditional"],"examples":["conditional"],"description":"Optional, default `required` — the subject is on every envelope. `conditional` is what lets a subject be absent from an envelope, and a field addressed to an absent subject is hidden and not required. ⚠️ On an envelope created through the API, a `conditional` subject is ABSENT unless somebody says otherwise — `subjects` on `POST /api/v1/envelopes`, or the signer on the signing page.","uniqueKey":"subjects.items.[INDEX].presence","typeLabel":"enum\u003cstring>"},"starts_as":{"type":"string","enum":["ask","present","absent"],"examples":["ask"],"description":"Optional, default `absent` (Leave out). For a `conditional` subject, what an envelope CREATED IN THE DASHBOARD starts with: `ask` (the signer is asked at the start of signing whether this person is on the form), `present` (Include) or `absent` (Leave out). The sender can change it in the editor. Ignored for a `required` subject. ⚠️ An envelope created through the API, a draft a person later sends included, does not take it for the subjects it records when it is created: one its `subjects` does not name is left out and never asked, whatever this says.","uniqueKey":"subjects.items.[INDEX].starts_as","typeLabel":"enum\u003cstring>"}},"required":["key","label"],"uniqueKey":"subjects.items.[INDEX]","typeLabel":"object"},"uniqueKey":"subjects","typeLabel":"object[]"}},"required":["file","roles"],"uniqueKey":"","typeLabel":"object"},"examples":{"example":{"title":"example","summary":"A one-page PDF whose tag places the one field","value":{"file":"JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAyMTQKPj4Kc3RyZWFtCnicjY9BS0MxEITv+ytyFsTNJpndQCm8vubhwYuQP1BKLRV7qIi/331VD5UWTAgsycx8mROtOnGY9/ueHh53b5+7j8N2c69cLRur1RAR+gtJDv2J4lkaAzion36kRS5YK2PEpBVrFDTNwkiY5kkFEUnzMvRX6nfUOj3T6Ra1uhUmBRZivEqFP52p0OLM0UnNCc5Nw/8YwszGpRpuMsp3szSmUTOKmuY0XPQsM+/aHzT5nWBwhbcWwx+X1DRg5ZlVzLXZfb6k4SerTL9ZrmypXXT6ArXxXt4KZW5kc3RyZWFtCmVuZG9iagoKNiAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQovVHlwZSAvT2JqU3RtCi9OIDQKL0ZpcnN0IDIwCi9MZW5ndGggMjYzCj4+CnN0cmVhbQp4nGVQ0UoDMRB8z1fsD9hNYu4uB6XQllZBRGmFCuJDeheOlJJILyf1783G01IkL9md2ZndEcBBglJwC5UGBaLkMJ0yfPn6sIDPprM9wwfX9vCWUA4beGe4DIOPINhsxi7cpYnmGDr2MwSCyNeMdfCR4XbYx1xSUzBcmN4SAnhvj582usYwXPkmtM53gDvn5753v41rRbIiw5OlfbIjbmwfhlOTViBeVqbPn/hNxWutNK90nY7OIxesrpQstSxK/R+TnHPNi1qXI5ZWwden/cE22YLK1TnebaOJdmxQ79G2zizCOSXI0yvqYiI1aCUmaYOU5tz7ECnfnKyP6RaqijHtJPENHlNyWAplbmRzdHJlYW0KZW5kb2JqCgo3IDAgb2JqCjw8Ci9TaXplIDgKL1Jvb3QgMiAwIFIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL1hSZWYKL0xlbmd0aCAzOQovVyBbIDEgMiAyIF0KL0luZGV4IFsgMCA4IF0KPj4Kc3RyZWFtCnicFcSxEQAwCAOxt3NHnU2yMLsSrELAjClISk5HXJDe5oYPUN4DBgplbmRzdHJlYW0KZW5kb2JqCgpzdGFydHhyZWYKNjY4CiUlRU9G","roles":["Employee"],"subjects":[{"key":"employee","label":"Employee"}],"filename":"employment-contract.pdf","name":"Employment contract","routing_types":["sign"],"signing_mode":"parallel"}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"9ab1de1a-b028-4f9b-bd3c-2d494f333d70":{"description":"The template, in exactly the shape `GET /api/v1/templates/{templateId}` returns — same fields, same ids, same everything, because it is read back through the same function rather than assembled separately. `Idempotency-Replayed` says whether this request authored it (`false`) or is being shown an earlier one’s result (`true`); the status is 201 either way, deliberately, so a client branching on it behaves identically on a retry.\n\nIt also carries `warnings`: what the upload found worth telling you — today, personal information already printed on the document, which every envelope sent from the template would carry.","content":{"application/json":{"schema":{"type":"object","description":"The template, with every field’s id, the upload’s warnings and, with `name_fields`, its naming run.","required":["id","name","created_at","warnings","documents","pages","roles","subjects","questions","fields","coverage"],"properties":{"id":{"type":"string","format":"uuid","description":"The template’s id. A bare uuid, no prefix.","isRequired":true,"uniqueKey":"id","typeLabel":"string\u003cuuid>"},"name":{"type":"string","description":"What the sender called it.","isRequired":true,"uniqueKey":"name","typeLabel":"string"},"created_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC. Also the order this list is in — newest first.","isRequired":true,"uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"warnings":{"type":"array","description":"What the template’s upload warned about, kept with the template: on the create response and on every read, so a template somebody uploaded on the dashboard says here what its upload said. Empty when there was nothing to say, and always present. A retry of the create’s `Idempotency-Key` answers with the same list.","maxItems":10,"items":{"type":"object","description":"One warning.","properties":{"code":{"type":"string","enum":["personal-information","xfa-form"],"description":"`xfa-form`: a pure XFA form, which no field can be read from and whose pages may show only a viewer’s notice (dashboard uploads only).\n\n`personal-information`: the document already holds somebody’s details — South African ID numbers that pass their checksum, email addresses, phone numbers, or a signature baked into a signature cell as an image — and every envelope sent from this template will carry them. Usually a form that was filled in once and then uploaded as the template. Upload the blank form instead, or remove the details from it first.","isRequired":true,"uniqueKey":"warnings.items.[INDEX].code","typeLabel":"enum\u003cstring>"},"document":{"type":"integer","minimum":1,"description":"Which document of the upload it is about, counting from 1.","isRequired":true,"uniqueKey":"warnings.items.[INDEX].document","typeLabel":"integer"},"message":{"type":"string","description":"A sentence for a person, saying how many of each were found — never which: “This template appears to contain personal information: 2 ID numbers and 2 signatures. Every copy sent will include it.”","isRequired":true,"uniqueKey":"warnings.items.[INDEX].message","typeLabel":"string"}},"required":["code","document","message"],"uniqueKey":"warnings.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"warnings","typeLabel":"object[]"},"documents":{"type":"array","description":"The pack, in the order it is stacked.","items":{"type":"object","description":"One document of the pack.","properties":{"id":{"type":"string","format":"uuid","description":"The document’s id. ⚠️ ALSO THE `documentId` OF `GET /api/v1/documents/{documentId}/pages/{pageNumber}`, which is where you fetch the page itself to look at.","isRequired":true,"uniqueKey":"documents.items.[INDEX].id","typeLabel":"string\u003cuuid>"},"page_count":{"type":"integer","description":"How many pages this document contributes to the pack.","isRequired":true,"uniqueKey":"documents.items.[INDEX].page_count","typeLabel":"integer"}},"required":["id","page_count"],"uniqueKey":"documents.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"documents","typeLabel":"object[]"},"pages":{"type":"array","description":"⚠️ THE DENOMINATOR FOR EVERY `Field.rect`, and a client doing field matching cannot skip it: a rectangle of fractions is dimensionless without the page it is a fraction of. Join on `(document_id, page)`, the same pair `fields` is joined by.\n\nEvery page of every document of the pack, in the pack’s order and then by page number — the order a signer scrolls.","items":{"type":"object","description":"One page: its size in points and its rotation.","properties":{"document_id":{"type":"string","format":"uuid","description":"Which document of the pack. Matches `Document.id` and `Field.document_id`.","isRequired":true,"uniqueKey":"pages.items.[INDEX].document_id","typeLabel":"string\u003cuuid>"},"page":{"type":"integer","description":"1-indexed, WITHIN `document_id` and not within the pack. Matches `Field.page`, and is the `pageNumber` of `GET /api/v1/documents/{documentId}/pages/{pageNumber}`.","isRequired":true,"uniqueKey":"pages.items.[INDEX].page","typeLabel":"integer"},"width":{"type":"number","description":"The visible width in PDF points (1/72 inch). ⚠️ ALREADY ROTATED — this is the width of the page as it is drawn and as you will see it. A4 portrait is 595.28; the same page at `rotation: 90` reports 841.89 here.","examples":[595.28],"isRequired":true,"uniqueKey":"pages.items.[INDEX].width","typeLabel":"number"},"height":{"type":"number","description":"The visible height in PDF points. Already rotated, like `width`.","examples":[841.89],"isRequired":true,"uniqueKey":"pages.items.[INDEX].height","typeLabel":"number"},"rotation":{"type":"integer","examples":[0],"description":"One of 0, 90, 180 or 270. ⚠️ INFORMATION, NOT AN INSTRUCTION. `width`, `height` and every `Field.rect` on this page are ALREADY expressed against the rotated page. A client that rotates the geometry again because this says 90 places every field wrongly, and the result looks entirely plausible.\n\nIt is published for the two things it is genuinely needed for: telling a page that is landscape because it was rotated from one that was authored landscape, and checking that whatever produced your image honoured the rotation at all — if your image’s aspect ratio disagrees with `width`/`height`, your renderer is what is wrong.","isRequired":true,"uniqueKey":"pages.items.[INDEX].rotation","typeLabel":"integer"}},"required":["document_id","page","width","height","rotation"],"uniqueKey":"pages.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"pages","typeLabel":"object[]"},"roles":{"type":"array","description":"The signing roles, in the template’s order. When each is asked is its `step`.","items":{"type":"object","description":"One role.","properties":{"name":{"type":"string","description":"What the sender called this role. Matches `Field.role`.","isRequired":true,"uniqueKey":"roles.items.[INDEX].name","typeLabel":"string"},"routing_type":{"type":"string","description":"What this role does with the document.","enum":["sign","approve","cc"],"isRequired":true,"uniqueKey":"roles.items.[INDEX].routing_type","typeLabel":"enum\u003cstring>"},"kind":{"type":"string","description":"Whether this role is a `party` to the document or a `witness` to a signature. A witness role is pre-signed under a standing authorisation only when the authorisation was granted for witness use and your organisation has witness use enabled, and the document then says the witness was not present. A role marked a witness can be made a party again in the dashboard; that changes only envelopes made afterwards, and a role whose name contains “witness” or “getuie” anywhere, in any case is treated as a witness for pre-signing whatever its kind.","enum":["party","witness"],"isRequired":true,"uniqueKey":"roles.items.[INDEX].kind","typeLabel":"enum\u003cstring>"},"step":{"type":"integer","minimum":1,"description":"When this role is asked: everyone in the lowest step that still has something to do is asked together, and the next step opens when that one is finished. Roles that share a step are asked at the same time; a `cc` role never holds anybody up. ⚠️ A SEND WITHOUT `step` DOES NOT FOLLOW THESE: it asks everyone together when the template’s roles that are not `cc` all share one step, and otherwise one at a time in the order of its own `recipients` array. To send in this template’s steps, pass each recipient the `step` of their role.","isRequired":true,"uniqueKey":"roles.items.[INDEX].step","typeLabel":"integer"},"presign_hint":{"type":"boolean","description":"Whether the template marks this role as one your organisation normally pre-signs under a standing authorisation, so you know which role to name an authorisation for. Information only: Vumasign never applies a mandate because of it. A send applies one only when it names the authorisation. Always `false` on a witness role.","isRequired":true,"uniqueKey":"roles.items.[INDEX].presign_hint","typeLabel":"boolean"},"presence":{"type":"string","enum":["required","optional"],"description":"Whether an envelope may be sent without this role. `required`: every envelope from this template needs a recipient for it. `optional`: leave the recipient out and the role is left out of the envelope, with every field it holds; the sealed certificate says it was not on the envelope. Always `required` on a `cc` role. Set with `role_presences` when the template is created, with `role_presence` on a person decision, or in the dashboard’s Who signs.","isRequired":true,"uniqueKey":"roles.items.[INDEX].presence","typeLabel":"enum\u003cstring>"}},"required":["name","routing_type","kind","step","presign_hint","presence"],"uniqueKey":"roles.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"roles","typeLabel":"object[]"},"subjects":{"type":"array","description":"The people whose data this template collects.","items":{"type":"object","description":"One subject.","properties":{"key":{"type":"string","description":"The machine half of the address — letters, digits and underscores only, so it can never contain a dot. A subject declared today is lower-case `a`–`z`, `0`–`9` and `_`; one stored under an older, wider rule is returned exactly as stored. Matches `Field.subject`, and is what `values[].subject` and `subjects` on `POST /api/v1/envelopes` name. It never changes once created, so this is what to match your own records against.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].key","typeLabel":"string"},"label":{"type":"string","description":"What the sender called this person, and what a signer reads. The sender may rename it at any time without the `key` moving, so it is for display, not for matching.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].label","typeLabel":"string"},"presence":{"type":"string","enum":["required","conditional"],"description":"`required`: on every envelope, and `false` or `\"ask\"` for this person in `subjects` on `POST /api/v1/envelopes` is refused. `conditional`: may be left out, and the signer may be asked. Set when the template is created (`subjects[].presence`), by a person decision, or in the editor.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].presence","typeLabel":"enum\u003cstring>"},"starts_as":{"type":"string","enum":["ask","present","absent"],"description":"The sender’s choice for a `conditional` person on envelopes CREATED IN THE DASHBOARD: `ask` (the signer is asked at the start of signing), `present` (Include) or `absent` (Leave out). ⚠️ An envelope created through the API, a draft a person later sends from the dashboard included, does not take it for the people it records when it is created: a person `subjects` does not name is left out and never asked, and the signer is asked only about a person you give `\"ask\"`. Set with `subjects[].starts_as` when the template is created, with `starts_as` on a person decision, or in the editor. Not meaningful for a `required` person.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].starts_as","typeLabel":"enum\u003cstring>"}},"required":["key","label","presence","starts_as"],"uniqueKey":"subjects.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"subjects","typeLabel":"object[]"},"questions":{"type":"array","description":"The tickbox questions and how many answers each takes.","items":{"type":"object","description":"One question.","properties":{"id":{"type":"string","format":"uuid","description":"⚠️ A JOIN KEY WITHIN THIS RESPONSE, NOT AN ADDRESS. Nothing in the API accepts it as input. It exists because a question has no natural key — two questions on one form legitimately called \"Other\" are a form, not a mistake — so joining fields to questions by name would merge them.","isRequired":true,"uniqueKey":"questions.items.[INDEX].id","typeLabel":"string\u003cuuid>"},"name":{"type":"string","description":"What a signer reads above the boxes: \"Race\", \"Marital status\".","isRequired":true,"uniqueKey":"questions.items.[INDEX].name","typeLabel":"string"},"min_selected":{"type":"integer","description":"0 makes the question optional. `>= 1` is what \"required\" means here.","isRequired":true,"uniqueKey":"questions.items.[INDEX].min_selected","typeLabel":"integer"},"max_selected":{"type":"integer","description":"1 makes the question exclusive. ⚠️ It is NOT always 1: \"tick any that apply, at least one\" is `(1, n)`. Never 0 — a question that takes no answers is not a question.","isRequired":true,"uniqueKey":"questions.items.[INDEX].max_selected","typeLabel":"integer"},"subject":{"oneOf":[{"type":"string","description":"WHOSE answer this is — a `Subject.key` — or null for the signer’s own. Half of the question’s address. The question’s boxes carry the same `subject`, which is what hides them when that person is not on the envelope.","isRequired":true,"uniqueKey":"questions.items.[INDEX].subject.oneOf.0","typeLabel":"string"},{"type":"null","description":"WHOSE answer this is — a `Subject.key` — or null for the signer’s own. Half of the question’s address. The question’s boxes carry the same `subject`, which is what hides them when that person is not on the envelope.","isRequired":true,"uniqueKey":"questions.items.[INDEX].subject.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"questions.items.[INDEX].subject","typeLabel":"string | null"},"data_key":{"type":"string","description":"⚠️ THE QUESTION’S ADDRESS (template field naming PR 6). A value for this question is sent to `(subject, data_key)` and names one or more of `options[].value`: `{\"subject\": null, \"key\": \"medical_aid.plan\", \"value\": \"classic_saver\"}`, or an array of values where the question takes more than one. Never null: every question is named — by Vumasign, when nobody else has (see `name_source`). A box of a question has no address of its own (its `data_key` is null).","isRequired":true,"uniqueKey":"questions.items.[INDEX].data_key","typeLabel":"string"},"tier":{"type":"string","enum":["core","organisation","legacy"],"description":"`core` when `data_key` is a key of the core vocabulary (`GET /api/v1/vocabulary`), `organisation` when it follows the naming grammar and is not core, and `legacy` for any other spelling.","isRequired":true,"uniqueKey":"questions.items.[INDEX].tier","typeLabel":"enum\u003cstring>"},"name_source":{"type":"string","enum":["accepted","suggested","fallback"],"description":"HOW THE NAME CAME TO BE. `accepted`: a person or a caller wrote it, or kept it as it stands — Vumasign never changes it. `suggested`: Vumasign named it from the core or your organisation’s vocabulary, or from the words printed beside it, or a signature, initials or date of signing from its type and role (`signature.employee`). `fallback`: Vumasign numbered it (`form.\u003ctype>_\u003cnumber>`, or `option_\u003cnumber>` for a box), because nothing printed says what it is, or for a signature, initials or date of signing because its role’s name makes no name of its own; the number is never reused. A `suggested` name may be replaced by somebody accepting a naming run, and by Vumasign when it no longer fits its field: a field retyped, or a signature, initials or date of signing named after its role whose role changed or was renamed. Accept a name as it stands with `PATCH …/fields` naming the same value. It describes the question’s `data_key`.","isRequired":true,"uniqueKey":"questions.items.[INDEX].name_source","typeLabel":"enum\u003cstring>"},"open":{"type":"boolean","description":"`false` when `data_key` is a core `choice` key, whose option values the core vocabulary fixes for every template; `true` when this template supplies its own, listed in `options`.","isRequired":true,"uniqueKey":"questions.items.[INDEX].open","typeLabel":"boolean"},"options":{"type":"array","items":{"type":"object","description":"One answer a value may name.","properties":{"value":{"type":"string","description":"What a value names to tick these boxes: one snake_case segment, e.g. `classic_saver`.","isRequired":true,"uniqueKey":"questions.items.[INDEX].options.items.[INDEX].value","typeLabel":"string"},"label":{"oneOf":[{"type":"string","description":"The label of the box, as the sender named it — what is printed beside it.","isRequired":true,"uniqueKey":"questions.items.[INDEX].options.items.[INDEX].label.oneOf.0","typeLabel":"string"},{"type":"null","description":"The label of the box, as the sender named it — what is printed beside it.","isRequired":true,"uniqueKey":"questions.items.[INDEX].options.items.[INDEX].label.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"questions.items.[INDEX].options.items.[INDEX].label","typeLabel":"string | null"},"field_ids":{"type":"array","items":{"type":"string","format":"uuid","description":"A `Field.id`.","uniqueKey":"questions.items.[INDEX].options.items.[INDEX].field_ids.items.[INDEX]","typeLabel":"string\u003cuuid>"},"description":"The box this option ticks. An array, though an option value is unique within its question.","isRequired":true,"uniqueKey":"questions.items.[INDEX].options.items.[INDEX].field_ids","typeLabel":"string\u003cuuid>[]"},"locked":{"oneOf":[{"type":"string","enum":["ticked","cleared",null],"examples":["ticked",null],"description":"⚠️ WHERE THE TEMPLATE’S LOCKS LEAVE THIS OPTION, whatever a value says. `ticked`: the send leaves its box ticked, from an answer the template holds — name it. `cleared`: the send leaves it clear — never name it. That is an option the template locked clear, and also an open one its locks leave no answer for. `null`: open, yours to name or not. A partly locked question’s one value names every option locked `ticked`, no option locked `cleared`, and the open options you choose, within `min_selected` and `max_selected`, counted over what the sent document ticks: an option locked `ticked` counts whether the value names it or not. Left out, it is added when the bounds still hold with it, and refused (`value_option_locked`) when they do not; naming an option locked `cleared` is refused. An entry that sets `locked` replaces the template’s locks on every box of the question, so neither applies to it. A box whose option is not `null` is a `Field` with `fixed` true. A question’s answer is which boxes are ticked, so a question its locks settle whole is published as its answer. The same rule as the field map’s `filled_by` and `fixed_tick` ([Seeing a template](https://docs.vumasign.com/concepts/seeing-a-template)), so the two never disagree. Part of the body, so the template’s `ETag` changes when this does; a lock with no answer of its own is not published here and does not change it.","isRequired":true,"uniqueKey":"questions.items.[INDEX].options.items.[INDEX].locked.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["ticked","cleared",null],"examples":["ticked",null],"description":"⚠️ WHERE THE TEMPLATE’S LOCKS LEAVE THIS OPTION, whatever a value says. `ticked`: the send leaves its box ticked, from an answer the template holds — name it. `cleared`: the send leaves it clear — never name it. That is an option the template locked clear, and also an open one its locks leave no answer for. `null`: open, yours to name or not. A partly locked question’s one value names every option locked `ticked`, no option locked `cleared`, and the open options you choose, within `min_selected` and `max_selected`, counted over what the sent document ticks: an option locked `ticked` counts whether the value names it or not. Left out, it is added when the bounds still hold with it, and refused (`value_option_locked`) when they do not; naming an option locked `cleared` is refused. An entry that sets `locked` replaces the template’s locks on every box of the question, so neither applies to it. A box whose option is not `null` is a `Field` with `fixed` true. A question’s answer is which boxes are ticked, so a question its locks settle whole is published as its answer. The same rule as the field map’s `filled_by` and `fixed_tick` ([Seeing a template](https://docs.vumasign.com/concepts/seeing-a-template)), so the two never disagree. Part of the body, so the template’s `ETag` changes when this does; a lock with no answer of its own is not published here and does not change it.","isRequired":true,"uniqueKey":"questions.items.[INDEX].options.items.[INDEX].locked.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"questions.items.[INDEX].options.items.[INDEX].locked","typeLabel":"enum\u003cstring> | null"}},"required":["value","label","field_ids","locked"],"uniqueKey":"questions.items.[INDEX].options.items.[INDEX]","typeLabel":"object"},"description":"WHAT A VALUE FOR THIS QUESTION MAY NAME, by option value. A box with no option value is in none of them, and no value can tick it. For an open question this is the only place this template’s option values are listed.","isRequired":true,"uniqueKey":"questions.items.[INDEX].options","typeLabel":"object[]"}},"required":["id","name","min_selected","max_selected","subject","data_key","tier","name_source","open","options"],"uniqueKey":"questions.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"questions","typeLabel":"object[]"},"fields":{"type":"array","description":"⚠️ A FLAT LIST, NOT A MAP KEYED BY ADDRESS. Several fields sharing one `(subject, data_key)` pair is NORMAL — real forms ask for an ID number on the application and again on the declaration, and initials in the footer of all nine pages. A value supplied for an address means it for every box that asks.","items":{"type":"object","description":"One field placement.","properties":{"id":{"type":"string","format":"uuid","description":"⚠️ THE HANDLE FOR EXACTLY ONE FIELD, AND NOT A SECOND ADDRESS. `subject` + `data_key` is the address and it names a SET of fields on purpose — one `main_member.id_number` is meant to fill the box on the application, the box on the declaration and the initials in nine footers. Write values to the ADDRESS by default. Use this id when you need to name ONE of several boxes the address cannot tell apart, or to keep a durable reference to a particular box. The two can never name the same target, so there is no precedence to learn: an id is one field, an address is a set. ⚠️ NOTHING ACCEPTS IT AS INPUT TODAY — `values` on `POST /api/v1/envelopes` is addressed by `subject` and `key`, and there is no id-keyed form. ⚠️ IT IS STABLE across ordinary editing — the sender may move, retype, relabel and readdress a box, or delete its neighbours, and this value does not change — so it is safe to store. ⚠️ IT NAMES A TEMPLATE FIELD: sending a template COPIES its fields onto the envelope, and those copies are their own rows with their own ids.","isRequired":true,"uniqueKey":"fields.items.[INDEX].id","typeLabel":"string\u003cuuid>"},"type":{"type":"string","description":"What kind of box this is. This vocabulary is `FIELD_TYPES` verbatim and the database CHECK constraint’s, not a translation of either.","enum":["signature","initial","text","date","checkbox","dropdown","attachment","date_signed","signer_name","signer_email","signer_title","signer_company"],"isRequired":true,"uniqueKey":"fields.items.[INDEX].type","typeLabel":"enum\u003cstring>"},"label":{"oneOf":[{"type":"string","description":"What is printed beside the box. Null for a box the sender never named.","isRequired":true,"uniqueKey":"fields.items.[INDEX].label.oneOf.0","typeLabel":"string"},{"type":"null","description":"What is printed beside the box. Null for a box the sender never named.","isRequired":true,"uniqueKey":"fields.items.[INDEX].label.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].label","typeLabel":"string | null"},"required":{"type":"boolean","description":"⚠️ ALWAYS FALSE ON A GROUPED OPTION — requiredness lives on the question, so read `min_selected` there instead. This flag is the answer for independent boxes only.","isRequired":true,"uniqueKey":"fields.items.[INDEX].required","typeLabel":"boolean"},"fixed":{"type":"boolean","examples":[false],"description":"⚠️ WHETHER THE TEMPLATE FIXES THIS BOX’S ANSWER. `true`: the template holds the answer at this box’s address, so send no value for it. On a field outside a question, true when any box at its `(subject, data_key)` holds one: a value sent there without `locked` is replaced by the template’s answer in the box holding it and lands in the others, so the boxes would disagree. On a box of a question, true when the box holds an answer of its own or its option’s `locked` (`Question.options`) is not null. Exactly the boxes whose field map row says `filled_by` is `fixed`. A field’s locked text is never published. ⚠️ A lock with no answer of its own is not fixed: its value arrives with the envelope, and a send without it is refused `locked_answer_missing`. Part of the body, so the template’s `ETag` changes when this does.","isRequired":true,"uniqueKey":"fields.items.[INDEX].fixed","typeLabel":"boolean"},"role":{"type":"string","description":"WHO fills this in. Matches `Role.name`.","isRequired":true,"uniqueKey":"fields.items.[INDEX].role","typeLabel":"string"},"document_id":{"type":"string","format":"uuid","description":"Which document of the pack this box is on. Matches `Document.id`.","isRequired":true,"uniqueKey":"fields.items.[INDEX].document_id","typeLabel":"string\u003cuuid>"},"page":{"type":"integer","description":"1-indexed, WITHIN `document_id` and not within the pack.","isRequired":true,"uniqueKey":"fields.items.[INDEX].page","typeLabel":"integer"},"subject":{"oneOf":[{"type":"string","description":"WHOSE datum this is — a `Subject.key` — or null for the signer’s own. Half of the address.","isRequired":true,"uniqueKey":"fields.items.[INDEX].subject.oneOf.0","typeLabel":"string"},{"type":"null","description":"WHOSE datum this is — a `Subject.key` — or null for the signer’s own. Half of the address.","isRequired":true,"uniqueKey":"fields.items.[INDEX].subject.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].subject","typeLabel":"string | null"},"data_key":{"oneOf":[{"type":"string","description":"⚠️ THE OTHER HALF OF THE ADDRESS. NEVER NULL ON A FIELD OUTSIDE A QUESTION, whatever its type: Vumasign names every field, and when nothing printed says what a field is it numbers it (`form.text_013`; see `name_source`). Match your data to these names; renaming is optional. A signature’s or a signing date’s name is for reading it back — a value sent to it is refused `value_not_writable`. ⚠️ It may contain a dot and any Unicode letter — South Africa has eleven official languages and a Sesotho label is not a malformed address — which is why this is never composed with `subject` into one dotted string. ⚠️ ALWAYS NULL ON A BOX OF A QUESTION: its address is the question’s (`Question.data_key`), and `option_value` says which answer it is.","isRequired":true,"uniqueKey":"fields.items.[INDEX].data_key.oneOf.0","typeLabel":"string"},{"type":"null","description":"⚠️ THE OTHER HALF OF THE ADDRESS. NEVER NULL ON A FIELD OUTSIDE A QUESTION, whatever its type: Vumasign names every field, and when nothing printed says what a field is it numbers it (`form.text_013`; see `name_source`). Match your data to these names; renaming is optional. A signature’s or a signing date’s name is for reading it back — a value sent to it is refused `value_not_writable`. ⚠️ It may contain a dot and any Unicode letter — South Africa has eleven official languages and a Sesotho label is not a malformed address — which is why this is never composed with `subject` into one dotted string. ⚠️ ALWAYS NULL ON A BOX OF A QUESTION: its address is the question’s (`Question.data_key`), and `option_value` says which answer it is.","isRequired":true,"uniqueKey":"fields.items.[INDEX].data_key.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].data_key","typeLabel":"string | null"},"tier":{"oneOf":[{"type":"string","enum":["core","organisation","legacy",null],"description":"`core` when `data_key` is a key of the core vocabulary, `organisation` when it follows the naming grammar and is not core, `legacy` for any other spelling, and null on a box of a question.","isRequired":true,"uniqueKey":"fields.items.[INDEX].tier.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["core","organisation","legacy",null],"description":"`core` when `data_key` is a key of the core vocabulary, `organisation` when it follows the naming grammar and is not core, `legacy` for any other spelling, and null on a box of a question.","isRequired":true,"uniqueKey":"fields.items.[INDEX].tier.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].tier","typeLabel":"enum\u003cstring> | null"},"name_source":{"type":"string","enum":["accepted","suggested","fallback"],"description":"How this field’s name came to be — its `data_key`, or on a box of a question its `option_value`. The values are `Question.name_source`’s.","isRequired":true,"uniqueKey":"fields.items.[INDEX].name_source","typeLabel":"enum\u003cstring>"},"question_id":{"oneOf":[{"type":"string","description":"The `Question.id` this box is an option of, or null for an independent one.","isRequired":true,"uniqueKey":"fields.items.[INDEX].question_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"The `Question.id` this box is an option of, or null for an independent one.","isRequired":true,"uniqueKey":"fields.items.[INDEX].question_id.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].question_id","typeLabel":"string | null"},"option_value":{"oneOf":[{"type":"string","description":"For a box of a question, the option it stands for: a value for the question naming it ticks this box. Null on any other field. Never null on a box: Vumasign names every box, from the words printed beside it or, failing those, as `option_1`, `option_2` and so on within its question.","isRequired":true,"uniqueKey":"fields.items.[INDEX].option_value.oneOf.0","typeLabel":"string"},{"type":"null","description":"For a box of a question, the option it stands for: a value for the question naming it ticks this box. Null on any other field. Never null on a box: Vumasign names every box, from the words printed beside it or, failing those, as `option_1`, `option_2` and so on within its question.","isRequired":true,"uniqueKey":"fields.items.[INDEX].option_value.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].option_value","typeLabel":"string | null"},"options":{"oneOf":[{"type":"array","items":{"type":"string","description":"One option, exactly as a signer sees it and exactly as it is sealed.","uniqueKey":"fields.items.[INDEX].options.oneOf.0.items.[INDEX]","typeLabel":"string"},"description":"WHAT A `dropdown` OFFERS, in the order the signer reads them. Null on every other type. An option is ONE STRING — what is shown, what you write back, and what is sealed onto the document; there is no separate value and label, so the string on the certificate cannot disagree with the string in the database. ⚠️ A value you write to a dropdown MUST be one of these exactly: anything else is refused. ⚠️ Null on a dropdown created before options existed — such a field cannot be answered at all, by you or by a signer, and has to be given a list in the editor.","isRequired":true,"uniqueKey":"fields.items.[INDEX].options.oneOf.0","typeLabel":"string[]"},{"type":"null","items":{"type":"string","description":"One option, exactly as a signer sees it and exactly as it is sealed."},"description":"WHAT A `dropdown` OFFERS, in the order the signer reads them. Null on every other type. An option is ONE STRING — what is shown, what you write back, and what is sealed onto the document; there is no separate value and label, so the string on the certificate cannot disagree with the string in the database. ⚠️ A value you write to a dropdown MUST be one of these exactly: anything else is refused. ⚠️ Null on a dropdown created before options existed — such a field cannot be answered at all, by you or by a signer, and has to be given a list in the editor.","isRequired":true,"uniqueKey":"fields.items.[INDEX].options.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].options","typeLabel":"string[] | null"},"rect":{"type":"object","description":"⚠️ WHERE THE BOX IS ON THE PAGE, AND THE REASON THIS ENDPOINT IS USABLE BY SOMETHING THAT CAN SEE. `label` says what is printed beside the box and `data_key` says what may be written into it; on a real form neither is enough. A nine-page medical application carries 284 fields named `checklist.17` and `fullwidth.42`, with OCR-derived labels, where \"ID or passport number\" appears four times on one page and only the POSITION says which dependant it belongs to.\n\nFetch the page it is on from `GET /api/v1/documents/{document_id}/pages/{page}`, render it, and these four fractions land on the box. ⚠️ Read `Rect` before using them: origin top-left, Y downward, measured against the page AFTER rotation.","properties":{"x":{"type":"number","description":"The LEFT edge, as a fraction of the visible page width. 0 is the left edge of the page, 1 the right.","examples":[0.1024],"isRequired":true,"uniqueKey":"fields.items.[INDEX].rect.x","typeLabel":"number"},"y":{"type":"number","description":"⚠️ The TOP edge, as a fraction of the visible page height, measured DOWNWARD. 0 is the top of the page, 1 the bottom.","examples":[0.2153],"isRequired":true,"uniqueKey":"fields.items.[INDEX].rect.y","typeLabel":"number"},"w":{"type":"number","description":"Width, as a fraction of the visible page width. Always positive.","examples":[0.3201],"isRequired":true,"uniqueKey":"fields.items.[INDEX].rect.w","typeLabel":"number"},"h":{"type":"number","description":"Height, as a fraction of the visible page height. Always positive.","examples":[0.0261],"isRequired":true,"uniqueKey":"fields.items.[INDEX].rect.h","typeLabel":"number"}},"required":["x","y","w","h"],"isRequired":true,"uniqueKey":"fields.items.[INDEX].rect","typeLabel":"object"},"context":{"oneOf":[{"type":"object","description":"The printed text around the box: see `FieldContext`. ⚠️ NULL MEANS THE DOCUMENT’S TEXT HAS NOT BEEN STORED — a document uploaded before this existed and not yet backfilled, or one carrying more text than is stored — or that the template has more fields and printed text than one read describes. It never means the page is blank. Fetch the page with `documents:read` to read it yourself.","required":["label","row","column","option","section","nearby","widget_name","tooltip","continues"],"properties":{"label":{"oneOf":[{"type":"string","description":"The printed label for this box: on its row to the left, else just above. ⚠️ Null on a box with another box between it and its row’s label — the cents half of an amount, the second column of a table — where `continues` or `row` names it instead.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.label.oneOf.0","typeLabel":"string"},{"type":"null","description":"The printed label for this box: on its row to the left, else just above. ⚠️ Null on a box with another box between it and its row’s label — the cents half of an amount, the second column of a table — where `continues` or `row` names it instead.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.label.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.label","typeLabel":"string | null"},"row":{"oneOf":[{"type":"string","description":"The printed heading of the box’s row: the left-most text on its row, even with other boxes in between. In a table it names the attribute (\"ID number\") for every column.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.row.oneOf.0","typeLabel":"string"},{"type":"null","description":"The printed heading of the box’s row: the left-most text on its row, even with other boxes in between. In a table it names the attribute (\"ID number\") for every column.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.row.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.row","typeLabel":"string | null"},"column":{"oneOf":[{"type":"string","description":"The printed heading of the column the box sits in: the nearest text above it (within 400 pt) that overlaps it, past the text printed on rows that hold boxes. \"Dependant 2\".","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.column.oneOf.0","typeLabel":"string"},{"type":"null","description":"The printed heading of the column the box sits in: the nearest text above it (within 400 pt) that overlaps it, past the text printed on rows that hold boxes. \"Dependant 2\".","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.column.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.column","typeLabel":"string | null"},"option":{"oneOf":[{"type":"string","description":"For a checkbox, the printed option beside it (\"Male\"). Null on every other type.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.option.oneOf.0","typeLabel":"string"},{"type":"null","description":"For a checkbox, the printed option beside it (\"Male\"). Null on every other type.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.option.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.option","typeLabel":"string | null"},"section":{"oneOf":[{"type":"string","description":"The nearest printed section heading above the box, or carried from an earlier page. ⚠️ A heuristic, and null rather than a guess: when two headings tie, or a page has too many heading-like lines to trust.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.section.oneOf.0","typeLabel":"string"},{"type":"null","description":"The nearest printed section heading above the box, or carried from an earlier page. ⚠️ A heuristic, and null rather than a guess: when two headings tie, or a page has too many heading-like lines to trust.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.section.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.section","typeLabel":"string | null"},"nearby":{"type":"array","items":{"type":"string","description":"One printed run, tidied.","uniqueKey":"fields.items.[INDEX].context.oneOf.0.nearby.items.[INDEX]","typeLabel":"string"},"description":"Up to 8 printed runs within 72 pt of the box, nearest first, each once.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.nearby","typeLabel":"string[]"},"widget_name":{"oneOf":[{"type":"string","description":"An AcroForm widget’s own field name, for the widget under this box, when it is not a machine-generated one such as `Text12`. Evidence, never an address.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.widget_name.oneOf.0","typeLabel":"string"},{"type":"null","description":"An AcroForm widget’s own field name, for the widget under this box, when it is not a machine-generated one such as `Text12`. Evidence, never an address.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.widget_name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.widget_name","typeLabel":"string | null"},"tooltip":{"oneOf":[{"type":"string","description":"That widget’s tooltip (`/TU`), if it has one.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.tooltip.oneOf.0","typeLabel":"string"},{"type":"null","description":"That widget’s tooltip (`/TU`), if it has one.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.tooltip.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.tooltip","typeLabel":"string | null"},"continues":{"oneOf":[{"type":"object","description":"The box this one continues on its row: the nearest box to its left, with one separator glyph printed between them, or nothing between and the two one size and nearly touching, and that box’s printed label. A cents box after its rands, a number after its dialling code. Null for every other box: always when `label` is not null, and for a box under a column heading of its own, such as the second column of a grid.","properties":{"label":{"type":"string","description":"The printed label of the box this one continues.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.0.label","typeLabel":"string"},"separator":{"oneOf":[{"type":"string","description":"The one glyph printed between the two boxes (\".\" between rands and cents), or null when nothing is.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.0.separator.oneOf.0","typeLabel":"string"},{"type":"null","description":"The one glyph printed between the two boxes (\".\" between rands and cents), or null when nothing is.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.0.separator.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.0.separator","typeLabel":"string | null"},"currency":{"oneOf":[{"type":"string","description":"The currency mark printed inside or just before the first box, or named in its label as \"(R)\", \"(ZAR)\" or \"in rand\", or null. A \".\" or \",\" separator is an amount’s cents only with a currency.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.0.currency.oneOf.0","typeLabel":"string"},{"type":"null","description":"The currency mark printed inside or just before the first box, or named in its label as \"(R)\", \"(ZAR)\" or \"in rand\", or null. A \".\" or \",\" separator is an amount’s cents only with a currency.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.0.currency.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.0.currency","typeLabel":"string | null"}},"required":["label","separator","currency"],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.0","typeLabel":"object"},{"type":"null","description":"The box this one continues on its row: the nearest box to its left, with one separator glyph printed between them, or nothing between and the two one size and nearly touching, and that box’s printed label. A cents box after its rands, a number after its dialling code. Null for every other box: always when `label` is not null, and for a box under a column heading of its own, such as the second column of a grid.","properties":{"label":{"type":"string","description":"The printed label of the box this one continues."},"separator":{"oneOf":[{"type":"string","description":"The one glyph printed between the two boxes (\".\" between rands and cents), or null when nothing is."},{"type":"null","description":"The one glyph printed between the two boxes (\".\" between rands and cents), or null when nothing is."}]},"currency":{"oneOf":[{"type":"string","description":"The currency mark printed inside or just before the first box, or named in its label as \"(R)\", \"(ZAR)\" or \"in rand\", or null. A \".\" or \",\" separator is an amount’s cents only with a currency."},{"type":"null","description":"The currency mark printed inside or just before the first box, or named in its label as \"(R)\", \"(ZAR)\" or \"in rand\", or null. A \".\" or \",\" separator is an amount’s cents only with a currency."}]}},"required":["label","separator","currency"],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0.continues","typeLabel":"object | null"}},"isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.0","typeLabel":"object"},{"type":"null","description":"The printed text around the box: see `FieldContext`. ⚠️ NULL MEANS THE DOCUMENT’S TEXT HAS NOT BEEN STORED — a document uploaded before this existed and not yet backfilled, or one carrying more text than is stored — or that the template has more fields and printed text than one read describes. It never means the page is blank. Fetch the page with `documents:read` to read it yourself.","isRequired":true,"uniqueKey":"fields.items.[INDEX].context.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].context","typeLabel":"object | null"},"cells":{"oneOf":[{"type":"integer","minimum":1,"description":"On a field split across several sets of printed boxes, how many characters its FIRST set holds — the boxes at `rect`. Null for a field drawn in one place. See `continuations`.","examples":[3],"isRequired":true,"uniqueKey":"fields.items.[INDEX].cells.oneOf.0","typeLabel":"integer"},{"type":"null","minimum":1,"description":"On a field split across several sets of printed boxes, how many characters its FIRST set holds — the boxes at `rect`. Null for a field drawn in one place. See `continuations`.","examples":[3],"isRequired":true,"uniqueKey":"fields.items.[INDEX].cells.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].cells","typeLabel":"integer | null"},"continuations":{"oneOf":[{"type":"array","items":{"type":"object","description":"One later set of boxes, in fill order.","properties":{"rect":{"type":"object","description":"Where these boxes are, exactly as `Field.rect` is measured: fractions of the visible page, origin top-left, Y downward. Always on the field’s own page.","properties":{"x":{"type":"number","description":"The LEFT edge, as a fraction of the visible page width. 0 is the left edge of the page, 1 the right.","examples":[0.1024],"isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations.oneOf.0.items.[INDEX].rect.x","typeLabel":"number"},"y":{"type":"number","description":"⚠️ The TOP edge, as a fraction of the visible page height, measured DOWNWARD. 0 is the top of the page, 1 the bottom.","examples":[0.2153],"isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations.oneOf.0.items.[INDEX].rect.y","typeLabel":"number"},"w":{"type":"number","description":"Width, as a fraction of the visible page width. Always positive.","examples":[0.3201],"isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations.oneOf.0.items.[INDEX].rect.w","typeLabel":"number"},"h":{"type":"number","description":"Height, as a fraction of the visible page height. Always positive.","examples":[0.0261],"isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations.oneOf.0.items.[INDEX].rect.h","typeLabel":"number"}},"required":["x","y","w","h"],"isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations.oneOf.0.items.[INDEX].rect","typeLabel":"object"},"cells":{"type":"integer","minimum":1,"description":"How many characters these boxes hold, one in each.","examples":[7],"isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations.oneOf.0.items.[INDEX].cells","typeLabel":"integer"}},"required":["rect","cells"],"uniqueKey":"fields.items.[INDEX].continuations.oneOf.0.items.[INDEX]","typeLabel":"object"},"description":"⚠️ ONE VALUE DRAWN ACROSS SEVERAL SETS OF PRINTED BOXES, such as a telephone number printed as a 3-box dialling code and a 7-box number. `rect` is the first set; these are the later ones, in the order the value fills them. Write the field ONE value at its one address — `0828014085`, not two values — and it is drawn from the left: `cells` characters in the first set, then each continuation’s `cells` in turn. Send only the characters the boxes print: spaces and dashes are removed for you only on a field checked as a telephone, ID, tax or VAT number, and this response does not say which fields those are. A value with more characters than all the boxes together is refused `cannot_be_drawn`. Null for a field drawn in one place. Draw these too when you outline the field on a page. A field whose `amount` is set is not filled from the left: see `amount`.","isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations.oneOf.0","typeLabel":"object[]"},{"type":"null","items":{"type":"object","description":"One later set of boxes, in fill order.","properties":{"rect":{"type":"object","description":"Where these boxes are, exactly as `Field.rect` is measured: fractions of the visible page, origin top-left, Y downward. Always on the field’s own page.","properties":{"x":{"type":"number","description":"The LEFT edge, as a fraction of the visible page width. 0 is the left edge of the page, 1 the right.","examples":[0.1024]},"y":{"type":"number","description":"⚠️ The TOP edge, as a fraction of the visible page height, measured DOWNWARD. 0 is the top of the page, 1 the bottom.","examples":[0.2153]},"w":{"type":"number","description":"Width, as a fraction of the visible page width. Always positive.","examples":[0.3201]},"h":{"type":"number","description":"Height, as a fraction of the visible page height. Always positive.","examples":[0.0261]}},"required":["x","y","w","h"]},"cells":{"type":"integer","minimum":1,"description":"How many characters these boxes hold, one in each.","examples":[7]}},"required":["rect","cells"]},"description":"⚠️ ONE VALUE DRAWN ACROSS SEVERAL SETS OF PRINTED BOXES, such as a telephone number printed as a 3-box dialling code and a 7-box number. `rect` is the first set; these are the later ones, in the order the value fills them. Write the field ONE value at its one address — `0828014085`, not two values — and it is drawn from the left: `cells` characters in the first set, then each continuation’s `cells` in turn. Send only the characters the boxes print: spaces and dashes are removed for you only on a field checked as a telephone, ID, tax or VAT number, and this response does not say which fields those are. A value with more characters than all the boxes together is refused `cannot_be_drawn`. Null for a field drawn in one place. Draw these too when you outline the field on a page. A field whose `amount` is set is not filled from the left: see `amount`.","isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].continuations","typeLabel":"object[] | null"},"amount":{"oneOf":[{"type":"object","required":["fraction_digits"],"properties":{"fraction_digits":{"type":"integer","minimum":1,"maximum":2,"description":"How many digits the cents box holds: the number of digits after the decimal point.","examples":[2],"isRequired":true,"uniqueKey":"fields.items.[INDEX].amount.oneOf.0.fraction_digits","typeLabel":"integer"}},"description":"⚠️ ONE AMOUNT IN RANDS AND CENTS, such as a form’s `R [ ] . [ ]`, or null. The first set of boxes (`rect`, `cells`) holds the rands and the one continuation the cents. Write the field ONE value: a decimal such as `12345.67`, or the way a person writes one, `12 345,67` or `R 12 345,67`; a whole amount such as `12345` is stored as `12345.00`. It is read back, and sealed, as a decimal with exactly `fraction_digits` digits after the point, the rands drawn right-aligned so they end at the printed separator. A value that is not an amount, or whose rands or cents do not fit their boxes, is refused `cannot_be_drawn`, and so is one that could be read as two amounts: one point or comma followed by exactly three digits, such as `12.500`. Group thousands with spaces, or with the other mark: `12 500,00`, `12,500.00`. Null for every other field.","examples":[{"fraction_digits":2}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].amount.oneOf.0","typeLabel":"object"},{"type":"null","required":["fraction_digits"],"properties":{"fraction_digits":{"type":"integer","minimum":1,"maximum":2,"description":"How many digits the cents box holds: the number of digits after the decimal point.","examples":[2]}},"description":"⚠️ ONE AMOUNT IN RANDS AND CENTS, such as a form’s `R [ ] . [ ]`, or null. The first set of boxes (`rect`, `cells`) holds the rands and the one continuation the cents. Write the field ONE value: a decimal such as `12345.67`, or the way a person writes one, `12 345,67` or `R 12 345,67`; a whole amount such as `12345` is stored as `12345.00`. It is read back, and sealed, as a decimal with exactly `fraction_digits` digits after the point, the rands drawn right-aligned so they end at the printed separator. A value that is not an amount, or whose rands or cents do not fit their boxes, is refused `cannot_be_drawn`, and so is one that could be read as two amounts: one point or comma followed by exactly three digits, such as `12.500`. Group thousands with spaces, or with the other mark: `12 500,00`, `12,500.00`. Null for every other field.","examples":[{"fraction_digits":2}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].amount.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"fields.items.[INDEX].amount","typeLabel":"object | null"}},"required":["id","type","label","required","fixed","role","document_id","page","subject","data_key","tier","name_source","question_id","option_value","options","rect","context","cells","continuations","amount"],"uniqueKey":"fields.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"fields","typeLabel":"object[]"},"coverage":{"type":"object","description":"How much of the template your integration can address, counted by the same code as the editor’s coverage line, so the two always agree. Part of the body, so the template’s `ETag` changes when it does.","properties":{"prefillable":{"type":"integer","minimum":0,"description":"Fields outside a question you may write a value into: every type except those the signer performs or the system stamps.","isRequired":true,"uniqueKey":"coverage.prefillable","typeLabel":"integer"},"core":{"type":"integer","minimum":0,"description":"Those whose `data_key` is a key of the core vocabulary.","isRequired":true,"uniqueKey":"coverage.core","typeLabel":"integer"},"organisation":{"type":"integer","minimum":0,"description":"Those whose `data_key` follows the naming grammar (`namespace.attribute` or `namespace.entity.attribute`, snake_case) and is not core.","isRequired":true,"uniqueKey":"coverage.organisation","typeLabel":"integer"},"legacy":{"type":"integer","minimum":0,"description":"Those with any other `data_key`, such as one derived from a label (`date_birth`). It still works as an address, and is a name to replace.","isRequired":true,"uniqueKey":"coverage.legacy","typeLabel":"integer"},"unnamed":{"type":"integer","minimum":0,"description":"Those with no `data_key`. Always 0: Vumasign names every field.","isRequired":true,"uniqueKey":"coverage.unnamed","typeLabel":"integer"},"questions":{"type":"integer","minimum":0,"description":"Tickbox questions, each one address.","isRequired":true,"uniqueKey":"coverage.questions","typeLabel":"integer"},"unnamed_groups":{"type":"integer","minimum":0,"description":"Questions with no `data_key`. Always 0: Vumasign names every question.","isRequired":true,"uniqueKey":"coverage.unnamed_groups","typeLabel":"integer"},"unnamed_options":{"type":"integer","minimum":0,"description":"Boxes of a question with no `option_value`. Always 0: Vumasign names every box.","isRequired":true,"uniqueKey":"coverage.unnamed_options","typeLabel":"integer"},"collisions":{"type":"integer","minimum":0,"description":"Fields and questions sharing an address they cannot share, such as two lone tickboxes at one `(subject, data_key)`, which any value would tick together. Two fields of the same other type at one address are one datum printed twice, and are not counted.","isRequired":true,"uniqueKey":"coverage.collisions","typeLabel":"integer"},"fallback":{"type":"integer","minimum":0,"description":"Prefillable fields outside a question, and questions, whose name is a fallback Vumasign numbered because nothing printed says what they are (`name_source: fallback`). They work as they are; they are counted so that somebody can give them a better name.","isRequired":true,"uniqueKey":"coverage.fallback","typeLabel":"integer"},"fallback_options":{"type":"integer","minimum":0,"description":"Boxes of a question whose `option_value` is a fallback (`option_2`).","isRequired":true,"uniqueKey":"coverage.fallback_options","typeLabel":"integer"}},"required":["prefillable","core","organisation","legacy","unnamed","questions","unnamed_groups","unnamed_options","collisions","fallback","fallback_options"],"isRequired":true,"uniqueKey":"coverage","typeLabel":"object"},"naming_run_id":{"type":"string","format":"uuid","description":"Present only when `name_fields` was `true`: the run naming the template. Read it, or wait for `template.named`.","uniqueKey":"naming_run_id","typeLabel":"string\u003cuuid>"}},"uniqueKey":"","typeLabel":"object"},"examples":{"example":{"title":"example","summary":"The template, with one detected field and nothing to warn about","value":{"warnings":[],"id":"01960000-0000-4000-8000-0000000007e1","name":"Employment contract","created_at":"2026-09-01T08:30:00.000Z","documents":[{"id":"01960000-0000-4000-8000-00000000d0c5","page_count":1}],"pages":[{"document_id":"01960000-0000-4000-8000-00000000d0c5","page":1,"width":595.28,"height":841.89,"rotation":0}],"roles":[{"name":"Employee","routing_type":"sign","kind":"party","step":1,"presign_hint":false,"presence":"required"}],"subjects":[{"key":"employee","label":"Employee","presence":"required","starts_as":"absent"}],"questions":[],"fields":[{"id":"01960000-0000-4000-8000-00000000f1e1","type":"text","label":"Full name","required":true,"fixed":false,"role":"Employee","document_id":"01960000-0000-4000-8000-00000000d0c5","page":1,"subject":"employee","data_key":"staff.full_name","tier":"organisation","name_source":"accepted","question_id":null,"option_value":null,"options":null,"rect":{"x":0.1007929,"y":0.2107045,"w":0.5689591,"h":0.0213805},"context":{"label":"Full name","row":null,"column":"Full name","option":null,"section":"Employment contract","nearby":["\u003c\u003ctext:Employee:Full name:subject(employee):key(staff.full_name)>>","Full name"],"widget_name":null,"tooltip":null,"continues":null},"cells":null,"continuations":null,"amount":null}],"coverage":{"prefillable":1,"core":0,"organisation":1,"legacy":0,"unnamed":0,"questions":0,"unnamed_groups":0,"unnamed_options":0,"collisions":0,"fallback":0,"fallback_options":0}}}},"exampleType":"examples"}},"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."}}},"exampleType":"examples"},"b1bf8b53-7dce-48ad-9e51-b14bb9591551":{"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.\n\n`idempotency_key_required` — Send `Idempotency-Key: \u003cuuid>` — this operation takes one and the request carried none. A distinct code from `invalid_request` because the remedy is to ADD a header, and an integrator reading it in a log should not have to work that out. (A key that is present but malformed is `invalid_request`, and its `message` names the header.)","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","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","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","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","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","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","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"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.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"01cefd29-c005-419d-84f6-30096ad30bfd":{"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":{"type":"object","description":"The refusal.","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","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","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","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","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","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"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.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"acb0ad98-1f2f-4789-b572-3d9bc3b50f31":{"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.\n\n`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 until the key changes: an owner or admin edits its permissions under Settings → API keys, and the same key holds the new scope from its next request — no new key is needed. 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.\n\n`api_key_owner_removed` — The person who created this key has left the organisation, and everything the key creates or sends — an envelope, a batch, a template — is attributed to that person, who must still be a member. The key is not revoked and its reads still work, and so does managing webhooks; mint a new key from a current member and use that.\n\n`test_key_cannot_edit_templates` — A `vsk_test_` key tried to rename a template’s fields. A template has no environment — one template serves test and live sends alike — so a test key’s rename would change what live envelopes contain, and a swapped address prefills the wrong box silently. Rename with a live key that names `templates:name`, or in the editor.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","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","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","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","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","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","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"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.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"2853b720-b9d0-4232-a5de-df9312ac9448":{"description":"`idempotency_key_reused` — This key was already used for a DIFFERENT request. ⚠️ The request itself may be perfectly valid — what conflicts is the key against state we already hold, which is what 409 means and why it is not a 400. Mint a new key. Do not retry with this one; it will conflict forever.\n\n`request_in_progress` — A request carrying this key has not finished. We deliberately do not block waiting for it — that would hold a connection across a send that calls an email provider N times. Retry the identical request; when the first one lands you will get its result, replayed.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","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","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","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","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","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","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"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.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"d7de6fe6-ccab-49de-94d2-e015cdeafa57":{"description":"`step_with_signing_mode` — Steps and `signing_mode` were both given — `step` on a recipient of `POST /api/v1/envelopes/one-off`, or `role_steps` on `POST /api/v1/templates`. They answer the same question, who is asked when, so give one of them.\n\n`document_too_complex` — The document needs more memory or time to read than one document is allowed, what reading it produced is larger than one document may produce, or it could not be read through at all. Every uploaded PDF is read in an isolated service, one document at a time, under a fixed memory limit and a fixed time limit, and this one went past one of them; the message says which. Because nothing else was running there, the same document fails the same way. On an upload (`POST /api/v1/templates`, `POST /api/v1/envelopes/one-off`) nothing was stored or created; printing the document to a new PDF usually makes it simpler. On `GET /api/v1/documents/{documentId}/pages/{pageNumber}` or `.../content`, the document was stored before uploads were checked this way and its viewing copy cannot be made; the template, with every field and its position, is still readable from `GET /api/v1/templates/{templateId}`. Retrying gives the same answer.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","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","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","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","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","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","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"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.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"05b2115e-40d9-4c65-a814-dcd26249f1f8":{"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. THREE 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; `POST /api/v1/templates/{templateId}/preview` shares the per-organisation one. 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":{"type":"object","description":"The refusal.","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","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","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","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","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","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"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.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"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."}}},"exampleType":"generated"},"7d0e7d97-a80f-4b22-98b8-5d8c0e3763d4":{"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":{"type":"object","description":"The refusal.","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","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","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","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","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","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"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.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"f0b366a0-057d-4c96-b885-231f2e20c294":{"description":"`service_unavailable` — Ours, and briefly. Something this operation depends on was not answering, or was already doing as much as it will at once. What it was depends on the operation: on a create, the service that renders a Word document to a PDF, or the isolated service every uploaded document is read in, when it is starting up, at capacity, or did not answer in time; on `GET .../documents/{position}/draft` and `POST /api/v1/templates/{templateId}/preview`, the service that renders the draft or the preview itself; on the two template-document reads (`GET /api/v1/documents/{documentId}/pages/{pageNumber}` and `.../content`), that same isolated service, which says so with `Retry-After`. ⚠️ THE DISTINCTION FROM 400 IS THE WHOLE POINT: your request is fine and your document is fine, so do not go and re-save it. On a create, nothing was created and no allowance was spent. On an operation that takes an `Idempotency-Key`, retry the identical request with the SAME one — a completed key replays, so a retry can never make a second envelope or a second template even if the first attempt got further than this answer suggests. A new key could. ⚠️ ON THE DRAFT AND THE PREVIEW THE ATTEMPT WAS ALREADY PAID FOR: the render is charged to the per-minute draft ceilings (the envelope’s and the organisation’s, or the organisation’s alone) before the renderer is asked, and a render that then fails is not refunded. There is no key to reuse, because there is nothing to replay — so retry on the backoff above rather than at once, or an outage of ours becomes a `rate_limited` of yours.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","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","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","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","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","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","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"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.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"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."}}},"exampleType":"generated"}},"security":{"001117df-617e-47ef-97a0-72ed3aba026f":{"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.","scopes":[],"schemeName":"ApiKey"}}},"servers":{"2ed67dbf-843b-4ce0-93c8-8c35248fcb3e":{"url":"https://app.vumasign.com"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"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.","scopes":[],"schemeName":"ApiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"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.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"ApiKey","name":"Authorization"}],"title":"ApiKey"}]},"originalFileLocation":"openapi.json"},"subdomain":"vumasign","siteName":"Vumasign","title":"Upload a PDF or a Word document and get a template with its fields already placed. - Vumasign","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-16T05:07:55.839Z","originalFileLocation":"api-reference/create-template.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"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. ⚠️ FIRST, CHECK THIS IS THE RESOURCE YOU WANT. A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in GET /api/v1/templates and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want POST /api/v1/envelopes/one-off instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: template_id comes back null. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused template_has_no_fields there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted. ⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE. ⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured. Text tags — write the field into the document where it goes, and it arrives placed and already assigned to the right signer: \u0026lt;\u0026gt; a signature for the role named \u0026lt;\u0026gt; a labelled text box \u0026lt;\u0026gt; the signer’s job title, prefilled \u0026lt;\u0026gt; the date they signed, stamped \u0026lt;\u0026gt; a box they may leave empty \u0026lt;\u0026gt; checked as an email address \u0026lt;\u0026gt; say the size, do not pad the tag \u0026lt;\u0026gt; the api name a value addresses \u0026lt;\u0026gt; one box of a question; each box says it \u0026lt;\u0026gt; on any one box: up to three ticked \u0026lt;\u0026gt; thirteen printed boxes, one character each \u0026lt;\u0026gt; a date in eight printed boxes, day first \u0026lt;\u0026gt; one answer in two sets of boxes, \u0026lt;\u0026gt; filled part(1) first Types: sig, signature, initial, text, dateinput, check, checkbox, title, company, name, email, datesigned. \u0026lt;\u0026gt; names the role EXACTLY and case-sensitively; \u0026lt;\u0026gt; names it BY POSITION — signer1 is the first entry in your roles array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: optional, validate(), dimension(WxH mm|pt) and key() — which sets the field’s data_key, stored lower-cased, so address it in lower case when you prefill; the name is a core key (GET /api/v1/vocabulary) or follows the naming grammar, namespace.attribute, and any other refuses the request. A QUESTION is declared on its tickbox tags: every box of it says question() — the question’s data_key, a choice key of the core (only its own options) or one in the grammar — and option(), its option_value; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says select(0-3), select(2) or select(1-) (` is every box), and named by ask() on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no key(...) and no optional. PRINTED BOXES: cells() on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a key(...) and a subject, each with cells() and part(), are ONE field filled in k order — part(1) first — returned with cells and continuations; a part needs both cells(...) and key(...), and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with dimension(...). A DATE IN PRINTED BOXES is a dateinput tag with cells(8), or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: order(DD/MM/YYYY), order(MM/DD/YYYY) or order(YYYY/MM/DD) on the tag or one part, or in the label, as Date of birth (DD/MM/YYYY). It is a date field whose value is its digits in the order the boxes print them — 16082026 for 16 August 2026, day first; a value sent as YYYY-MM-DD is accepted too and laid into the boxes in that order — and a date tag with cells(...) and no order refuses the request. Detection names nothing: a detected field arrives with no data_key, and a detected question with none either, each box with a proposed option_value; name them with PATCH .../fields. A segment shaped like name(...) is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without cells(...), a condition, a dropdown’s options or a validate(regex) pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards. ⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows. ⚠️ BUT THAT SAYS NOTHING ABOUT WHICH ENDPOINT, and this paragraph used to be read as though it did. POST /api/v1/envelopes/one-off accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient. ⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 invalid_request, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print \u0026lt;\u0026gt; on a document somebody signs. ⚠️ WHO A FIELD IS ABOUT — subject(dependant_2). Declare the people the document asks about in subjects, then address a field to one of them. A field addressed to somebody who is not on a given envelope is hidden and not required, automatically, with no condition to write: \u0026lt;\u0026gt; The argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does. ⚠️ AND THE SUBJECT MUST BE conditional FOR ANY OF IT TO MATTER. A required subject is on every envelope and can never be absent, which is the safe default; conditional is the one the caller or the signer decides about. A medical-aid application declaring spouse and dependant_1..3 as conditional asks for none of them until somebody says that person exists — which is the whole point. ⚠️ WHERE THE FIELD LANDS, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is centred vertically on the tag’s line — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. dimension() replaces both, and is placed the same way. ⚠️ SO WRITE THE TAG ON THE LINE ABOVE A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew: \u0026lt;\u0026gt; \u0026lt;\u0026gt; _________________ _________________ Employee name Date The signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; dimension() sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it. Sizes by tag: sig or signature 40pt tall, at least 120pt wide; initial 40pt tall, at least 40pt wide; dateinput 18pt tall, at least 80pt wide; text 18pt tall, at least 80pt wide; check or checkbox 14pt tall, at least 14pt wide; title 15.2pt tall, at least 131pt wide; company 15.2pt tall, at least 131pt wide; name 15.2pt tall, at least 131pt wide; email 15.2pt tall, at least 166.6pt wide; datesigned 15.2pt tall, at least 89pt wide. ⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well. ⚠️ AND THE DELIMITER IS \u0026lt;\u0026lt; \u0026gt;\u0026gt; BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every {-based templating engine destroys a {{ }} tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. \u0026lt;\u0026lt; \u0026gt;\u0026gt; is untouched by all three, so your merge fields ({employee.full_name}, {#clause}…{/}) and your tags coexist with nothing to reconfigure. A {{type:Role}} tag is refused by name rather than ignored, as is Dropbox Sign’s [sig|req|signer1], so neither can be uploaded silently and printed on a signed document. ✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. file takes a Word .docx as well as a PDF — decided by the BYTES, so there is no content_type to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the .docx. We render it, and the tags survive that render, which is the whole reason they are text. A Word document (.docx) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later GET refer to, and it is what a signer sees. The .docx you sent is retained unchanged and is not what anybody signs. ⚠️ THE OLDER .doc IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a .docx. Detection, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-cc role, for you to reassign. ⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. fields being empty is how you tell. The document travels base64-encoded inside the JSON body rather than as multipart/form-data, so one media type and one HTTP client serve every endpoint of this API. See file for what that costs and what it bounds. A vsk_test_` key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Vumasign\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Upload a PDF or a Word document and get a template with its fields already placed. - Vumasign\">\u003cmeta data-mint-head property=\"og:description\" content=\"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. ⚠️ FIRST, CHECK THIS IS THE RESOURCE YOU WANT. A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in GET /api/v1/templates and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want POST /api/v1/envelopes/one-off instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: template_id comes back null. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused template_has_no_fields there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted. ⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE. ⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured. Text tags — write the field into the document where it goes, and it arrives placed and already assigned to the right signer: \u0026lt;\u0026gt; a signature for the role named \u0026lt;\u0026gt; a labelled text box \u0026lt;\u0026gt; the signer’s job title, prefilled \u0026lt;\u0026gt; the date they signed, stamped \u0026lt;\u0026gt; a box they may leave empty \u0026lt;\u0026gt; checked as an email address \u0026lt;\u0026gt; say the size, do not pad the tag \u0026lt;\u0026gt; the api name a value addresses \u0026lt;\u0026gt; one box of a question; each box says it \u0026lt;\u0026gt; on any one box: up to three ticked \u0026lt;\u0026gt; thirteen printed boxes, one character each \u0026lt;\u0026gt; a date in eight printed boxes, day first \u0026lt;\u0026gt; one answer in two sets of boxes, \u0026lt;\u0026gt; filled part(1) first Types: sig, signature, initial, text, dateinput, check, checkbox, title, company, name, email, datesigned. \u0026lt;\u0026gt; names the role EXACTLY and case-sensitively; \u0026lt;\u0026gt; names it BY POSITION — signer1 is the first entry in your roles array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: optional, validate(), dimension(WxH mm|pt) and key() — which sets the field’s data_key, stored lower-cased, so address it in lower case when you prefill; the name is a core key (GET /api/v1/vocabulary) or follows the naming grammar, namespace.attribute, and any other refuses the request. A QUESTION is declared on its tickbox tags: every box of it says question() — the question’s data_key, a choice key of the core (only its own options) or one in the grammar — and option(), its option_value; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says select(0-3), select(2) or select(1-) (` is every box), and named by ask() on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no key(...) and no optional. PRINTED BOXES: cells() on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a key(...) and a subject, each with cells() and part(), are ONE field filled in k order — part(1) first — returned with cells and continuations; a part needs both cells(...) and key(...), and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with dimension(...). A DATE IN PRINTED BOXES is a dateinput tag with cells(8), or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: order(DD/MM/YYYY), order(MM/DD/YYYY) or order(YYYY/MM/DD) on the tag or one part, or in the label, as Date of birth (DD/MM/YYYY). It is a date field whose value is its digits in the order the boxes print them — 16082026 for 16 August 2026, day first; a value sent as YYYY-MM-DD is accepted too and laid into the boxes in that order — and a date tag with cells(...) and no order refuses the request. Detection names nothing: a detected field arrives with no data_key, and a detected question with none either, each box with a proposed option_value; name them with PATCH .../fields. A segment shaped like name(...) is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without cells(...), a condition, a dropdown’s options or a validate(regex) pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards. ⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows. ⚠️ BUT THAT SAYS NOTHING ABOUT WHICH ENDPOINT, and this paragraph used to be read as though it did. POST /api/v1/envelopes/one-off accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient. ⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 invalid_request, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print \u0026lt;\u0026gt; on a document somebody signs. ⚠️ WHO A FIELD IS ABOUT — subject(dependant_2). Declare the people the document asks about in subjects, then address a field to one of them. A field addressed to somebody who is not on a given envelope is hidden and not required, automatically, with no condition to write: \u0026lt;\u0026gt; The argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does. ⚠️ AND THE SUBJECT MUST BE conditional FOR ANY OF IT TO MATTER. A required subject is on every envelope and can never be absent, which is the safe default; conditional is the one the caller or the signer decides about. A medical-aid application declaring spouse and dependant_1..3 as conditional asks for none of them until somebody says that person exists — which is the whole point. ⚠️ WHERE THE FIELD LANDS, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is centred vertically on the tag’s line — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. dimension() replaces both, and is placed the same way. ⚠️ SO WRITE THE TAG ON THE LINE ABOVE A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew: \u0026lt;\u0026gt; \u0026lt;\u0026gt; _________________ _________________ Employee name Date The signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; dimension() sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it. Sizes by tag: sig or signature 40pt tall, at least 120pt wide; initial 40pt tall, at least 40pt wide; dateinput 18pt tall, at least 80pt wide; text 18pt tall, at least 80pt wide; check or checkbox 14pt tall, at least 14pt wide; title 15.2pt tall, at least 131pt wide; company 15.2pt tall, at least 131pt wide; name 15.2pt tall, at least 131pt wide; email 15.2pt tall, at least 166.6pt wide; datesigned 15.2pt tall, at least 89pt wide. ⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well. ⚠️ AND THE DELIMITER IS \u0026lt;\u0026lt; \u0026gt;\u0026gt; BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every {-based templating engine destroys a {{ }} tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. \u0026lt;\u0026lt; \u0026gt;\u0026gt; is untouched by all three, so your merge fields ({employee.full_name}, {#clause}…{/}) and your tags coexist with nothing to reconfigure. A {{type:Role}} tag is refused by name rather than ignored, as is Dropbox Sign’s [sig|req|signer1], so neither can be uploaded silently and printed on a signed document. ✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. file takes a Word .docx as well as a PDF — decided by the BYTES, so there is no content_type to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the .docx. We render it, and the tags survive that render, which is the whole reason they are text. A Word document (.docx) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later GET refer to, and it is what a signer sees. The .docx you sent is retained unchanged and is not what anybody signs. ⚠️ THE OLDER .doc IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a .docx. Detection, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-cc role, for you to reassign. ⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. fields being empty is how you tell. The document travels base64-encoded inside the JSON body rather than as multipart/form-data, so one media type and one HTTP client serve every endpoint of this API. See file for what that costs and what it bounds. A vsk_test_` key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Vumasign\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.vumasign.com/api-reference/create-template\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://vumasign.mintlify.site/_mintlify/api/og/v2?division=Templates\u0026amp;title=Upload+a+PDF+or+a+Word+document+and+get+a+template+with+its+fields+already+placed.\u0026amp;description=THE+ENDPOINT+THIS+API+EXISTS+FOR.+Send+a+document+and+a+list+of+roles%3B+get+back+a+template+whose+signature+boxes%2C+date+fields%2C+ID-number+combs+and+marital-statu\u0026amp;theme=5afaa4abac00f05afdc3c271\u0026amp;signature=dea521ba6b41c1e89e6c743c880e8b3495a0f72675a1a84c7e73123eca1c3902\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Upload a PDF or a Word document and get a template with its fields already placed. - Vumasign\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"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. ⚠️ FIRST, CHECK THIS IS THE RESOURCE YOU WANT. A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in GET /api/v1/templates and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want POST /api/v1/envelopes/one-off instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: template_id comes back null. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused template_has_no_fields there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted. ⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE. ⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured. Text tags — write the field into the document where it goes, and it arrives placed and already assigned to the right signer: \u0026lt;\u0026gt; a signature for the role named \u0026lt;\u0026gt; a labelled text box \u0026lt;\u0026gt; the signer’s job title, prefilled \u0026lt;\u0026gt; the date they signed, stamped \u0026lt;\u0026gt; a box they may leave empty \u0026lt;\u0026gt; checked as an email address \u0026lt;\u0026gt; say the size, do not pad the tag \u0026lt;\u0026gt; the api name a value addresses \u0026lt;\u0026gt; one box of a question; each box says it \u0026lt;\u0026gt; on any one box: up to three ticked \u0026lt;\u0026gt; thirteen printed boxes, one character each \u0026lt;\u0026gt; a date in eight printed boxes, day first \u0026lt;\u0026gt; one answer in two sets of boxes, \u0026lt;\u0026gt; filled part(1) first Types: sig, signature, initial, text, dateinput, check, checkbox, title, company, name, email, datesigned. \u0026lt;\u0026gt; names the role EXACTLY and case-sensitively; \u0026lt;\u0026gt; names it BY POSITION — signer1 is the first entry in your roles array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: optional, validate(), dimension(WxH mm|pt) and key() — which sets the field’s data_key, stored lower-cased, so address it in lower case when you prefill; the name is a core key (GET /api/v1/vocabulary) or follows the naming grammar, namespace.attribute, and any other refuses the request. A QUESTION is declared on its tickbox tags: every box of it says question() — the question’s data_key, a choice key of the core (only its own options) or one in the grammar — and option(), its option_value; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says select(0-3), select(2) or select(1-) (` is every box), and named by ask() on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no key(...) and no optional. PRINTED BOXES: cells() on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a key(...) and a subject, each with cells() and part(), are ONE field filled in k order — part(1) first — returned with cells and continuations; a part needs both cells(...) and key(...), and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with dimension(...). A DATE IN PRINTED BOXES is a dateinput tag with cells(8), or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: order(DD/MM/YYYY), order(MM/DD/YYYY) or order(YYYY/MM/DD) on the tag or one part, or in the label, as Date of birth (DD/MM/YYYY). It is a date field whose value is its digits in the order the boxes print them — 16082026 for 16 August 2026, day first; a value sent as YYYY-MM-DD is accepted too and laid into the boxes in that order — and a date tag with cells(...) and no order refuses the request. Detection names nothing: a detected field arrives with no data_key, and a detected question with none either, each box with a proposed option_value; name them with PATCH .../fields. A segment shaped like name(...) is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without cells(...), a condition, a dropdown’s options or a validate(regex) pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards. ⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows. ⚠️ BUT THAT SAYS NOTHING ABOUT WHICH ENDPOINT, and this paragraph used to be read as though it did. POST /api/v1/envelopes/one-off accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient. ⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 invalid_request, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print \u0026lt;\u0026gt; on a document somebody signs. ⚠️ WHO A FIELD IS ABOUT — subject(dependant_2). Declare the people the document asks about in subjects, then address a field to one of them. A field addressed to somebody who is not on a given envelope is hidden and not required, automatically, with no condition to write: \u0026lt;\u0026gt; The argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does. ⚠️ AND THE SUBJECT MUST BE conditional FOR ANY OF IT TO MATTER. A required subject is on every envelope and can never be absent, which is the safe default; conditional is the one the caller or the signer decides about. A medical-aid application declaring spouse and dependant_1..3 as conditional asks for none of them until somebody says that person exists — which is the whole point. ⚠️ WHERE THE FIELD LANDS, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is centred vertically on the tag’s line — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. dimension() replaces both, and is placed the same way. ⚠️ SO WRITE THE TAG ON THE LINE ABOVE A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew: \u0026lt;\u0026gt; \u0026lt;\u0026gt; _________________ _________________ Employee name Date The signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; dimension() sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it. Sizes by tag: sig or signature 40pt tall, at least 120pt wide; initial 40pt tall, at least 40pt wide; dateinput 18pt tall, at least 80pt wide; text 18pt tall, at least 80pt wide; check or checkbox 14pt tall, at least 14pt wide; title 15.2pt tall, at least 131pt wide; company 15.2pt tall, at least 131pt wide; name 15.2pt tall, at least 131pt wide; email 15.2pt tall, at least 166.6pt wide; datesigned 15.2pt tall, at least 89pt wide. ⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well. ⚠️ AND THE DELIMITER IS \u0026lt;\u0026lt; \u0026gt;\u0026gt; BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every {-based templating engine destroys a {{ }} tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. \u0026lt;\u0026lt; \u0026gt;\u0026gt; is untouched by all three, so your merge fields ({employee.full_name}, {#clause}…{/}) and your tags coexist with nothing to reconfigure. A {{type:Role}} tag is refused by name rather than ignored, as is Dropbox Sign’s [sig|req|signer1], so neither can be uploaded silently and printed on a signed document. ✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. file takes a Word .docx as well as a PDF — decided by the BYTES, so there is no content_type to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the .docx. We render it, and the tags survive that render, which is the whole reason they are text. A Word document (.docx) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later GET refer to, and it is what a signer sees. The .docx you sent is retained unchanged and is not what anybody signs. ⚠️ THE OLDER .doc IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a .docx. Detection, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-cc role, for you to reassign. ⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. fields being empty is how you tell. The document travels base64-encoded inside the JSON body rather than as multipart/form-data, so one media type and one HTTP client serve every endpoint of this API. See file for what that costs and what it bounds. A vsk_test_` key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://vumasign.mintlify.site/_mintlify/api/og/v2?division=Templates\u0026amp;title=Upload+a+PDF+or+a+Word+document+and+get+a+template+with+its+fields+already+placed.\u0026amp;description=THE+ENDPOINT+THIS+API+EXISTS+FOR.+Send+a+document+and+a+list+of+roles%3B+get+back+a+template+whose+signature+boxes%2C+date+fields%2C+ID-number+combs+and+marital-statu\u0026amp;theme=5afaa4abac00f05afdc3c271\u0026amp;signature=dea521ba6b41c1e89e6c743c880e8b3495a0f72675a1a84c7e73123eca1c3902\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Vumasign\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#00827B\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.vumasign.com/api-reference/create-template\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/create-template.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.vumasign.com/#organization\",\"name\":\"Vumasign\",\"url\":\"https://docs.vumasign.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/vumasign.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=f5e34bf1faf4c64eaa58dee0553702d6\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.vumasign.com#website\",\"name\":\"Vumasign\",\"url\":\"https://docs.vumasign.com\",\"publisher\":{\"@id\":\"https://docs.vumasign.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.vumasign.com/api-reference/create-template#webpage\",\"url\":\"https://docs.vumasign.com/api-reference/create-template\",\"name\":\"Upload a PDF or a Word document and get a template with its fields already placed.\",\"description\":\"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. ⚠️ FIRST, CHECK THIS IS THE RESOURCE YOU WANT. A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in GET /api/v1/templates and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want POST /api/v1/envelopes/one-off instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: template_id comes back null. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused template_has_no_fields there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted. ⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE. ⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured. Text tags — write the field into the document where it goes, and it arrives placed and already assigned to the right signer: \\u003c> a signature for the role named \\u003c> a labelled text box \\u003c> the signer’s job title, prefilled \\u003c> the date they signed, stamped \\u003c> a box they may leave empty \\u003c> checked as an email address \\u003c> say the size, do not pad the tag \\u003c> the api name a value addresses \\u003c> one box of a question; each box says it \\u003c> on any one box: up to three ticked \\u003c> thirteen printed boxes, one character each \\u003c> a date in eight printed boxes, day first \\u003c> one answer in two sets of boxes, \\u003c> filled part(1) first Types: sig, signature, initial, text, dateinput, check, checkbox, title, company, name, email, datesigned. \\u003c> names the role EXACTLY and case-sensitively; \\u003c> names it BY POSITION — signer1 is the first entry in your roles array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: optional, validate(), dimension(WxH mm|pt) and key() — which sets the field’s data_key, stored lower-cased, so address it in lower case when you prefill; the name is a core key (GET /api/v1/vocabulary) or follows the naming grammar, namespace.attribute, and any other refuses the request. A QUESTION is declared on its tickbox tags: every box of it says question() — the question’s data_key, a choice key of the core (only its own options) or one in the grammar — and option(), its option_value; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says select(0-3), select(2) or select(1-) (` is every box), and named by ask() on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no key(...) and no optional. PRINTED BOXES: cells() on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a key(...) and a subject, each with cells() and part(), are ONE field filled in k order — part(1) first — returned with cells and continuations; a part needs both cells(...) and key(...), and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with dimension(...). A DATE IN PRINTED BOXES is a dateinput tag with cells(8), or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: order(DD/MM/YYYY), order(MM/DD/YYYY) or order(YYYY/MM/DD) on the tag or one part, or in the label, as Date of birth (DD/MM/YYYY). It is a date field whose value is its digits in the order the boxes print them — 16082026 for 16 August 2026, day first; a value sent as YYYY-MM-DD is accepted too and laid into the boxes in that order — and a date tag with cells(...) and no order refuses the request. Detection names nothing: a detected field arrives with no data_key, and a detected question with none either, each box with a proposed option_value; name them with PATCH .../fields. A segment shaped like name(...) is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without cells(...), a condition, a dropdown’s options or a validate(regex) pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards. ⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows. ⚠️ BUT THAT SAYS NOTHING ABOUT WHICH ENDPOINT, and this paragraph used to be read as though it did. POST /api/v1/envelopes/one-off accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient. ⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 invalid_request, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print \\u003c> on a document somebody signs. ⚠️ WHO A FIELD IS ABOUT — subject(dependant_2). Declare the people the document asks about in subjects, then address a field to one of them. A field addressed to somebody who is not on a given envelope is hidden and not required, automatically, with no condition to write: \\u003c> The argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does. ⚠️ AND THE SUBJECT MUST BE conditional FOR ANY OF IT TO MATTER. A required subject is on every envelope and can never be absent, which is the safe default; conditional is the one the caller or the signer decides about. A medical-aid application declaring spouse and dependant_1..3 as conditional asks for none of them until somebody says that person exists — which is the whole point. ⚠️ WHERE THE FIELD LANDS, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is centred vertically on the tag’s line — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. dimension() replaces both, and is placed the same way. ⚠️ SO WRITE THE TAG ON THE LINE ABOVE A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew: \\u003c> \\u003c> _________________ _________________ Employee name Date The signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; dimension() sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it. Sizes by tag: sig or signature 40pt tall, at least 120pt wide; initial 40pt tall, at least 40pt wide; dateinput 18pt tall, at least 80pt wide; text 18pt tall, at least 80pt wide; check or checkbox 14pt tall, at least 14pt wide; title 15.2pt tall, at least 131pt wide; company 15.2pt tall, at least 131pt wide; name 15.2pt tall, at least 131pt wide; email 15.2pt tall, at least 166.6pt wide; datesigned 15.2pt tall, at least 89pt wide. ⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well. ⚠️ AND THE DELIMITER IS \\u003c\\u003c >> BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every {-based templating engine destroys a {{ }} tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. \\u003c\\u003c >> is untouched by all three, so your merge fields ({employee.full_name}, {#clause}…{/}) and your tags coexist with nothing to reconfigure. A {{type:Role}} tag is refused by name rather than ignored, as is Dropbox Sign’s [sig|req|signer1], so neither can be uploaded silently and printed on a signed document. ✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. file takes a Word .docx as well as a PDF — decided by the BYTES, so there is no content_type to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the .docx. We render it, and the tags survive that render, which is the whole reason they are text. A Word document (.docx) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later GET refer to, and it is what a signer sees. The .docx you sent is retained unchanged and is not what anybody signs. ⚠️ THE OLDER .doc IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a .docx. Detection, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-cc role, for you to reassign. ⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. fields being empty is how you tell. The document travels base64-encoded inside the JSON body rather than as multipart/form-data, so one media type and one HTTP client serve every endpoint of this API. See file for what that costs and what it bounds. A vsk_test_` key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.\",\"dateModified\":\"2026-11-16T05:07:55.839Z\",\"isPartOf\":{\"@id\":\"https://docs.vumasign.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.vumasign.com/api-reference/create-template#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.vumasign.com/api-reference/create-template#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Templates\",\"item\":\"https://docs.vumasign.com/api-reference/list-templates\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Upload a PDF or a Word document and get a template with its fields already placed.\",\"item\":\"https://docs.vumasign.com/api-reference/create-template\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.vumasign.com/api-reference/create-template#apireference\",\"headline\":\"Upload a PDF or a Word document and get a template with its fields already placed.\",\"name\":\"Upload a PDF or a Word document and get a template with its fields already placed.\",\"description\":\"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. ⚠️ FIRST, CHECK THIS IS THE RESOURCE YOU WANT. A template is a LIBRARY ENTRY — a kind of document you will send again, which stays in GET /api/v1/templates and on the Templates screen until it is archived. If what you are sending exists ONCE — an offer of employment to one candidate, a Letter of Authority — you want POST /api/v1/envelopes/one-off instead. It takes the same document and the SAME TEXT TAGS, sends the same envelope, and creates no template: template_id comes back null. ⚠️ BUT IT PLACES FIELDS FROM TEXT TAGS ONLY. Nothing is detected, so a request whose documents carry no tag between them is refused template_has_no_fields there rather than measured as it is here — counted over the whole envelope, so an untagged annexure beside a tagged document is accepted. ⚠️ THIS FORK WAS NOT WRITTEN DOWN HERE AND IT COST A CUSTOMER A ROW PER SEND. The one-off endpoint explains itself perfectly and an integrator reading THIS page had no reason to go and find it — so a product owner sent one offer letter and watched it appear in his template library. The paragraph below about documents that differ per employee is what pointed them here, and it was right about the TAGS and silent about the RESOURCE. ⚠️ TWO WAYS FIELDS GET PLACED, AND THE DOCUMENT CHOOSES. If your document carries TEXT TAGS, they win and detection does not run. Otherwise the page is measured. Text tags — write the field into the document where it goes, and it arrives placed and already assigned to the right signer: \\u003c> a signature for the role named \\u003c> a labelled text box \\u003c> the signer’s job title, prefilled \\u003c> the date they signed, stamped \\u003c> a box they may leave empty \\u003c> checked as an email address \\u003c> say the size, do not pad the tag \\u003c> the api name a value addresses \\u003c> one box of a question; each box says it \\u003c> on any one box: up to three ticked \\u003c> thirteen printed boxes, one character each \\u003c> a date in eight printed boxes, day first \\u003c> one answer in two sets of boxes, \\u003c> filled part(1) first Types: sig, signature, initial, text, dateinput, check, checkbox, title, company, name, email, datesigned. \\u003c> names the role EXACTLY and case-sensitively; \\u003c> names it BY POSITION — signer1 is the first entry in your roles array — for a generator that does not know your roster. SEVERAL DIRECTIVES may follow the role, in any order: optional, validate(), dimension(WxH mm|pt) and key() — which sets the field’s data_key, stored lower-cased, so address it in lower case when you prefill; the name is a core key (GET /api/v1/vocabulary) or follows the naming grammar, namespace.attribute, and any other refuses the request. A QUESTION is declared on its tickbox tags: every box of it says question() — the question’s data_key, a choice key of the core (only its own options) or one in the grammar — and option(), its option_value; the boxes of one document sharing a key and a subject are one question. It is single-select unless one box says select(0-3), select(2) or select(1-) (` is every box), and named by ask() on one box, or else by the core’s label or its key. A question of one box must say its bounds. A box of a question takes no key(...) and no optional. PRINTED BOXES: cells() on a text tag makes its box a comb of n cells, one character each. Tags on one page sharing a key(...) and a subject, each with cells() and part(), are ONE field filled in k order — part(1) first — returned with cells and continuations; a part needs both cells(...) and key(...), and one answer’s parts split across two pages, a missing or repeated k, or parts for different roles or people refuse the request; the same complete parts on another page are another field at the same key. Size the boxes with dimension(...). A DATE IN PRINTED BOXES is a dateinput tag with cells(8), or with parts of 2 + 2 + 4 or 4 + 2 + 2 cells, and its ORDER STATED, never guessed: order(DD/MM/YYYY), order(MM/DD/YYYY) or order(YYYY/MM/DD) on the tag or one part, or in the label, as Date of birth (DD/MM/YYYY). It is a date field whose value is its digits in the order the boxes print them — 16082026 for 16 August 2026, day first; a value sent as YYYY-MM-DD is accepted too and laid into the boxes in that order — and a date tag with cells(...) and no order refuses the request. Detection names nothing: a detected field arrives with no data_key, and a detected question with none either, each box with a proposed option_value; name them with PATCH .../fields. A segment shaped like name(...) is never a label: it is a directive this parser knows, or the whole request is refused. The first plain word or phrase becomes the field’s label, which is why a field labelled literally “optional” cannot be expressed by a tag. What a tag still cannot set is a per-character input shape on a box without cells(...), a condition, a dropdown’s options or a validate(regex) pattern — a pattern would have to survive being typed into a document — so those belong to a field you edit in the editor afterwards. ⚠️ TAGS ARE WHAT YOU WANT WHEN EVERY DOCUMENT DIFFERS. A contract generated per employee — conditional clauses, a page count that varies — cannot reuse one template and has nothing detectable on it either. Tags travel with the text, so they land correctly however the document reflows. ⚠️ BUT THAT SAYS NOTHING ABOUT WHICH ENDPOINT, and this paragraph used to be read as though it did. POST /api/v1/envelopes/one-off accepts the identical tags. If each generated contract goes to one person and is never sent again, send it THERE: every one you create here is a permanent library row, and a hundred offers of employment is a hundred of them. Create a template here when the document is a KIND you will send repeatedly — even if its text is merged per recipient. ⚠️ A TAG THAT CANNOT BE PLACED REFUSES THE WHOLE REQUEST with 400 invalid_request, naming every bad tag and its page. A tag naming a role you did not declare is the common one. Nothing is created — silently dropping the tag would lose a signature field, and leaving it as text would print \\u003c> on a document somebody signs. ⚠️ WHO A FIELD IS ABOUT — subject(dependant_2). Declare the people the document asks about in subjects, then address a field to one of them. A field addressed to somebody who is not on a given envelope is hidden and not required, automatically, with no condition to write: \\u003c> The argument is the subject’s KEY, not its label — the key is stable and the label is prose somebody may rename. An undeclared key refuses the whole request, naming the ones the document does declare, exactly as an unknown role does. ⚠️ AND THE SUBJECT MUST BE conditional FOR ANY OF IT TO MATTER. A required subject is on every envelope and can never be absent, which is the safe default; conditional is the one the caller or the signer decides about. A medical-aid application declaring spouse and dependant_1..3 as conditional asks for none of them until somebody says that person exists — which is the whole point. ⚠️ WHERE THE FIELD LANDS, which this reference did not say until a customer had to work it out from a screenshot. The field’s LEFT EDGE is where the tag starts, and the field is centred vertically on the tag’s line — so it straddles the line you typed on, reaching about half its height above and half below the middle of the tag’s text, whatever type it is. Its HEIGHT comes from its type. Its WIDTH is the tag’s own printed width or the type’s minimum, whichever is larger. dimension() replaces both, and is placed the same way. ⚠️ SO WRITE THE TAG ON THE LINE ABOVE A RULE, not on the rule and not under it. Signature blocks are drawn with underscores, and there is nowhere on a row of underscores to put a tag without breaking the rule you drew: \\u003c> \\u003c> _________________ _________________ Employee name Date The signature, 40pt tall, then straddles its rule. A shorter field — a date, a text box, a signed date — is centred on the same line but reaches less far, so at ordinary line spacing it sits just above its rule rather than across it; dimension() sets an exact size when you want it to reach the rule. A tag on the row BELOW a rule puts the field below it, beside whatever caption is there — which is a common way to end up with a date under the line instead of on it. Sizes by tag: sig or signature 40pt tall, at least 120pt wide; initial 40pt tall, at least 40pt wide; dateinput 18pt tall, at least 80pt wide; text 18pt tall, at least 80pt wide; check or checkbox 14pt tall, at least 14pt wide; title 15.2pt tall, at least 131pt wide; company 15.2pt tall, at least 131pt wide; name 15.2pt tall, at least 131pt wide; email 15.2pt tall, at least 166.6pt wide; datesigned 15.2pt tall, at least 89pt wide. ⚠️ AND THE TAG STAYS VISIBLE unless you write it in white. Nothing here rewrites your PDF, so a tag in black ink prints on the sealed document. Extraction finds white text perfectly well. ⚠️ AND THE DELIMITER IS \\u003c\\u003c >> BECAUSE YOUR DOCUMENT IS PROBABLY GENERATED. Every {-based templating engine destroys a {{ }} tag before we ever see the document — Mustache and Handlebars delete it SILENTLY, so the upload succeeds and reports no tags, and docxtemplater throws. \\u003c\\u003c >> is untouched by all three, so your merge fields ({employee.full_name}, {#clause}…{/}) and your tags coexist with nothing to reconfigure. A {{type:Role}} tag is refused by name rather than ignored, as is Dropbox Sign’s [sig|req|signer1], so neither can be uploaded silently and printed on a signed document. ✅ AND YOU NO LONGER HAVE TO RENDER IT TO PDF YOURSELF. file takes a Word .docx as well as a PDF — decided by the BYTES, so there is no content_type to set and nothing to rename — and a docxtemplater or Word pipeline therefore has one step FEWER than it used to: write the tags into the document and upload the .docx. We render it, and the tags survive that render, which is the whole reason they are text. A Word document (.docx) is accepted and converted to PDF on our side. The template is over the converted PDF: that is what page numbers, field coordinates and every later GET refer to, and it is what a signer sees. The .docx you sent is retained unchanged and is not what anybody signs. ⚠️ THE OLDER .doc IS NOT THE SAME FORMAT AND IS NOT ACCEPTED — it is refused by its bytes, with a sentence saying to Save As a .docx. Detection, when there are no tags, is the same code the editor’s “Find fields” button runs, not a second implementation — so a template authored here and one authored by a person pressing that button have their fields in the same places, with the same masks and the same inferred types, because it is the same function. It infers position but not ownership, so every detected field goes to your first non-cc role, for you to reassign. ⚠️ A DOCUMENT WITH NOTHING DETECTABLE IN IT IS NOT AN ERROR. A flat scan with no text layer yields no fields, and this still answers 201 with a template holding its roles, its document and no fields — which is the thing you then place fields on. fields being empty is how you tell. The document travels base64-encoded inside the JSON body rather than as multipart/form-data, so one media type and one HTTP client serve every endpoint of this API. See file for what that costs and what it bounds. A vsk_test_` key may author templates, deliberately: a template is a draft, nothing reaches a signer until an envelope is created AND sent, and iterating on where the boxes land is what a sandbox is for. Templates carry no sandbox/live distinction of their own.\",\"url\":\"https://docs.vumasign.com/api-reference/create-template\",\"mainEntityOfPage\":{\"@id\":\"https://docs.vumasign.com/api-reference/create-template#webpage\"},\"dateModified\":\"2026-11-16T05:07:55.839Z\",\"publisher\":{\"@id\":\"https://docs.vumasign.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.vumasign.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Vumasign\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Vumasign\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/create-template.md","siteName":"Vumasign","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Specification","pages":[{"title":"This document, the machine-readable description of the API.","deprecated":null,"version":null,"sidebarTitle":"Get openapi document","openapi":"/openapi.json get /api/v1/openapi.json","href":"/api-reference/get-openapi-document"}]},{"group":"Templates","pages":[{"title":"List live templates, newest first.","description":"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 between two pages is upload a template.\n\nArchived templates are never returned, by either endpoint.","deprecated":null,"version":null,"sidebarTitle":"List templates","openapi":"/openapi.json get /api/v1/templates","href":"/api-reference/list-templates"},{"title":"Upload a PDF or a Word document and get a template with its fields already placed.","deprecated":null,"version":null,"sidebarTitle":"Create template","openapi":"/openapi.json post /api/v1/templates","href":"/api-reference/create-template"},{"title":"One template, with every field address on it.","description":"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.\n\n⚠️ AND IT SHOWS WHERE EVERY BOX IS. Each `Field` carries a `rect`, and `pages` carries the dimensions those rectangles are fractions of. Together with `GET /api/v1/documents/{documentId}/pages/{pageNumber}`, which serves the page itself, that is enough for a program that can SEE to match fields it could not match from labels alone — which is the case on any real form, where `checklist.17` is a field name and \"ID or passport number\" appears four times on one page.\n\n⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such template anywhere; a template belonging to another organisation; one of yours that has been archived; and 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 key’s tenant.","deprecated":null,"version":null,"sidebarTitle":"Get template","openapi":"/openapi.json get /api/v1/templates/{templateId}","href":"/api-reference/get-template"},{"title":"The core vocabulary, and your organisation’s own keys.","deprecated":null,"version":null,"sidebarTitle":"Get vocabulary","openapi":"/openapi.json get /api/v1/vocabulary","href":"/api-reference/get-vocabulary"},{"title":"A template’s field map, as a spreadsheet: one numbered row per field.","deprecated":null,"version":null,"sidebarTitle":"Get template field map","openapi":"/openapi.json get /api/v1/templates/{templateId}/field-map","href":"/api-reference/get-template-field-map"},{"title":"One document of a template with every field outlined and numbered on it, as a PDF.","deprecated":null,"version":null,"sidebarTitle":"Get template document field map","openapi":"/openapi.json get /api/v1/templates/{templateId}/documents/{documentId}/field-map","href":"/api-reference/get-template-document-field-map"},{"title":"Rename a template’s fields and questions: names only, all or nothing.","deprecated":null,"version":null,"sidebarTitle":"Rename template fields","openapi":"/openapi.json patch /api/v1/templates/{templateId}/fields","href":"/api-reference/rename-template-fields"},{"title":"Rename one field of a template.","deprecated":null,"version":null,"sidebarTitle":"Rename template field","openapi":"/openapi.json patch /api/v1/templates/{templateId}/fields/{fieldId}","href":"/api-reference/rename-template-field"},{"title":"Ask Vumasign to name a template’s fields: a naming run, produced in the background.","deprecated":null,"version":null,"sidebarTitle":"Request naming run","openapi":"/openapi.json post /api/v1/templates/{templateId}/naming-runs","href":"/api-reference/request-naming-run"},{"title":"Read a naming run: its status, its proposals with reasons, and the preview.","deprecated":null,"version":null,"sidebarTitle":"Get naming run","openapi":"/openapi.json get /api/v1/templates/{templateId}/naming-runs/{runId}","href":"/api-reference/get-naming-run"},{"title":"Accept a naming run’s proposals, all or some, with your own corrections: all or nothing.","deprecated":null,"version":null,"sidebarTitle":"Accept naming run","openapi":"/openapi.json post /api/v1/templates/{templateId}/naming-runs/{runId}/accept","href":"/api-reference/accept-naming-run"},{"title":"Accept a naming run’s own proposals, if the template has not changed since: no overrides.","deprecated":null,"version":null,"sidebarTitle":"Accept naming run current","openapi":"/openapi.json post /api/v1/templates/{templateId}/naming-runs/{runId}/accept-current","href":"/api-reference/accept-naming-run-current"},{"title":"The people a template is about or signed by, each with a proposed decision.","deprecated":null,"version":null,"sidebarTitle":"List template people","openapi":"/openapi.json get /api/v1/templates/{templateId}/people","href":"/api-reference/list-template-people"},{"title":"Decide one person: a subject for their details, a signing role, both, or a witness.","deprecated":null,"version":null,"sidebarTitle":"Decide template person","openapi":"/openapi.json put /api/v1/templates/{templateId}/people/{personId}","href":"/api-reference/decide-template-person"},{"title":"Apply Vumasign’s own current proposal for one person.","deprecated":null,"version":null,"sidebarTitle":"Accept template person proposal","openapi":"/openapi.json post /api/v1/templates/{templateId}/people/{personId}/accept-proposal","href":"/api-reference/accept-template-person-proposal"},{"title":"What creating an envelope would say about your values, without creating one.","deprecated":null,"version":null,"sidebarTitle":"Validate template values","openapi":"/openapi.json post /api/v1/templates/{templateId}/validate-values","href":"/api-reference/validate-template-values"},{"title":"One of a template’s documents, filled in with your values, as it would be sealed.","deprecated":null,"version":null,"sidebarTitle":"Preview template","openapi":"/openapi.json post /api/v1/templates/{templateId}/preview","href":"/api-reference/preview-template"}]},{"group":"Documents","pages":[{"title":"One page of a document, as a PDF, to look at.","deprecated":null,"version":null,"sidebarTitle":"Get document page","openapi":"/openapi.json get /api/v1/documents/{documentId}/pages/{pageNumber}","href":"/api-reference/get-document-page"},{"title":"A template document, every page, as one PDF.","deprecated":null,"version":null,"sidebarTitle":"Get document content","openapi":"/openapi.json get /api/v1/documents/{documentId}/content","href":"/api-reference/get-document-content"}]},{"group":"Envelopes","pages":[{"title":"List envelopes, newest first, optionally filtered by status or by your reference.","deprecated":null,"version":null,"sidebarTitle":"List envelopes","openapi":"/openapi.json get /api/v1/envelopes","href":"/api-reference/list-envelopes"},{"title":"Create an envelope from a template, and optionally send it.","deprecated":null,"version":null,"sidebarTitle":"Create envelope","openapi":"/openapi.json post /api/v1/envelopes","href":"/api-reference/create-envelope"},{"title":"Send a document that is not a template, and optionally send it.","deprecated":null,"version":null,"sidebarTitle":"Create one off envelope","openapi":"/openapi.json post /api/v1/envelopes/one-off","href":"/api-reference/create-one-off-envelope"},{"title":"Create and send many envelopes from one template, in one request.","deprecated":null,"version":null,"sidebarTitle":"Create envelope batch","openapi":"/openapi.json post /api/v1/envelopes/batches","href":"/api-reference/create-envelope-batch"},{"title":"One envelope, as it stands right now.","deprecated":null,"version":null,"sidebarTitle":"Get envelope","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}","href":"/api-reference/get-envelope"},{"title":"Discard a draft envelope. ⚠️ Drafts only, and it cannot be undone.","deprecated":null,"version":null,"sidebarTitle":"Delete envelope","openapi":"/openapi.json delete /api/v1/envelopes/{envelopeId}","href":"/api-reference/delete-envelope"},{"title":"Get an envelope’s document, and its certificate once sealed.","deprecated":null,"version":null,"sidebarTitle":"List envelope documents","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}/documents","href":"/api-reference/list-envelope-documents"},{"title":"The document as it stands, mid-flight, stamped DRAFT.","deprecated":null,"version":null,"sidebarTitle":"Get envelope document draft","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}/documents/{position}/draft","href":"/api-reference/get-envelope-document-draft"},{"title":"Withdraw a sent envelope.","deprecated":null,"version":null,"sidebarTitle":"Void envelope","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/void","href":"/api-reference/void-envelope"},{"title":"Give a sent envelope a later deadline.","deprecated":null,"version":null,"sidebarTitle":"Extend envelope deadline","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/extend","href":"/api-reference/extend-envelope-deadline"},{"title":"Send a draft envelope to its recipients.","deprecated":null,"version":null,"sidebarTitle":"Send envelope","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/send","href":"/api-reference/send-envelope"},{"title":"Mint a short-lived, single-use URL for an embedded signer.","deprecated":null,"version":null,"sidebarTitle":"Create signing url","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url","href":"/api-reference/create-signing-url"}]},{"group":"Webhooks","pages":[{"title":"Every registered endpoint, with its health.","deprecated":null,"version":null,"sidebarTitle":"List webhooks","openapi":"/openapi.json get /api/v1/webhooks","href":"/api-reference/list-webhooks"},{"title":"Register an endpoint and mint its signing secret.","deprecated":null,"version":null,"sidebarTitle":"Create webhook","openapi":"/openapi.json post /api/v1/webhooks","href":"/api-reference/create-webhook"},{"title":"One endpoint, with its health.","deprecated":null,"version":null,"sidebarTitle":"Get webhook","openapi":"/openapi.json get /api/v1/webhooks/{webhookId}","href":"/api-reference/get-webhook"},{"title":"Remove an endpoint. ⚠️ Queued deliveries go with it.","deprecated":null,"version":null,"sidebarTitle":"Delete webhook","openapi":"/openapi.json delete /api/v1/webhooks/{webhookId}","href":"/api-reference/delete-webhook"},{"title":"Change the URL, the subscription, the brand filter or the active flag.","deprecated":null,"version":null,"sidebarTitle":"Update webhook","openapi":"/openapi.json patch /api/v1/webhooks/{webhookId}","href":"/api-reference/update-webhook"},{"title":"Mint a new signing secret, keeping the old one alive briefly.","deprecated":null,"version":null,"sidebarTitle":"Rotate webhook secret","openapi":"/openapi.json post /api/v1/webhooks/{webhookId}/rotate-secret","href":"/api-reference/rotate-webhook-secret"}]},{"group":"Brands","pages":[{"title":"List your organisation’s brands, newest first.","deprecated":null,"version":null,"sidebarTitle":"List brands","openapi":"/openapi.json get /api/v1/brands","href":"/api-reference/list-brands"},{"title":"One brand, archived or not.","deprecated":null,"version":null,"sidebarTitle":"Get brand","openapi":"/openapi.json get /api/v1/brands/{brandId}","href":"/api-reference/get-brand"},{"title":"Register one origin that may frame this brand’s signing pages.","deprecated":null,"version":null,"sidebarTitle":"Add brand embed origin","openapi":"/openapi.json post /api/v1/brands/{brandId}/embed-origins","href":"/api-reference/add-brand-embed-origin"},{"title":"Stop one origin framing this brand’s signing pages.","deprecated":null,"version":null,"sidebarTitle":"Remove brand embed origin","openapi":"/openapi.json delete /api/v1/brands/{brandId}/embed-origins","href":"/api-reference/remove-brand-embed-origin"}]},{"group":"Standing authorisations","pages":[{"title":"List standing authorisations, newest first, optionally filtered.","deprecated":null,"version":null,"sidebarTitle":"List standing authorisations","openapi":"/openapi.json get /api/v1/standing-authorisations","href":"/api-reference/list-standing-authorisations"},{"title":"One standing authorisation, as it stands now.","deprecated":null,"version":null,"sidebarTitle":"Get standing authorisation","openapi":"/openapi.json get /api/v1/standing-authorisations/{authorisationId}","href":"/api-reference/get-standing-authorisation"},{"title":"Cancel a pending standing authorisation request.","deprecated":null,"version":null,"sidebarTitle":"Cancel standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/cancel","href":"/api-reference/cancel-standing-authorisation"},{"title":"Email the grantor a fresh link to a pending request.","deprecated":null,"version":null,"sidebarTitle":"Resend standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/resend","href":"/api-reference/resend-standing-authorisation"},{"title":"Revoke a standing authorisation.","deprecated":null,"version":null,"sidebarTitle":"Revoke standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/revoke","href":"/api-reference/revoke-standing-authorisation"},{"title":"Renew a standing authorisation: send its grantor a new mandate that starts when it ends.","deprecated":null,"version":null,"sidebarTitle":"Renew standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/renew","href":"/api-reference/renew-standing-authorisation"},{"title":"Request a standing authorisation: generate the mandate and send it to the grantor.","deprecated":null,"version":null,"sidebarTitle":"Invite standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/invitations","href":"/api-reference/invite-standing-authorisation"}]}]}]},"basePath":"","title":"Upload a PDF or a Word document and get a template with its fields already placed. - Vumasign","buildId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","deploymentId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-BFmjTMeT.js","utils-BWr-sjpP.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-LafIDf0N.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-MJNzuxek.js","snippetPresets-DPZEtUvW.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-DQ2UhGIs.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-DUUJTUkE.js","shallow-BTf5bw35.js","getApiPlaygroundDisplay-h2POYYOO.js","CodeSnippet-C4qEftRe.js","CodeSnippets-CsSrOqMC.js","Page-CWFqNdGh.js","getPastedJson-DU6W6y78.js","icon-2ZYNQ78y.js","MethodPill-BMXJzYMm.js","DuplicateIcon-DNjdEpYZ.js","createIcon-WdPVhKxl.js","DynamicMarkdown-Z_y464fM.js","SectionHeading-Bcrd8azU.js","axios-vUo_bRtp.js","Markdown-BnvucbFu.js","dist-D7YyC486.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","katex-YMM-FMeD.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js","AssistantPageLink-D1I8TPjt.js"]}