Skip to main content
There are two ways to get a document in front of the people who sign it, and the question that chooses between them is whether you will send this document again.
  • 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/templates creates it, and every envelope after that is POST /api/v1/envelopes with its template_id and the people this copy is for — or POST /api/v1/envelopes/batches for 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-off takes the document and the people in a single request and creates no template: the envelope’s template_id comes back null.
⚠️ Do not register a template per send. A template stays in your library and in 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
It leaves behind:
  • 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
The envelope uses the template’s documents as they are: nothing is uploaded again. 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, each conditional:
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
A 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 phone field of exactly 10 boxes, a leading +27 or 0027 followed by nine digits becomes 0 and those nine digits.
  • For example, on a 10-box phone field, 082 801 4085 is checked and sealed as 0828014085, and +27 82 801 4085 as 0828014085.
Other fields drawn as printed boxes, such as a date or an amount, keep every character you send. A value that is still longer than its boxes is not shortened to fit. On a field drawn in one set of boxes, a locked one is refused at the send, and otherwise the signer is asked to correct it before they can finish; a field drawn in several refuses it when you create the envelope (below).

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. In GET /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: 3 and one continuation of cells: 7 takes one value at its one address. Sent as 082 801 4085 to a phone field, it is stored as 0828014085 and drawn 082 then 8014085, filling each set of boxes from the left. validate-values counts it as one field.
  • Longer than its boxes: refused cannot_be_drawn at create, and reported cannot_be_drawn by validate-values, and never shortened to fit. For 082 801 4085 1 the 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’s amount 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 amount is { "fraction_digits": 2 }, with cells: 8 and one continuation of cells: 2, takes one decimal value. 12 345,67 is stored as 12345.67 and drawn 12345 then 67; 12345.67 is stored as 12345.67 and drawn 12345 then 67; R 8 500 is stored as 8500.00 and drawn 8500 then 00. 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. For 123456789 the 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.500 the 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, as 12 500,00 or 12,500.00.

Checking values before you send

Create refuses the first values 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
The answer is a 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 in attachments 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
An attachment’s fields come from its own text tags, as a one-off’s do, and nothing is detected on it. A tag names a role by the 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. values fill 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 refused value_address_unknown.
  • No subject(...) tags. An attachment declares no subjects, so a tag naming one is refused invalid_request, with the tag and its page.
  • Not in a batch. A batch row has no attachments.
The template still needs fields of its own. Attachments go beside a template, not in place of one, so a template with no fields is refused 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 in documents 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
The order is what each recipient meets: the order of their pages, the “Document 1 of 3” above each page, the order their fields are walked in, the order of the attachments on the completion email, and the “document 1 of 3” on each certificate of completion. 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 in documents 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
A template document you do not name at all is refused rather than left out, so a document is never dropped without your saying so. Only a template document can be left out this way: to leave out an attachment, do not send it. If you leave out the template’s first document, 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.
The message names the document and the reason, and says what would let it go where something would. Nothing is created.

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 — and send, 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’s role 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. signerN counts the entries in recipients, 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 cc is refused recipient_role_missing, because a copy is never asked to sign.
  • There is no values array, so you prefill nothing and lock nothing.
That is not the same as the signer typing every box. On either path, some tags arrive already filled, and the first row is never asked at all. A recipient’s 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 refused envelope_not_draft and 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 no Idempotency-Key, because repeating it cannot delete anything twice: a retry after a timeout that answers not_found means 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 refused test_key_cannot_discard.
  • Creating the same envelope again with the Idempotency-Key that made the discarded draft makes a new draft rather than returning the deleted one.

Retrying safely

Every request on this page requires an Idempotency-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.