The core vocabulary

A template’s keys come in three kinds. Core keys are a vocabulary Vumasign publishes: people, South African ID and passport, contact details, addresses, employment, employers and banking. Map your data to them once and every template named with them is addressed the same way. Organisation keys are every other key your own templates use, in the naming grammar (namespace.attribute, see Naming fields). Legacy keys are any other spelling a template still carries from before; they work as addresses and are names to replace.

Reading it

GET /api/v1/vocabulary answers with both lists, for a key holding templates:read, test or live. It carries an ETag, and If-None-Match answers with no body while nothing has changed.

core is version 1.0.0, 50 keys, with the subject keys the core standardises: spouse, dependant_<n>, beneficiary_<n>, witness_<n>, where n counts from one.
organisation lists the keys your organisation’s live templates use and the core does not: each key’s type (a field type, or choice for a question), how many templates use it, up to 5 labels printed beside the boxes that carry it, and for a question the option values in use. It is derived from your templates whenever you read it, archived templates left out, and it never lists another organisation’s keys.

How the core changes

The core uses semantic versioning. A minor version adds keys, options or synonyms. A key or an option value is never renamed or removed; at most it is deprecated, with the key that replaces it. A template named with a core key never needs renaming because the core moved.

Using a core key

person.*, the two address namespaces and employment.* describe a person. With subject null they are the form’s principal person, the one the signer answers for; with subject set to spouse, the spouse’s. employer.* and bank.* describe the organisation and take no subject.
A key in a core namespace (person, employer, employment, residential_address, postal_address, bank) must be a core key: a key such as person.sa_idnumber is refused with the core key it most likely means.
A choice key is a question (or a dropdown), and its options are fixed: a question named with person.gender offers male, female, and its boxes take those option values.
A core key is refused on a field of a kind it does not describe: a date key on a tickbox, or a choice key on a text box.

The keys

`person.*`

Subject-capable: with subject null it is the form’s principal person; with a subject, that person’s.

Key	Label	Type	Options	What belongs here
`person.title`	Title	`choice`	`mr`, `mrs`, `ms`, `miss`, `dr`, `prof`	The form of address printed before a name. Not a job title (that is `employment.job_title`).
`person.first_names`	First names	`text`		Every given name, as on the identity document. Not initials, and not a preferred or known-as name.
`person.last_name`	Surname	`text`		The family name, as on the identity document. Not a maiden name unless the form asks for the current surname.
`person.initials`	Initials	`text`		The initials of the first names, for example `J.M.` Not a signature initial.
`person.sa_id_number`	South African ID number	`sa_id`		The 13-digit South African identity number. Not a passport number.
`person.passport_number`	Passport number	`text`		The number of a passport, for a person without a South African ID number. Not the ID number.
`person.passport_country`	Passport country	`text`		The country that issued the passport. Not the country of residence.
`person.date_of_birth`	Date of birth	`date`		The day the person was born. Not an age.
`person.gender`	Gender	`choice`	`male`, `female`	The gender the form asks for, as the two options printed on most South African forms.
`person.marital_status`	Marital status	`choice`	`single`, `married`, `divorced`, `widowed`, `life_partner`	Whether the person is married, and how. Not the spouse’s details.
`person.relationship_to_principal`	Relationship to the principal	`choice`	`spouse`, `child`, `parent`, `sibling`, `other`	How a subject (a spouse, dependant or beneficiary) is related to the form’s principal person.
`person.email`	Email address	`email`		The person’s own email address. Not an employer’s contact address (that is `employer.contact_email`).
`person.mobile_number`	Mobile number	`phone`		The person’s cellphone number.
`person.home_phone`	Home telephone	`phone`		A landline at home. Not a cellphone.
`person.work_phone`	Work telephone	`phone`		A telephone number at work. Not the employer’s switchboard on an employer section.
`person.income_tax_number`	Income tax number	`text`		The person’s SARS income tax reference number. Not a company’s PAYE reference.
`person.home_language`	Home language	`text`		The language the person speaks at home.
`person.occupation`	Occupation	`text`		What the person does for a living, in general terms. Not a job title at one employer.

`residential_address.*`

Subject-capable: with subject null it is the form’s principal person; with a subject, that person’s.

Key	Label	Type	Options	What belongs here
`residential_address.line_1`	Residential address line 1	`text`		The first line of the residential address: a street number and name, a unit, or a box number.
`residential_address.line_2`	Residential address line 2	`text`		The second line of the residential address, when the form prints one.
`residential_address.suburb`	Suburb	`text`		The suburb of the residential address. Not the city.
`residential_address.city`	City or town	`text`		The city or town of the residential address.
`residential_address.postal_code`	Postal code	`text`		The four-digit postal code of the residential address.
`residential_address.province`	Province	`choice`	`eastern_cape`, `free_state`, `gauteng`, `kwazulu_natal`, `limpopo`, `mpumalanga`, `north_west`, `northern_cape`, `western_cape`	The South African province of the residential address.
`residential_address.country`	Country	`text`		The country of the residential address.

`postal_address.*`

Subject-capable: with subject null it is the form’s principal person; with a subject, that person’s.

Key	Label	Type	Options	What belongs here
`postal_address.line_1`	Postal address line 1	`text`		The first line of the postal address: a street number and name, a unit, or a box number.
`postal_address.line_2`	Postal address line 2	`text`		The second line of the postal address, when the form prints one.
`postal_address.suburb`	Suburb	`text`		The suburb of the postal address. Not the city.
`postal_address.city`	City or town	`text`		The city or town of the postal address.
`postal_address.postal_code`	Postal code	`text`		The four-digit postal code of the postal address.
`postal_address.province`	Province	`choice`	`eastern_cape`, `free_state`, `gauteng`, `kwazulu_natal`, `limpopo`, `mpumalanga`, `north_west`, `northern_cape`, `western_cape`	The South African province of the postal address.
`postal_address.country`	Country	`text`		The country of the postal address.

`employment.*`

Subject-capable: with subject null it is the form’s principal person; with a subject, that person’s.

Key	Label	Type	What belongs here
`employment.employee_number`	Employee number	`text`	The number the employer knows the person by. Not a payroll or tax reference.
`employment.job_title`	Job title	`text`	The person’s position at their employer. Not their form of address (that is `person.title`).
`employment.start_date`	Employment start date	`date`	The day the person started with this employer.
`employment.monthly_salary`	Monthly salary	`number`	Gross pay a month, in rand. Not an annual figure.
`employment.annual_salary`	Annual salary	`number`	Gross pay a year, in rand. Not a monthly figure.

`employer.*`

Not subject-capable: it describes the organisation, and a subject is refused.

Key	Label	Type	What belongs here
`employer.name`	Employer name	`text`	The employer’s registered name. Not a trading name.
`employer.trading_name`	Trading name	`text`	The name the employer trades under, when it differs from the registered name.
`employer.registration_number`	Company registration number	`text`	The employer’s CIPC registration number. Not a PAYE or VAT reference.
`employer.paye_reference_number`	PAYE reference number	`text`	The employer’s SARS PAYE reference number. Not a person’s income tax number.
`employer.contact_name`	Employer contact person	`text`	The person at the employer a form names as its contact, for example someone in HR.
`employer.contact_email`	Employer contact email	`email`	The employer contact’s email address. Not the employee’s.
`employer.contact_phone`	Employer contact telephone	`phone`	The employer contact’s telephone number. Not the employee’s.

`bank.*`

Not subject-capable: it describes the organisation, and a subject is refused.

Key	Label	Type	Options	What belongs here
`bank.account_holder`	Account holder	`text`		The name the bank account is held in.
`bank.bank_name`	Bank	`text`		The name of the bank.
`bank.branch_code`	Branch code	`text`		The bank’s branch or universal branch code.
`bank.account_number`	Account number	`text`		The bank account number. Not a card number.
`bank.account_type`	Account type	`choice`	`cheque`, `savings`, `transmission`	The kind of bank account.
`bank.debit_order_day`	Debit order day	`number`		The day of the month a debit order runs, from 1 to 31.

Get started

Concepts

Guides

The core vocabulary

Reading it

How the core changes

Using a core key

The keys

`person.*`

`residential_address.*`

`postal_address.*`

`employment.*`

`employer.*`

`bank.*`

​Reading it

​How the core changes

​Using a core key

​The keys

​person.*

​residential_address.*

​postal_address.*

​employment.*

​employer.*

​bank.*

Reading it

How the core changes

Using a core key

The keys

`person.*`

`residential_address.*`

`postal_address.*`

`employment.*`

`employer.*`

`bank.*`