Naming a template's fields

​

How much of a template you can address

​

Reading a template only when it has changed

​

Renaming fields

{
  "fields": [
    { "id": "6c1e…", "data_key": "member.surname", "label": "Surname" },
    { "id": "9a40…", "data_key": "member.id_number", "subject": "spouse" },
    { "id": "b2d7…", "data_key": null }
  ],
  "questions": [{ "id": "4b0f…", "label": "Gender" }]
}

• Names only. Nothing else about a field can change here: not where it is, its type, who fills it, its options, its rules or its conditions. Any other property is refused. A name is not inert, though: a field’s data_key decides which value an envelope can be created with in that box, and its subject whether the box is shown when that person is not on the envelope. That holds for a required field too: moving one to a subject who may be absent makes it optional whenever they are, exactly as the same change in the editor does.
• A dedicated scope. The key must name templates:name. A full-access key does not hold it; choose it by name when you create the key.
• Live keys only. A template has no environment: the same template serves test and live sends. A rename made with a vsk_test_ key would change what live envelopes contain, so it is refused with test_key_cannot_edit_templates. A key whose creator has left your organisation is refused with api_key_owner_removed.
• Against the version you read. Send the template’s ETag as If-Match. Without it, or with *, the answer is precondition_required. If the template has changed since, the answer is template_changed with the current ETag, and nothing is renamed: read the template again and look at what changed before you retry. A retry of a rename that succeeded, whose answer you lost, is answered as a success: every name it asks for is already there.
• All or nothing. At most 500 fields and 200 questions in one request. Every change applies, or none does.
• Only envelopes created afterwards use the new names. An envelope already created, sent or not, keeps the names it was created with, and the values it holds stay where they were.
• Recorded. Every change is kept in the template’s naming record with the key that made it, and each request that changes a name appears in your organisation’s activity. A rename in the editor is recorded the same way.

​

What a name may be

• The namespaces person, employer, employment, residential_address, postal_address, bank belong to the core vocabulary, a shared list of keys that is not published yet. No key in them can be set until it is.
• A namespace may not be a subject key, either one the template declares or one of the standard ones, spouse, dependant_<n>, beneficiary_<n>, witness_<n>, where n counts from one. The subject is never part of the key: set subject instead.
• A key a field already has may be kept, whatever it says. data_key: null removes it.
• A box in a question takes no key or subject of its own; name it with label. Option values, and a question’s own key, come with the core vocabulary.
• A rename may not make a collision, as coverage counts them. A collision the template already had does not stop you renaming other fields, which is how you fix it.
• A label is at most 200 characters, and not blank; null removes it. It may be changed on any field, a signature or a question’s box included, as in the editor. A label is Vumasign’s name for the box; it does not change the printed document, which is what decides what a tick or a signature means. A subject must be declared on the template.
• ⚠️ A subject never changes here on a field nobody may prefill: a signature, initials, an attachment or a field the product stamps. On those fields the subject decides whether somebody must sign or complete them, and a key must not be able to change that unseen. The request is refused with value_not_writable. This is deliberately stricter than the editor, which allows it.

​

Sending against the template you checked