Key Value Pairs

Whilst we strive in our APIs to make as many data points as possible into first-class citizens, i.e. they have their own dedicated named attribute, the nature of the data we hold and process means that it is impossible to do this in any sane fashion.

To that end, many of our structures contain an additional array of extra data made up of loosely typed key-value pairs (KVPs).

We call them loosely typed as all values are stored and represented as strings, but you can define a type in order to provide some hints as to how the data may be treated. Unless specifically stated though, there is no rigorous enforcement of this, so do not expect it.

KVP Types

KVP Types are used to describe the contents of the KVP data (full list below).

🚧

There is NO enforcement of types on values of any kind, ultimately, they will be treated as strings.

However, they do serve as a guide for developers as to the content.

The general and raw types are pretty much what they are defined as. They're used to hold generic or raw/binary data.

All raw.* fields will be Base64 encoded so as to not interfere with JSON structuring. These are useful for returning/storing larger quantities of data that don't necessarily require processing now or may be useful to a calling client.

The id. and pii. are used to indicate that this is data that can potentially be used to create new document objects, or entities. They should also be treated with the utmost care and attention when it comes to securing them too.

id.external can be used to capture an object's ID on an external service, and can potentially be searchable in the index.

📘

Note

The id.external is different from a result.id.

🚧

External IDs

all id.external KVPs that are attached to an entity’s extraData KVP array will also be indexed and can be used to search for the entity using the /search API. More on this later.

Defunct is used to mark an existing KVP deleted when the value must be retained, for example, for audit purposes.

result.* are used to capture response codes and transaction IDs from external services.

error. types can be used when processing a document that returns an error but doesn't necessarily require a full-blown error response.

transient.* types will be accepted for processing, but only on the initial call to the service.

📘

Note

Transient types are not saved and are only active for the life of an individual call. They're good for passing sensitive data that is used once and once only.

Full List of Valid kvpTypes

• defunct
• general.string
• general.integer
• general.float
• general.bool
• general.date
• general.datetime
• transient.string
• transient.integer
• raw.json.base64
• raw.xml.base64
• raw.base64
• error.code
• error.message
• result.code
• result.id
• id.external
• id.number.primary
• id.number.additional
• id.msisdn
• id.email
• id.device
• pii.name.full
• pii.name.familyname
• pii.name.givenname
• pii.name.middlename
• pii.gender
• pii.address.longform
• pii.address.street1
• pii.address.street2
• pii.address.postalcode
• pii.address.town
• pii.address.suburb
• pii.address.region
• pii.address.state
• pii.address.country
• pii.dob