REFERENCE

Templates reference

List published templates, read their roles and fields, and send a document from one.

All documentation

Templates are built in the web app - there is no endpoint that creates one, because placing fields is a visual job. The API reads them and sends from them. For the worked example, see send from a template.

GET/v1/templates

Requires templates:read

Query parameters

Field	Type	Notes
`limit`	integer	1 to 100. Defaults to 20.
`cursor`	string	Pass next_cursor from the previous page.

200 OK

{
  "data": [
    { "id": "tpl_4c8a...", "name": "Mutual NDA", "description": null,
      "status": "PUBLISHED",
      "roles": [ { "role": "Client", "type": "SIGNER" } ],
      "created_at": "2026-08-02T09:14:00.000Z" }
  ],
  "has_more": false,
  "next_cursor": null
}

Published templates only

Drafts are never returned. If a template you expect is missing, publish it in the web app.

GET/v1/templates/{id}

Requires templates:read

This is the call that tells you how to send. roles is who you must supply; fields[].field_key is what you are allowed to prefill.

200 OK

{
  "id": "tpl_4c8a...",
  "name": "Mutual NDA",
  "description": null,
  "status": "PUBLISHED",
  "roles": [
    { "role": "Client",  "type": "SIGNER", "order": 0 },
    { "role": "Counsel", "type": "CC",     "order": 1 }
  ],
  "fields": [
    { "field_key": "contract_value", "type": "TEXT",
      "role": "Client", "required": true, "page": 2 }
  ],
  "created_at": "2026-08-02T09:14:00.000Z"
}

A field with a field_key of null cannot be prefilled - it has no handle to address it by.

POST/v1/templates/{id}/send

Requires templates:write

Body

Field	Type	Notes
`recipients`	object[]required	1 to 20. Each carries role, name, email and optional phone.
`recipients[].role`	stringrequired	Matched case-insensitively against the template roles.
`title`	string	Up to 160 chars. Defaults to the template name.
`field_values`	object	Keyed by field_key, values up to 2000 chars. Unknown keys are ignored silently.
`send`	boolean	Defaults to true. Pass false to leave a draft.
`embed`	object	Opt in to embed_links in the response. Takes expires_in (60-3600, default 900) and an https redirect_url. Requires send: true.

bash

curl https://api.documentesign.com/v1/templates/tpl_4c8a.../send \
  -H "Authorization: Bearer $ESIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "role": "Client", "name": "Sam Rivera", "email": "sam@example.com" }
    ],
    "field_values": { "contract_value": "48,000 USD" }
  }'

Returns the document object, with each recipient's role populated.

Errors

Field	Type	Notes
`template_not_found`	404	Unknown id, or the template belongs to the other mode.
`template_not_published`	409	It exists but is still a draft.
`unknown_role`	400	A role you supplied is not on the template. Carries known_roles.
`missing_roles`	400	A template role was left unassigned. Carries missing_roles.
`duplicate_role`	400	The same role was supplied twice.
`unprefillable_field_type`	400	A field_values key targets a signature, identity or server-stamped field. Lists every offending key.
`invalid_prefill_value`	400	A value does not fit its field type - text in a number, an option not on the dropdown.
`embedding_not_configured`	409	embed was requested but the workspace has no allowed origins.

PreviousFiles reference NextTemplate links reference