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 all built-in entities.

Note the following:

  • A person entity must have at least one identifier. Under the hood, each identifier is defined as a custom property with a constraintStyle of Identifier and a 3-stage property key in the Person domain.
  • 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.
  • LUSID stores person entity data bitemporally and you can retrieve historical information by rolling back the as at timeline in the normal way.

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 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"
    }
  }
},
...

An identifier consists of three components: an idTypeScopeidTypeCode 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 managerPortfolioManagersManagerIdPortMan1
TraderTradersTraderIdTrader5

Note: LUSID automatically generates an additional LusidPersonId identifier for John Doe (in this case, with a value of LUID_00003D6X) that is guaranteed to be unique and never change.

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.