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 every entity.

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, more 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 (such as FIGI and ISIN) as well as a globally-unique, system-generated identifier. More information.

• Certain other 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 property identifier. Note they can have more than one, perhaps reflecting different contexts in which they operate:

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

• LegalEntity, representing an institution.

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

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

Under-the-hood, a user-defined property identifier has a property type belonging to a particular domain. Consider the following example of an investor record:

{
  "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, InvestorRecord/Identifiers/External and InvestorRecord/Identifiers/Internal. Each consists of:

  • A domain (the first part of the 3-stage property key), in this case InvestorRecord.

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

  • An idTypeCode (the third part of the 3-stage property key), in this case External and Internal. This value 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 twice to create both InvestorRecord/Identifiers/External and InvestorRecord/Identifiers/Internal before creating the investor record they combine to identify.

For example, to create InvestorRecord/Identifiers/External:

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 property types.

• 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.