Skip to main content
POST
Upload a PDF or a Word document and get a template with its fields already placed.

Authorizations

Authorization
string
header
required

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.

Example:

"JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c+PgplbmRvYmoK"

roles
string[]
required

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

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
documents
object[]
required

The pack, in the order it is stacked.

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.

roles
object[]
required

The signing roles, in the template’s order. When each is asked is its step.

subjects
object[]
required

The people whose data this template collects.

questions
object[]
required

The tickbox questions and how many answers each takes.

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.

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.

naming_run_id
string<uuid>

Present only when name_fields was true: the run naming the template. Read it, or wait for template.named.