Skip to main content
POST
Create a template

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-workspace-id
string

One of the workspaces the key was issued for, as returned by GET /api/v1/workspaces. Required on a key that acts for members. On any other key it is optional and omitting it acts in the key's default workspace. Any id outside the key's workspaces is rejected with 401.

x-act-as
string

Required on a key that acts for members, refused on any other key. Names the member the call runs as, as key=value: email=jane@acme.com, employee_id=E-1001, scim_external_id=… or a custom identifier. Keys are lowercase and matched case-insensitively. The call fails with 403 when no active member of the workspace matches.

Body

application/json
name
string
required

The template's name.

Minimum string length: 1
Example:

"Employment agreement"

roles
object[]
required

The named slots recipients fill at launch. At least one, at most 100.

Required array length: 1 - 100 elements
description
string

Free-text description of what the template is for.

Example:

"Standard individual employment agreement for new hires."

status
enum<string>

Initial lifecycle state. Defaults to DRAFT. ACTIVE also stamps the publish time; ARCHIVED stamps the archive time. ACTIVE is refused with 400 when signingMode is WORKFLOW and the questions break a workflow rule; save as DRAFT to keep them and read the problems from warnings.

Available options:
DRAFT,
ACTIVE,
ARCHIVED
Example:

"DRAFT"

tags
string[]

Organisation tags to put on the template. A tag that does not exist yet is created.

Example:
reminderIntervalDays
integer

Days between automatic reminders to each recipient who hasn't finished, counted from their invitation. Null or absent sends none.

Required range: x >= 1
Example:

3

expirationDays
integer

Days the package stays open for signing, counted from when it is sent. Null or absent means it never expires.

Required range: x >= 1
Example:

30

expiryWarningDays
integer

Days before expiry at which recipients who haven't finished are warned. MUST be fewer than expirationDays.

Required range: x >= 1
Example:

5

emailSubject
string | null

Subject of the invitation email. {{key}} placeholders are filled from the package's merge field values.

Example:

"Your employment agreement with Ashcombe Advisory Limited"

emailMessage
string | null

Body of the invitation email. {{key}} placeholders are filled from the package's merge field values.

Example:

"Kia ora {{employee_name}}, please review and sign your agreement."

signingMode
enum<string>

How recipients are walked through signing. PARALLEL (the default) invites every role at once; SEQUENTIAL invites one role at a time in order; WORKFLOW follows the template's workflow, asking recipients its questions as they open the package.

Available options:
PARALLEL,
SEQUENTIAL,
WORKFLOW
Example:

"SEQUENTIAL"

brandColor
string | null

Accent colour for the signing experience and emails, as a six-digit hex code. Needs a plan with custom branding, otherwise 402. Null clears it.

Pattern: ^#[0-9a-fA-F]{6}$
Example:

"#1a2b3c"

metadata
any | null

Not accepted. A template's default custom field values are set in the app; sending this is refused with 400 and nothing is saved.

questions
object[]

Conditional questions the sender answers at launch. Each answer's actions decide which documents the package includes. Questions reference each other by position in this array.

mergeFields
object[]

Values the template collects and merges into its documents and emails. Blank at launch means the field's default.

Response

Success

data
object
required