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, does the same detection, sends the same envelope, and creates no template: template_id comes back null.

⚠️ 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(employee_id)>>       the api name a value addresses

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. 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 comb, a per-character input shape, 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.