--- title: "Representing people in LUSID using person entities" slug: "representing-people-in-lusid-using-person-entities" tags: ["person", "idtypecode", "idtypescope"] updated: 2025-07-22T16:33:57Z published: 2025-07-22T16:33:57Z canonical: "support.lusid.com/representing-people-in-lusid-using-person-entities" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # Representing people in LUSID using person entities 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](/v1/docs/what-is-an-entity). Note the following: - A person entity must have at least one user-defined identifier. Under the hood, an identifier is specified 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 structure to an instrument's [LUID](/v1/docs/what-is-a-lusid-instrument-id-or-luid), but differs in that you cannot use it to retrieve or delete a person entity. You must specify a user-defined identifier instead. - A person entity only has two data fields: `displayName` and `description`. - You can add [custom properties](/v1/docs/introduction-to-properties) to a person entity in the normal way to extend the information stored about them. - You can create [relationships](/v1/docs/creating-relationships-between-certain-types-of-entity) 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](/v1/docs/understanding-access-metadata-amd) 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](/v1/docs/introduction-to-identity-management-and-access-control), you can interact with a person entity (and any relationships they might have): - Using the **Data Management > Persons** dashboard in the LUSID web app. - Using the LUSID API endpoints in the [Persons](https://www.lusid.com/docs/api#tag/Persons) collection. - If you have a Luminesce license, using dedicated [read](/v1/docs/lusidperson) and [write](/v1/docs/lusidpersonwriter) providers. ## Understanding user-defined identifiers A person entity must have at least one [user-defined identifier](/v1/docs/what-is-an-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: ```json "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](/v1/docs/how-do-i-obtain-and-use-a-short-lived-api-access-token-from-okta) and call the [CreatePropertyDefinition](https://www.lusid.com/docs/api#operation/CreatePropertyDefinition) API for your LUSID domain to create a property type with the following mandatory characteristics: - A `domain` of `Person`. - A `constraintStyle` of `Identifier`. - A `lifeTime` of `Perpetual`. Note you can call the [SearchProperties](https://www.lusid.com/docs/api#operation/SearchProperties) API with a suitable filter to find all the property types that have been created as identifiers for person entities, in case a suitable one already exists: ```json curl -X GET "https://.lusid.com/api/api/search/propertydefinitions?filter=constraintStyle%20eq%20%27Identifier%27%20and%20domain%20eq%20%27Person%27"   -H "Authorization: Bearer " ``` ### Creating a property type to constitute a 'trader' identifier The following call creates a property type with a 3-stage property key of `Person/Traders/TraderId`: ```json curl -X POST "https://.lusid.com/api/api/propertydefinitions"  -H "Content-Type: application/json-patch+json"  -H "Authorization: Bearer "  -d '{  "domain": "Person",  "scope": "Traders",  "code": "TraderId",  "displayName": "Trader identifier for Person entities",  "dataTypeId": { "scope": "system", "code": "string" },  "lifeTime": "Perpetual",  "constraintStyle": "Identifier" }' ``` ### Creating a property type to constitute a 'portfolio manager' identifier The following call creates a property type with a 3-stage property key of `Person/PortfolioManagers/ManagerId`: ```json curl -X POST "https://.lusid.com/api/api/propertydefinitions"  -H "Content-Type: application/json-patch+json"  -H "Authorization: Bearer "  -d '{  "domain": "Person",  "scope": "PortfolioManagers",  "code": "ManagerId",  "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](https://www.lusid.com/docs/api#operation/UpsertPerson) API to create a person entity for John Doe with a trader identifier (you can add the portfolio manager identifier [retrospectively](/v1/docs/representing-people-in-lusid-using-person-entities#adding-and-removing-identifiers-retrospectively)). Note the following: - The `key` of the trader identifier must be the 3-stage property key for the underlying property type, 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`. ```json curl -X POST "https://.lusid.com/api/api/persons"  -H "Content-Type: application/json-patch+json"  -H "Authorization: Bearer "  -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: ```json {  "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](https://www.lusid.com/docs/api#operation/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 type [already exists](/v1/docs/representing-people-in-lusid-using-person-entities#creating-a-property-definition-to-constitute-a-portfolio-manager-identifier)), and give it the value `PortMan1`: ```json curl -X POST "https://.lusid.com/api/api/persons/Traders/TraderId/Trader5/identifiers"  -H "Content-Type: application/json-patch+json"  -H "Authorization: Bearer "  -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](https://www.lusid.com/docs/api#operation/DeletePersonIdentifiers) API. ## Retrieving person entities and their relationships You can retrieve: - Every person entity using the [ListAllPersons](https://www.lusid.com/docs/api#operation/ListAllPersons) API. - Every person entity with a particular identifier (for example, all the portfolio managers or all the traders) using the [ListPersons](https://www.lusid.com/docs/api#operation/ListPersons) API. - A particular person entity using the LUSID [GetPerson](https://www.lusid.com/docs/api#operation/GetPerson) API. For the first two operations, you can [perform a filter operation](/v1/docs/filtering-information-retrieved-from-lusid) to retrieve just a matching set, for example on the values of a particular identifier: ```plaintext Identifiers[Person/PortfolioManagers/ManagerId] startswith 'Port' ``` You can retrieve relationships created between a person entity and other types of entity using the [GetPersonRelationships](https://www.lusid.com/docs/api#operation/GetPersonRelationships) API.