- A template is a library entry: a kind of document — an employment contract, a membership
form — whose fields are placed once and which you send many times.
POST /api/v1/templatescreates it, and every envelope after that isPOST /api/v1/envelopeswith itstemplate_idand the people this copy is for — orPOST /api/v1/envelopes/batchesfor many copies at once. - A one-off envelope is a document that exists once, for one set of people — a Letter of
Authority, an offer of employment generated for one candidate.
POST /api/v1/envelopes/one-offtakes the document and the people in a single request and creates no template: the envelope’stemplate_idcomes backnull.
GET /api/v1/templates until somebody archives it in the dashboard, and this API has no operation
that deletes one. An integration that creates a template for every offer letter leaves
one behind for every offer letter. If the document is generated fresh each time, it is a one-off.
Choosing
Choose a template when the document is the same every time and only the people and a few
answers change: it is placed once, reviewed once in the editor, and each envelope is a small
request that names the people and what to prefill. Choose a one-off when your own system
generates the document — conditional clauses, a page count that varies — so there is nothing
stable to reuse, and the document can carry its own fields as text tags.
A one-off that turns out to be worth keeping can become a template from the dashboard, with Save
as template in the one-off’s editor. The one-off itself does not change, the new template needs a
plan that includes templates, as creating one does, and this API has no operation for it.
It keeps:
- the documents
- the boxes, each with its settings
- the labels of who signs
- the steps
- what each one does
- the verification each starts with
- which are groups
- which are normally pre-signed under a standing authorisation
- who the boxes are about, such as a spouse or a dependant, and whether each may be left out
- every name
- every email address
- every job title and company
- which standing authorisation a row was pre-signed under
- every answer locked into a box, and the lock with it: it may hold a client’s personal details
- every answer given for this one-off, by a signer or filled in through the API
- whether each person was on this one-off: a template is about nobody in particular until it is sent
The limits
The document bound is on the whole request, not on each document: a document travels
base64-encoded inside the JSON body, and every document in a one-off request shares one body. The
attachments of an envelope from a template share the same bound between them.
Documents larger than that go through the upload screen instead, which sends the file itself.
From a template
Create the template once.file is the whole document, base64-encoded — the value below is a
truncated stub, not a document — and roles names who signs it. When each role is asked is its
step, set with role_steps or
signing_mode; with neither, as here, everyone is asked at once.
POST /api/v1/templates
name is optional. When it is omitted or blank, the template takes the title printed at the top
of the document’s first page, if the page clearly has one; otherwise the name comes from filename,
as the upload screen suggests one; otherwise it is "Untitled document". A letterhead or a
heading repeated on later pages is not taken as a title. The title is picked by code from the
page’s own text: choosing the name sends nothing to the AI. A name you send is never replaced,
and a template’s name can be changed afterwards.
The answer carries the template’s id and the fields that were placed, each with its own id
and, where a text tag named one, the data_key a prefilled value is addressed to.
Detected fields arrive named, by Vumasign, and you match your data to those names; see Naming fields. Then each envelope names the people by the template’s role
names, and may prefill what your own records already know, and lock some of it:
POST /api/v1/envelopes
send
defaults to false, which creates a draft and emails nobody — send it later with
POST /api/v1/envelopes/{envelopeId}/send. Every role that has a
field needs a recipient who is not a copy, or the request is refused recipient_role_missing;
a role the template declares but places no field for needs nobody. A name the template does
not declare is refused recipient_role_unknown; Roles and recipients has the rules.
Not every field takes a value, and not every field that takes one can be locked. A job title or
a company belongs to whoever fills the role, not to the box, so locked on one is refused
value_not_lockable: send the value without locked, or set job_title and
company on the recipient, which is where those fields are filled from. What a value does to
each field type, in a batch row too:
In the dashboard, the send view’s Fill in tab takes the same values for one envelope, with
the same rules: see Filling in before sending.
Who the form is about
A lease may have a co-tenant and a surety, or neither. Declare such people as subjects when you create the template, eachconditional:
POST /api/v1/templates
starts_as is the sender’s choice for an envelope created in the dashboard:
Ask the signer (ask), or one of the other two in
Subjects. Left out, as for the surety
here, it is absent (Leave out), and it is ignored for a
required subject. The sender can change it in the editor, and reading the
template gives each subject’s presence and starts_as.
⚠️ An envelope you create through the API does not take starts_as for the people it records,
even a draft that a person later sends from the dashboard. Say who is on it in
subjects, by key: true, false, or "ask", which asks the signer at the start of signing.
POST /api/v1/envelopes
conditional subject you do not name is left out, and the signer is not
asked about them, whatever the template’s starts_as says. A batch row takes no subjects, so
every conditional subject is left out of a batch’s envelopes. One exception: when a draft you
created is sent later from the dashboard, a subject added to the template after the draft was made
takes the template’s starts_as, since your request could not name it.
Values for printed boxes
Some forms print a box for each character of an answer, such as a telephone number or an ID number. On the fields below, the separators people write between the groups are removed from a value you send before it is stored, because a box holds one character and has no room for them. A field at the same address that is not drawn as printed boxes keeps the value as you sent it.- Which fields: a field drawn as printed boxes, one character per box, whose validation is one of
phone,sa_id,sa_tax,sa_vat. - Which characters are removed: a space,
-,/,(,). A point and a comma are never removed. - A South African number: on a
phonefield of exactly 10 boxes, a leading+27or0027followed by nine digits becomes0and those nine digits. - For example, on a 10-box
phonefield,082 801 4085is checked and sealed as0828014085, and+27 82 801 4085as0828014085.
One value in several sets of boxes
Some forms print one answer as more than one set of boxes: a telephone number as a dialling code and a number, or a date as day, month and year. That is still one field, with one address and one value. InGET /api/v1/templates/{templateId}, such a field
carries cells, the number of boxes in its first set, and continuations, the later sets in the
order the value fills them, each with its own rect and cells. Both are null on any other
field. Send only the characters the boxes print: the separators above are removed only on the
fields listed there, and a date in boxes takes its digits alone, in the order the form prints them.
- One field, one value. A field with
cells: 3and one continuation ofcells: 7takes one value at its one address. Sent as082 801 4085to aphonefield, it is stored as0828014085and drawn082then8014085, filling each set of boxes from the left. validate-values counts it as one field. - Longer than its boxes: refused
cannot_be_drawnat create, and reportedcannot_be_drawnby validate-values, and never shortened to fit. For082 801 4085 1the address is a field drawn across 2 sets of printed boxes, one character in each box: 3 + 7 = 10 boxes. This value has 11 characters once the spaces and other separators the boxes do not hold are removed. - Shorter than its boxes: accepted at create. On a field whose value has one length (a date, or a validation of
phone,sa_id,sa_tax,sa_vat), an unlocked value must be completed by the signer before they can finish, and a locked one is refused at the send,locked_answer_unusable. Any other split field fills from the left and leaves its remaining boxes empty.
One amount in rands and cents
A form may print an amount as a rands box and a cents box, with a decimal point or comma printed between them and an R before them. Once the sender makes the two boxes one amount in the editor, the field’samount says so in
GET /api/v1/templates/{templateId}, and it takes one value, read
back as a decimal. It is not filled from the left: the rands are drawn right-aligned and the cents
fill their box.
- One field, one value. A field whose
amountis{ "fraction_digits": 2 }, withcells: 8and one continuation ofcells: 2, takes one decimal value.12 345,67is stored as12345.67and drawn12345then67;12345.67is stored as12345.67and drawn12345then67;R 8 500is stored as8500.00and drawn8500then00. The rands are drawn right-aligned, ending at the printed separator, and a whole amount’s cents print as zeros. - Too long for its boxes, or no amount: refused
cannot_be_drawn. For123456789the address is a field drawn as an amount in rands and cents. The field has 8 boxes for the rands, and the answer given has 9 digits before the decimal mark. - Read two ways: one point or one comma followed by exactly three digits is a decimal to one reader and thousands to another, so it is refused, never guessed. For
12.500the address is a field drawn as an amount in rands and cents. The field is an amount in rands and cents, and the answer given could be read as two different amounts. Write it with its cents, such as 12,50 or 1 234,00. Group thousands with spaces, or with the mark that is not the decimal one, as12 500,00or12,500.00.
Checking values before you send
Create refuses the firstvalues entry it cannot use and makes nothing, so finding every
mismatch that way takes one request per mistake.
POST /api/v1/templates/{templateId}/validate-values
takes the same values and subjects you would send to create, and answers for every entry
what create would do with it. It writes nothing, needs no Idempotency-Key, and answers a test
key exactly as it answers a live one.
POST /api/v1/templates/01960000-0000-4000-8000-0000000007e1/validate-values
results entry per value, in the order you sent them, and ok, which says
whether create would accept them all. An accepted entry carries fields, the number of fields it
would fill; a refused one carries the sentence create would refuse it with. The
reference shows the answer to this request.
When more than one entry is refused, create answers the first
duplicate_address if there is one,
and otherwise the entry with the lowest index. A subjects map the template refuses is refused
as a whole, invalid_request with create’s sentence, and no entry is judged.
It checks only what create checks of values. It does not look at the recipients, because they
belong to a send rather than to a mapping, and so it cannot know that a role will be pre-signed
under a standing authorisation; and it does not check whether
the template itself can make an envelope. Validate when you set a mapping up, and again whenever
the template changes.
Seeing the filled-in document
Validating tells you create would accept your values. To see what they look like on the page — a number spread one digit per printed box, a date in the form the field prints, the right option of a question ticked, a long name wrapping in its box —POST /api/v1/templates/{templateId}/preview takes the same
values and subjects and answers with one of the template’s documents as a PDF, every value
drawn exactly as the sealed copy will draw it and every page marked as a preview. Nothing is stored,
sent or billed, there is no envelope, and nobody is asked to sign. It needs a key holding both
templates:read and documents:read — the answer is the document
itself — and a test key gets the same answer as a live one.
A preview that renders is one the send would accept. The values are checked as
POST /api/v1/templates/{templateId}/validate-values
checks them, and the first one create
would refuse is refused here with create’s code and sentence; send the same body to validate-values
to see every entry’s verdict at once. Send the template_etag you checked against, and a template
that has changed since is refused template_changed, as create would refuse
it. The send’s own checks on the answers it would fix are asked as well, across every document of
the template — a locked, required box left empty, or a locked answer its box refuses, the template’s
own fixed answers included — and refused with the send’s code and sentence. A value too long for its box even at the smallest size the sealed copy prints is refused
cannot_be_drawn: create would accept it, and the envelope would then fail
to seal after everybody had signed.
There are no recipients, so every role is drawn as if it is on the envelope — an optional role
too, so you see the whole form. For the send’s checks your values stand in for the recipients: an
optional role is on the envelope when one of your values fills one of its boxes, and left out
otherwise, as a send leaves out an optional role nobody is named for. A left-out role’s boxes are
drawn but not checked, and a role whose box decides another role’s box cannot be left out: that is
refused as the send refuses it. A title or company box filled from a recipient’s own details is neither drawn
nor checked here.
Boxes you give no value stay blank, unless the template fixes the answer itself. Boxes the signing
fills — a signature, initials, the date of signing, the signer’s name and email — show whose they
are, such as Signature: Employee. For a template of more than one document,
say which to draw with document, its 1-based position in documents on
GET /api/v1/templates/{templateId}.
Each preview that renders counts against your organisation’s per-minute ceiling on renders, which
draft renders of envelopes count against too; past it the answer is
rate_limited, saying how long to wait. Every request that gets past the key
and the body checks is counted before the template is read — one refused for its values or a stale
etag, and one refused for the ceiling itself, included. To check values without spending the
ceiling, use validate-values, which draws nothing.
Attachments
An envelope from a template can carry documents of your own beside the template’s, such as a quote or a schedule made for this customer. Send them inattachments on
POST /api/v1/envelopes. Each is a PDF or a Word .docx,
base64-encoded, in the same shape as an entry of documents on a one-off; the value below is a
truncated stub. The envelope’s documents are the template’s first, in the template’s order, and then
the attachments, in the order you send them.
POST /api/v1/envelopes
role of a recipient in the request. That may be
one of the template’s roles, or a role only the attachments name, such as the Guarantor here when the
template has no such role. A recipient on a role only the attachments name signs. A recipient whose
role the template does not declare and no attachment’s tags name is refused
recipient_role_unknown, and a tag naming a role no recipient holds is refused
invalid_request, with the tag and its page.
What an attachment does not take:
- No
values.valuesfill the template’s fields only. A key an attachment’s tag declares still names its field, but no value is written to it, even when the template has a field at the same address. A value whose address is only on an attachment is refusedvalue_address_unknown. - No
subject(...)tags. An attachment declares no subjects, so a tag naming one is refusedinvalid_request, with the tag and its page. - Not in a batch. A batch row has no
attachments.
template_has_no_fields whatever the attachments
carry. When every document is your own, send a one-off instead.
The number of documents is counted across the envelope, the template’s and the attachments
together, and the attachments together are held to the document byte bound. Both are in
the limits above.
Each recipient is shown the documents that concern them rather than every document on the envelope:
see Which documents a recipient sees.
When the last recipient finishes, each document is sealed on its own, attachments included, and each
carries its own certificate of completion. Wait for envelope.sealed; then
GET /api/v1/envelopes/{envelopeId}/documents answers with
one sealed PDF per document, in the envelope’s order.
Document order
The template’s documents come first unless you say otherwise. To put an attachment first, such as an offer letter the employee should read before the agreement, list the envelope’s documents indocuments in the order to present them. Name an attachment by its index in attachments, from 0,
and a template document by its id in the documents of
GET /api/v1/templates/{templateId}.
POST /api/v1/envelopes
GET /api/v1/envelopes/{envelopeId}/documents lists the
documents in this order, and each keeps two numbers: position, its fixed address in the envelope,
where the first of the template’s documents on the envelope is always 1, and display_position,
where it is presented.
When you send documents, name every document once: every attachment and every one of the
template’s documents. A document not named, named twice, or an attachment index past the end of
attachments is refused invalid_request. A template document id the template
does not hold is refused template_changed: read the template again for its
current documents. Nothing is created either way. documents also reorders a template of several
documents without any attachments, and like attachments it is not taken in a batch.
Leaving a template document out
To send a template without one of its documents, such as a spouse’s form for an employee who is not married, name that document indocuments with include set to false. It is not part of the envelope:
nobody is shown it, it is not sealed, and the certificate’s “document 1 of 2” counts only the
documents kept. Its boxes go with it, including the boxes of a role the template requires, so an
employee who signs every document of a pack can still be sent the pack without one of them.
What is checked is a signature the role was sure to give: a required signature box, shown whatever
the answers and whoever the envelope is about. When a document you leave out holds one for a
role the template requires, that role must still have one on the documents you kept, or on an
attachment whose tag gives it a required signature, and a tag can name only a role you named a
recipient for. Initials do not count. A signature box the role may leave empty, or one that an
answer or who the envelope is about may hide, is not one it was sure to give, so leaving it out is
not checked, and a role whose boxes on the document are only initials or text loses them with it.
A role whose every box is on the documents you leave out goes with them, provided you name nobody
for it and it loses no signature it was sure to give. An optional role always may; a required role
may when its boxes there are only initials, text or signatures it was not sure to give. A required
role that loses a signature it was sure to give is refused by the rule above whether or not you
name anybody for it, and since a tag can name only a role you named a recipient for, naming nobody
leaves no attachment to give it one. If you name somebody for a role left with no box at all, the
request is refused, because they would be sent nothing to do; leave the recipient out too.
POST /api/v1/envelopes
position 1 is the first one you kept.
Some documents cannot be left out, because the envelope needs something on them.
Refused template_document_not_omittable (422) when:
- Every one of the template’s documents was left out. An envelope keeps at least one.
- The document holds a box about a subject (whose details it holds, or whose presence shows or hides it), or a question about one.
- A box on a document you kept is shown or hidden by a box on the document left out.
- The document holds some of the options of a question whose other options are on a document you kept.
- A role the template requires would be left with no signature box it is sure to sign (a required one, shown whatever the answers and whoever the envelope is about): its only ones are on the documents left out, and no attachment’s tag gives it another. Its other boxes on those documents simply go with them, and a role the template marks optional may lose all of its boxes.
- Every box of a role you named a recipient for is on the documents left out, so they would be sent nothing to do.
Many envelopes from one template
A batch is the bulk path, and it exists only from a template. Each row is one envelope — its recipients and its values — andsend, expires_at, brand_id and completion_delivery apply
to every row.
POST /api/v1/envelopes/batches
- A mistake in any row’s own data refuses the whole batch, and nothing is created: a mapping error in one row is usually in all of them.
- Past that, sending is per row. The status line says whether every row went out; when one did not — most often because the plan’s send allowance ran out partway — its draft is kept and named in the answer, and the remedy is to send those drafts rather than to rebuild the batch.
- A batch counts one unit per row against the rate limit, not one per request.
- There is no one-off batch. For many generated documents, make one one-off request each.
One-off
The document and its people, in one request. Each recipient’srole is the slot a text tag
names, so <<sig:Employee>> in the document places a signature for the recipient whose role is
Employee.
POST /api/v1/envelopes/one-off
documents is a list, in the order a signer meets them. They are stacked into one scroll on the
signing screen, and each is sealed on its own with its own certificate of completion. As on the
template path, a Word .docx is accepted and converted to PDF on our side, and its tags survive
the render.
title is required here: this API does not name a one-off for you. On the upload screen, where
the name starts as a suggestion made from the file’s name, a one-off left with that suggestion
takes the title printed at the top of its first page instead, by the same rules as a template’s
name above: a letterhead or a heading repeated on later pages is not taken,
and a name the sender typed is never replaced. Choosing the name sends nothing to the AI.
What a one-off refuses
- ⚠️ An envelope with no tags in any of its documents is refused,
template_has_no_fields, and nothing is created. A one-off has no detection and no editor behind it — this API has no operation that places a field later — so an envelope with no field could never become signable. The count is over the whole request, not per document: an annexure with no tags is accepted as long as another document in the same request places a field. - ⚠️ Roles are declared inline, and only there. A tag naming a role no recipient holds is
refused with the tag, its page and the roles the request does declare; so is a
subject(...)tag, since a one-off made through this API declares no subjects.signerNcounts the entries inrecipients, copies included. - One signing role, one person. Two recipients on the same role that is not a copy are
refused
recipient_role_duplicated: both would answer every box on that role. Give each person a role of their own and tag each role where that person signs. - Every role with a field needs somebody who can fill it. A tag for a role whose only
recipient is a
ccis refusedrecipient_role_missing, because a copy is never asked to sign. - There is no
valuesarray, so you prefill nothing and lock nothing.
job_title and company
are what seed the second row.
Every refusal
POST /api/v1/envelopes/one-off declares,
with what each one means, as the reference publishes them:
Discarding a draft
DELETE /api/v1/envelopes/{envelopeId} throws away a draft
that will not be sent — from a template, a one-off, or a batch row — exactly as the dashboard’s
Discard button does. The draft, its recipients, its placed fields and the values filled in are
deleted, and the answer has no body. It cannot be undone, and no webhook fires.
- Only a
draft. An envelope that has gone out is refusedenvelope_not_draftand left as it is. To withdraw one that is still out for signature, void it instead; a finished envelope stays on the record. - Discarding it again is
not_found, and so is an id that belongs to another organisation. The request takes noIdempotency-Key, because repeating it cannot delete anything twice: a retry after a timeout that answersnot_foundmeans the first attempt worked. - A
vsk_test_key discards only a draft a test key created. A draft made in the dashboard or with a live key is refusedtest_key_cannot_discard. - Creating the same envelope again with the
Idempotency-Keythat made the discarded draft makes a new draft rather than returning the deleted one.
Retrying safely
Every request on this page requires anIdempotency-Key — one key per request you intend, reused
only to retry that same request. A retry with the same key and the same body returns the first
answer and creates nothing; a batch replay returns the same batch, failed rows and all. A different
body under a used key is refused idempotency_key_reused. Reordering recipients is a different
body, because that order is the order recipients are listed in and, without step, can be the order
they are asked (see Steps). How long a key is remembered, and what to do past
it, is in Retrying a request safely.
A template role can be optional, so a request may leave its recipient out. See
Roles that can be left out.