Templates

In Legaldoc, a template isn’t a separate resource: it’s an envelope with type: "TEMPLATE". It’s created and given recipients and fields with the same endpoints as any envelope (see Integration Guide), but it isn’t distributed or signed: the template’s recipients are placeholders. To get something signable, generate a DOCUMENT envelope from it with POST /envelope/use; that document is what gets distributed and signed.

Create a document from a template

POST /envelope/use

Takes a template’s envelopeId and creates a new DOCUMENT-type envelope from it.

Field	Type	Required	Description
envelopeId	string	Yes	ID of the template to use.
recipients	array	Yes	Real recipients, mapped by id to the recipients defined in the template.
distributeDocument	boolean	No	If true, distributes the document immediately after creating it.
externalId	string	No	Your own identifier for the generated document.
folderId	string	No	Folder to create the document in.
customDocumentData	array	No	Replaces one or more of the template’s PDFs with new files (see below).
prefillFields	array	No	Prefills values into template fields (see below).

Each recipient in recipients requires id (the recipient’s ID in the template) and email; name and signingOrder are optional and override what’s defined in the template.

See the full spec in the API Reference.

Replacing the template’s PDF

If you need to generate the PDF dynamically but reuse the recipients and fields already configured in the template, use customDocumentData to map each of the template’s files (by its envelopeItemId) to a new file:

{
  "envelopeId": "envelope_template_123",
  "recipients": [{ "id": 1, "email": "[email protected]", "name": "Real Name" }],
  "customDocumentData": [
    { "identifier": "envelope_item_xyz", "envelopeItemId": "envelope_item_xyz" }
  ]
}

The replacement PDF must keep the same page layout as the original — the template’s fields are positioned according to the original coordinates, and a layout change misaligns them.

Prefilling field values

prefillFields lets you fill in template fields before distributing — useful when you already know the value (for example, pulling it from your own system) and don’t want to ask the signer for it:

{
  "envelopeId": "envelope_template_123",
  "recipients": [{ "id": 1, "email": "[email protected]" }],
  "prefillFields": [
    { "id": 101, "type": "text", "value": "Senior Software Engineer" },
    { "id": 102, "type": "number", "value": "120000" },
    { "id": 103, "type": "checkbox", "value": ["health", "life-insurance"] }
  ]
}

Each prefillField’s type must match the actual type of the field in the template.

---

See also

• Envelopes — listing templates by filtering on type=TEMPLATE
• Fields — field types and their options
• Integration Guide — the general creation and signing flow