Templates

List your E-Signing templates and read a single template's roles — the starting point for sending an envelope from the API.

Templates are the reusable documents your team has already set up in the app, with their fields and signer roles laid out. To send an envelope through the API you start from one of these, so the two read endpoints here are usually the first calls after authentication.

Both require the templates:read scope, and a key only ever sees the templates its owner can see in the app.

List templates

Endpoint

GET https://api2.bunnydoc.com/v1/templates

Query parameters

Parameter	Type	Description
`page`	integer	Page number, from `1`. Default `1`.
`per_page`	integer	Results per page, `1`–`100`. Default `25`.
`search`	string	Optional. Filter by template name, up to 200 characters.

Example request

List templates

curl "https://api2.bunnydoc.com/v1/templates?per_page=25&search=nda" \
  -H "Authorization: Bearer <access_token>"

List templates

GET /v1/templates?per_page=25&search=nda HTTP/1.1
Host: api2.bunnydoc.com
Authorization: Bearer <access_token>

Response

200 OK

{
  "data": [
    {
      "id": "018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "Mutual NDA",
      "description": "Standard two-way non-disclosure agreement",
      "file_count": 1,
      "role_count": 2,
      "created_at": "2026-06-01T09:30:00.000Z",
      "updated_at": "2026-07-10T14:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Field	Type	Description
`id`	string	The template id — pass it to `POST /v1/envelopes/from-template`.
`name`	string	Template name.
`description`	string \| null	Optional description.
`file_count`	integer	Number of documents in the template.
`role_count`	integer	Number of signer roles.
`created_at` / `updated_at`	string	ISO 8601 timestamps.

Get a template

Returns one template including its roles. Call this before sending — the roles array tells you exactly which role names to supply, and which ones are locked.

Endpoint

GET https://api2.bunnydoc.com/v1/templates/{id}

Example request

Get one template

curl https://api2.bunnydoc.com/v1/templates/018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer <access_token>"

Get one template

GET /v1/templates/018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d HTTP/1.1
Host: api2.bunnydoc.com
Authorization: Bearer <access_token>

Response

200 OK

{
  "id": "018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Mutual NDA",
  "description": "Standard two-way non-disclosure agreement",
  "file_count": 1,
  "role_count": 2,
  "created_at": "2026-06-01T09:30:00.000Z",
  "updated_at": "2026-07-10T14:12:00.000Z",
  "roles": [
    {
      "role": "Client",
      "recipient_type": "need-to-sign",
      "signing_order": 1,
      "locked": false
    },
    {
      "role": "Account manager",
      "recipient_type": "need-to-sign",
      "signing_order": 2,
      "locked": true,
      "name": "Dana Lee",
      "email": "dana@yourco.com"
    }
  ],
  "fields": [
    {
      "id": "018f2c3d-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
      "role": "Client",
      "file_id": "018f2c3d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "page_number": 1,
      "type": "signature",
      "label": "Client signature",
      "required": true,
      "locked": false,
      "position": { "x": 72, "y": 540, "width": 180, "height": 48 }
    }
  ],
  "files": [
    { "file_id": "018f2c3d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "order": 1, "excluded_pages": [] }
  ],
  "settings": {
    "signing_order": true,
    "email_subject": "Please sign: Mutual NDA",
    "email_message": "<p>Please review and sign the enclosed NDA.</p>",
    "expiry_date": "2026-12-31T23:59:59.000Z",
    "timezone": "Australia/Sydney",
    "signed_date_format": "DD/MM/YYYY",
    "envelope_date_time_format": "DD/MM/YYYY HH:mm",
    "brand_id": "018f2c3d-9c0d-7e1f-8a2b-3c4d5e6f7a8b"
  }
}

`roles`

Role field	Type	Description
`role`	string	The role name. Supply this in `recipients[].role` when you send.
`recipient_type`	string	How the recipient participates, e.g. `need-to-sign`, `receives-a-copy`.
`signing_order`	integer	The order this role signs in.
`locked`	boolean	If `true`, the name and email are fixed on the template — omit this role from your send request.
`name` / `email`	string \| null	Present only for locked roles — the fixed recipient.

Locked roles can't be reassigned

A locked role already has a person attached (or it's the template's own sender). Sending a recipient for a locked role is rejected with unknown_signer_role. Only supply recipients for roles where locked is false.

`fields`

Every field placed on the template, so you can show your users what the document will ask for before they send it.

Field	Type	Description
`id`	string \| null	The field's id.
`role`	string	The signer role this field belongs to — join it to `roles[].role`.
`file_id`	string	Which of the template's `files` the field sits on.
`page_number`	integer	1-based page within that file.
`type`	string	Field kind — `signature`, `initials`, `text`, `date`, `date_signed`, `checkbox`, `radio`, `dropdown`, `multi_select`, `email`, `phone`, `number`, `amount`, `address`, `company`, `job_title`, `title`, `full_name`, `first_name`, `last_name`, `masked_text`, `image`, or `file_attachment`.
`label`	string \| null	The field's label.
`required`	boolean	Whether a signer must complete it.
`locked`	boolean	Whether the value is fixed on the template.
`position`	object	`x`, `y`, `width`, `height` on the page.

Prepared values are not exposed

Field geometry is readable; the sender's prepared values are not. A sender-side value can be a signature reference or sensitive prefilled text, so it never leaves the app through this API.

`files`

Metadata only, in document order.

Field	Type	Description
`file_id`	string	The file's id. Use it to join `fields[].file_id`.
`order`	integer	Position in the document set.
`excluded_pages`	integer[]	Pages dropped from the template, if any.

Template files are not downloadable

There is no download URL and no storage path here, and no endpoint to fetch a template's document. This tells you which files are attached and in what order — nothing more. The finished, signed PDF is delivered through the envelope.document_ready webhook.

`settings`

What the envelope will inherit when you send from this template. Reading it is the reliable way to know what you don't need to pass.

Field	Type	Description
`signing_order`	boolean	Whether recipients sign sequentially.
`email_subject`	string \| null	Default subject. Override per send with `email_subject`.
`email_message`	string \| null	Default message, as safe HTML. Override per send with `email_message`.
`expiry_date`	string \| null	ISO 8601. Inherited by the envelope; not settable from the API.
`timezone`	string	IANA zone used for dates in the document and emails.
`signed_date_format`	string	How signed dates are rendered in the PDF.
`envelope_date_time_format`	string	How date-times are rendered.
`brand_id`	string \| null	The brand applied to the emails and signing page.

Errors

Status	`error.code`	When it happens
`404`	`template_not_found`	No template with that id exists in your company.

Next step

Send from a template

Assign recipients to the unlocked roles and send the envelope.

Send from a template

On this page