Skip to main content
PUT
Decide one person: a subject for their details, a signing role, both, or a witness.

Authorizations

Authorization
string
header
required

Authorization: Bearer vsk_live_…. Chosen over a bespoke X-API-KEY header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see x-scopes at the root of this document and x-required-scope on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for oauth2 and openIdConnect and requires it to be empty for an http scheme.

Headers

If-Match
string
required

The ETag of the template you read. ⚠️ REQUIRED: without it, or with *, the answer is precondition_required; a stale one is template_changed, with the current ETag. An entity tag, quoted.

Path Parameters

templateId
string<uuid>
required

The template’s id, as returned by the list endpoint. A template id.

Example:

"01960000-0000-4000-8000-0000000007e1"

personId
string
required

The person’s id, from GET /api/v1/templates/{templateId}/people or a run’s proposals.people. A person id: 32 lower-case hexadecimal digits.

Pattern: ^[0-9a-f]{32}$

Body

application/json

The decision.

The decision.

decision
enum<string>
required

subject: their details get a subject, and they sign nothing. signer: a signing role for their signature, initials and signing date. both: a subject and a signing role. mandate_signed: a signing role marked as one your organisation normally pre-signs under a standing authorisation (information only: a send applies a mandate only when it names one). witness: a witness role.

Available options:
subject,
signer,
both,
mandate_signed,
witness
subject_key
string

The subject’s key, for subject, both and witness.

Required string length: 1 - 100
subject_label
string

The subject’s name.

Required string length: 1 - 200
presence
enum<string>

Whether the person is always on the form.

Available options:
required,
conditional
role_name
string

The role’s name, for every decision but subject.

Required string length: 1 - 200
data_filled_by
enum<string>

For both: who fills the person’s details. current (the default) leaves them with whoever fills them now; own gives them to the person’s own role.

Available options:
current,
own

Response

The template as it now stands, with its new ETag.

The template, in full.

id
string<uuid>
required

The template’s id. A bare uuid, no prefix.

name
string
required

What the sender called it.

created_at
string<date-time>
required

ISO 8601, UTC. Also the order this list is in — newest first.

warnings
object[]
required

What the template’s upload warned about, kept with the template: on the create response and on every read, so a template somebody uploaded on the dashboard says here what its upload said. Empty when there was nothing to say, and always present. A retry of the create’s Idempotency-Key answers with the same list.

Maximum array length: 10
documents
object[]
required

The pack, in the order it is stacked.

pages
object[]
required

⚠️ THE DENOMINATOR FOR EVERY Field.rect, and a client doing field matching cannot skip it: a rectangle of fractions is dimensionless without the page it is a fraction of. Join on (document_id, page), the same pair fields is joined by.

Every page of every document of the pack, in the pack’s order and then by page number — the order a signer scrolls.

roles
object[]
required

The signing roles, in routing order.

subjects
object[]
required

The people whose data this template collects.

questions
object[]
required

The tickbox questions and how many answers each takes.

fields
object[]
required

⚠️ A FLAT LIST, NOT A MAP KEYED BY ADDRESS. Several fields sharing one (subject, data_key) pair is NORMAL — real forms ask for an ID number on the application and again on the declaration, and initials in the footer of all nine pages. A value supplied for an address means it for every box that asks.

coverage
object
required

How much of the template your integration can address, counted by the same code as the editor’s coverage line, so the two always agree. Part of the body, so the template’s ETag changes when it does.