Representing people in LUSID using person entities

Views:

You can create a person entity to represent a person of interest to your LUSID domain, for example a portfolio manager, trader or sales representative. See a list of the built-in entity types.

Note the following:

A person entity must have at least one user-specified identifier. Under the hood, an identifier is defined as a custom property with a constraintStyle of Identifier and a 3-stage property key in the Person domain.
LUSID automatically generates a LusidPersonId internal identifier for every person entity that is guaranteed to be unique and never change. This is identical in concept and structure to an instrument's LUID.
A person entity only has two data fields: displayName and description.
You can add custom properties to a person entity in the normal way to extend the information stored about them.
You can create relationships between a person entity and certain other types of entity, for example between a portfolio manager and the portfolios they manage.
You can apply access metadata to an identifier of a person entity. This may be a more effective way of restricting access to data stored about people in LUSID.

Providing you have appropriate access control permissions, you can interact with a person entity (and any relationships they might have):

Using the LUSID API endpoints in the Persons collection.
If you have a Luminesce license, using dedicated read and write providers.

Note you cannot interact via the LUSID web app at this time.

Understanding identifiers

A person entity must have at least one user-specified identifier. Consider the following JSON fragment defining John Doe, who is active in LUSID as both a portfolio manager and a trader, and so has an identifier for each context:

"displayName": "John Doe",
"description": "A portfolio manager and trader in US investments",
"lusidPersonId": "LUID_00003D6X",
"identifiers": {
  "Person/PortfolioManagers/ManagerId": {
     "key": "Person/PortfolioManagers/ManagerId",
     "value": {
       "labelValue": "PortMan1"
     }
  },
  "Person/Traders/TraderId": {
    "key": "Person/Traders/TraderId",
    "value": {
      "labelValue": "Trader5"
    }
  }
},
...

Note: LUSID automatically generates the LUID_00003D6X value for the LusidPersonId identifier, which is guaranteed to be unique and never change.

An identifier consists of three components: an idTypeScope, idTypeCode and code. The values you assign to these components combine to uniquely identify John Doe in each of the contexts in which he operates. In this example:

To uniquely identify John Doe as a ...	idTypeScope (This is the second stage in the 3-stage key)	idTypeCode (This is the third stage in the 3-stage key)	code (This is the label value)
Portfolio manager	`PortfolioManagers`	`ManagerId`	`PortMan1`
Trader	`Traders`	`TraderId`	`Trader5`

For each identifier you intend to give a person entity, you must obtain an API access token and call the CreatePropertyDefinition API for your LUSID domain to create a property definition with the following mandatory characteristics:

A domain of Person.
A constraintStyle of Identifier.
A lifeTime of Perpetual.

Note you can call the SearchProperties API with a suitable filter to find all the property definitions that have been created as identifiers for person entities, in case a suitable definition already exists:

curl -X GET "https://<your-domain>.lusid.com/api/api/search/propertydefinitions?filter=constraintStyle%20eq%20%27Identifier%27%20and%20domain%20eq%20%27Person%27"
  -H "Authorization: Bearer <your-API-access-token>"

Creating a property definition to constitute a 'trader' identifier

The following call creates a property definition with a 3-stage property key of Person/Traders/TraderId:

curl -X POST "https://<your-domain>.lusid.com/api/api/propertydefinitions"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>"
  -d '{
  "domain": "Person",
  "scope": "Traders",
  "code": "TraderId",
  "valueRequired": true,
  "displayName": "Trader identifier for Person entities",
  "dataTypeId": { "scope": "system", "code": "string" },
  "lifeTime": "Perpetual",
  "constraintStyle": "Identifier",
}'

Creating a property definition to constitute a 'portfolio manager' identifier

The following call creates a property definition with a 3-stage property key of Person/PortfolioManagers/ManagerId:

curl -X POST "https://<your-domain>.lusid.com/api/api/propertydefinitions"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>"
  -d '{
  "domain": "Person",
  "scope": "PortfolioManagers",
  "code": "ManagerId",
  "valueRequired": true,
  "displayName": "Portfolio manager identifier for Person entities",
  "dataTypeId": { "scope": "system", "code": "string" },
  "lifeTime": "Perpetual",
  "constraintStyle": "Identifier",
}'

Creating a person entity with a unique identifier value

You can now call the UpsertPerson API to create a person entity for John Doe with a trader identifier (you can add the portfolio manager identifier retrospectively).

Note the following:

The key of the trader identifier must be the 3-stage property key for the underlying property definition, in this case Person/Traders/TraderId.
The labelValue you give the trader identifier must be unique among all traders represented in LUSID, in this case Trader5.

curl -X POST "https://<your-domain>.lusid.com/api/api/persons"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>"
  -d '{
  "identifiers": {
    "Person/Traders/TraderId": {
      "key": "Person/Traders/TraderId",
      "value": {
        "labelValue": "Trader5"
      }
    }
  },
  "displayName": "John Doe",
  "description": "A portfolio manager and trader in US investments"
}'

Providing the request is successful, the response is as follows:

{
  "displayName": "John Doe",
  "description": "A portfolio manager and trader in US investments",
  "lusidPersonId": "LUID_00003D6X",
  "identifiers": {
    "Person/Traders/TraderId": {
      "key": "Person/Traders/TraderId",
      "value": {
        "labelValue": "Trader5"
      },
      "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",
      "effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"
    }
  },
  "properties": {},
  "version": {
    "effectiveFrom": "2022-09-08T14:55:17.1582910+00:00",
    "asAtDate": "2022-09-08T14:55:17.3857390+00:00"
  },
  ...
}

Adding and removing identifiers retrospectively

Once a person entity exists, you can call the SetPersonIdentifiers API to add additional identifier(s), specifying an identifier value (that is, code) unique to the context.

For example, to retrospectively add a portfolio manager identifier to John Doe (assuming the underlying property definition already exists), and give it the value PortMan1:

curl -X POST "https://<your-domain>.lusid.com/api/api/persons/Traders/TraderId/Trader5/identifiers"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>" 
  -d '{
  "identifiers": {
    "Person/PortfolioManagers/ManagerId": {
      "key": "Person/PortfolioManagers/ManagerId",
      "value": {
        "labelValue": "PortMan1"
      }
    }
  }
}'

To remove an identifier (providing it is not the last one), call the DeletePersonIdentifiers API.

Retrieving person entities and their relationships

You can retrieve:

Every person entity using the ListAllPersons API.
Every person entity with a particular identifier (for example, all the portfolio managers or all the traders) using the ListPersons API.
A particular person entity using the LUSID GetPerson API.

For the first two operations, you can perform a filter operation to retrieve just a matching set, for example on the values of a particular identifier:

Identifiers[Person/PortfolioManagers/ManagerId] startswith 'Port'

You can retrieve relationships created between a person entity and other types of entity using the GetPersonRelationships API.

Keywords: person, idtypecode, idtypescope