What is an identifier?

An identifier is a set of attributes that combine to identify a LUSID entity in some way. See a list of identifiers for all entities.

Most entities have an identifier consisting of a scope and a code. The code must be unique within the scope.

Some entities can have multiple complex identifiers, in which case the entity can be addressed by any, though note an identifier value may be shared between multiple entities:

• Instruments have unique and non-unique market identifiers as well as a globally-unique, system-generated identifier. More information.

• Certain entities have user-defined property identifiers as well as a globally-unique, system-generated identifier. See below.

Understanding user-defined property identifiers

The following types of entity do not have a scope and a code but rather at least one user-defined identifier. Note they can have more than one, perhaps reflecting different contexts in which it operates. Under-the-hood, an identifier is defined as a property type belonging to a particular domain:

• A Person representing a person of interest in your LUSID enviroment.

• A LegalEntity representing an institution.

• An InvestorRecord representing a link between an investor and their investment account.

• A custom entity created to extend LUSID’s data model.

Consider the following example of an investor record retrieved from LUSID that has both ‘external’ and ‘internal’ identifiers:

{
  "lusidInvestorRecordId": "LUID_00003EIC",
  "displayName": "John Doe",
  "description": "An investor record for John Doe",
  "identifiers": {
    "InvestorRecord/Identifiers/External": {
      "key": "InvestorRecord/Identifiers/External",
      "value": {
        "labelValue": "ABCDEFG"
      },
    },
    "InvestorRecord/Identifiers/Internal": {
      "key": "InvestorRecord/Identifiers/Internal",
      "value": {
        "labelValue": "1234567"
      },
    }
  },
  ...
}

This entity has:

• Two user-defined property identifiers. Each consists of:

  • A domain (the first part of the 3-stage property key), in this case InvestorRecord. This is the same for every identifier for this type of entity.

  • An idTypeScope (the second part of the 3-stage property key), in this case Identifiers. This happens to be the same in this example, but it need not be.

  • An idTypeCode (the third part of the 3-stage property key), in this case External and Internal. This must be unique with the idTypeScope.

  • A code (the actual property value), in this case ABCDEFG and 1234567.

• A globally-unique, system-generated lusidInvestorRecordId of LUID_00003EIC that is guaranteed to be unique and never change. This is identical in concept and structure to an instrument's LUID.

Property types for user-defined property identifiers must exist before entities can be created. In this example, we would need to call the CreatePropertyDefinition API to create both InvestorRecord/Identifiers/External and InvestorRecord/Identifiers/Internal before creating the investor record they combine to identify, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/propertydefinitions'
  -H 'Authorization: Bearer <your-API-access-token>'
  -H 'Content-Type: application/json-patch+json
  -d '{
    "constraintStyle": "Identifier",
    "domain": "InvestorRecord",
    "scope": "Identifiers",
    "code": "External",
    "displayName": "An external identifier for investor records",
    "lifeTime": "Perpetual",
    "dataTypeId": {"scope": "system", "code": "string"}
  }'

Note the following:

• The constraintStyle must be Identifier to distinguish this property type from standard custom properties.

• The domain must be the entity type to which the property type belongs: either Person, LegalEntity, InvestorRecord or the entity type name of a custom entity.

• The scope of the property type maps to the idTypeScope of identifiers.

• The code maps to the idTypeCode.

• The lifeTime must be Perpetual. Time-variant identifiers are not allowed.

• The dataTypeId must resolve to a string data type.