Entity Ids and LookupIds

Suggest Edits

All Entities can be identified in three different ways:

  • Entity Id
  • Name
  • External Id (optional)

This means that all these fields must have system-wide unique values.

Entity Id

This is the internal Identifier for the Entity, used across all tables in the database. This value can't be changed.
Entity Ids are 15 characters long, starting with a lowercase letter, followed by up to 14 lowercase letters, digits and underscores. The Entity Id cannot start or end with an underscore (this is reserved for system Entities).
The Entity Id is normally generated automatically when a new Entities is created, however it is possible to override this by specifying the Entity Id when creating the Entity. The benefit of being able to specify the value is that it's easier to reference the Entity in custom SQL queries.

Name

All Entities must have a unique name, and the name must be specified when the draft Entity is created.
The names are visible in the Loyalty API, but their primary usage is within the NEON Portal.

Names can be up to 100 characters long, consisting of upper and lowercase letters, digits and underscore.
Every name must have at least one uppercase letter. This is to distinguish them from Internal Ids.

Note that whilst Entities can be renamed at any time, changing the name may cause scripts or external programs to fail if they rely on looking up the Entity by its name. It's therefore not recommended to change the name after the Entity has been published.

Names are optionally prefixed with an @ sign to make it clear that they are names rather than Ids. The @ sign is completely optional.

External Id

External Ids are optional. If specified, they must be unique across the system.
The purpose of External Ids is to simplify integration with other systems by offering an alternative key which can match the key in the external system.

External Ids can be up to 100 characters long, consisting of upper and lowercase characters, digits and underscore.

External Ids can be set, cleared or changed at any time, but changing it may cause external programs to fail if they rely on the External Id to have a specific value. It is therefore not recommended not to change the External Id after the Entity has been published.

Note that when looking up an Entity by External Id, it must be prefixed by $ (the dollar sign). This is to distinguish it from the Internal Id or the name. The dollar sign is not be part of the External Id, just specified in front of it when searching for it (see Lookup Id)

Lookup Id

All API endpoints which require an Entity accept an entityLookupId as part of the url.

Note: If the documentation says entityLookupId, you can pass in the lookupId of any type of entity, but if it say offerLookupId, listLookupId, formLookupId etc then the identifier must belong to an Entity of that type.

The LookupId value can be any of:

  • The Entity's Internal Id (a lowercase string of up to 15 characters)
  • The Entity's Name (which is in mixed case), optionally prefixed by the @ sign
  • The Entity's External Id, assuming the Entity has been given an External Id. Note that a dollar sign needs to be specified in-front of the External Id.

If for example a List has a name called "HighScores", has been given a generated internalId of "abc123def456", and has been assigned an External Id of "list15", then it's members can be accessed in any of the following ways:

  • GET /lists/HighScores/members
  • GET /lists/abc123def456/members
  • GET /lists/$list15/members

Updated 9 months ago