Standard Fields

There are many standard record and payload fields and names which are used across the API. This page describes them and what they are used for.

*_id (fields ending with _id)

These are NEON's identifier fields, essentially primary and foreign keys in the database. They are case sensitive and up to 15 characters long. In most cases these are generated automatically (such as member_id), but they can in some cases be specified (such as Entities).

_Id fields can never be modified.

external_id (and external_*_id)

This is an optional external identifier for the Member, Entity or record. In database language it's an an alternative key. It can be set or left blank, but if set it has to be unique. It is always up to 50 characters, unique and case sensitive. The purpose is to simplify integration with surrounding systems by providing an alternative way to look up the Member or record.

When used for querying it has to be prefixed with $ (the dollar sign) to differentiate it from the NEON id.

The external_id field can be added, removed or updated, however doing so may break integrations which depend on them.

created

The timestamp when a database record was first created, in the format YYYY-MM-DDTHH:MI:SS.millisZ.

The field is set automatically upon creation (millisecond precision) and can't be modified. It is always returned in UTC (with timezone Z)

When querying, the 'create'd field will always return a value.

updated

The timestamp for when a database record was last modified, in the format YYYY-MM-DDTHH:MI:SS.millisZ.

The field is set automatically when a record is modified (millisecond precision). It is always returned in UTC (with timezone Z).

Note that in certain situations the NEON optimizer may decide to update or not update a record, in which case this updated field may or may not be updated when expected. A simple example of such an optimization would be if you increase a Counter List by 0. But doing so as part of a bulk operation or a SET action may still cause the field to be updated to the same value.

When querying, the 'updated' field will always return a value.

type (and subType)

Used by NEON's business logic to distinguish by different types of records. This is always a mandatory 20 character field containing one of NEON's recognised types, and always in uppercase.

The type field can never be updated, since business logic and behaviour is different depending on the type. An example is the List type, which can be one of TAG, SUBSCRIPTION, DATA, SQL and TARGET.

When querying, the 'type' field will always return a value. If the functionality and record supports subTypes then it will always return a value.

state (and *_state)

The state field (and fields ending with _state) is used by NEON's business logic to understand what state a record is in, to be able to apply the correct business logic.

States are up to 20 characters long and always in uppercase.

The state can sometimes be updated by the calling application (for example installing an Entity or activating a Member), but sometimes it's controlled entirely by the business logic (such as when you claim a code). In either case, a changed state affect aspects of NEON's business logic.

When querying, the state field will always return a value.

data

The data field is optional, and the value can be added, updated or removed. The data field holds a Json object with additional attributes to be saved together with a record. This Json is saved and is returned whenever the record is queried, and the attributes can in most cases be filtered by in queries, using the qry=data.attribute format.

NEON does not have a view on what's saved in the data attribute other than:

It has to be valid Json
It needs to be a Json object (a set of attributes), not a Json array
It's expected to hold simple key value pairs, so whilst deeper Json structure levels are allowed, they can't be used in filtering or set by triggers.

dimensions

Holds the passed in dimensions (the dim POST parameter) from when the record was first created. It is a way of tagging the record on creation, and is returned whenever the record is queried.

A record's Dimensions can't be modified, so setting different dimensions in the dim POST parameter when updating an existing record won't have any effect on the stored Dimensions.

When querying a record, it's Dimensions are always returned as a kay-value Json structure.

The Dimensions play an important part in NEON and the Dimension explorer, and it's important to always pass in accurate and comprehensive dimensions when saving new records.