--- title: "Representing institutions in LUSID using legal entities" slug: "representing-institutions-in-lusid-using-legal-entities" updated: 2025-07-22T15:28:29Z published: 2025-07-22T15:28:29Z canonical: "support.lusid.com/representing-institutions-in-lusid-using-legal-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 institutions in LUSID using legal entities You can create a *legal entity* to represent an institution of interest to your LUSID domain, for example an international bank, investment firm or pension company. [See a list of the built-in entity types](/v1/docs/what-is-an-entity). Note the following: - A legal 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 `LegalEntity` domain. - LUSID automatically generates a `LusidLegalEntityId` internal identifier for every legal 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 legal entity. You must specify a user-defined identifier instead. - A legal entity has a minimal set of data fields, for example `displayName` and `description`. You can optionally specify counterparty information. - You can populate the `LegalEntity/default/LEI` [system property](/v1/docs/what-is-a-system-property#legal-entity) to record a 20-character alpha-numeric code based on the ISO 17442 standard. - You can add [custom properties](/v1/docs/introduction-to-properties) to a legal 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 legal entity and certain other types of entity, for example between a bank and all the instruments for which it is the issuer. - You can apply [access metadata](/v1/docs/understanding-access-metadata-amd) to an identifier of a legal entity. This may be a more effective way of restricting access to data stored about institutions in LUSID. Providing you have appropriate [access control permissions](/v1/docs/introduction-to-identity-management-and-access-control), you can interact with a legal entity (and any relationships it might have): - Using the **Data Management > Legal Entities** dashboard in the LUSID web app. - Using the LUSID API endpoints in the [Legal Entities](https://www.lusid.com/docs/api#tag/Legal-Entities) collection. - If you have a Luminesce license, using dedicated [read](/v1/docs/lusidlegalentity) and [write](/v1/docs/lusidlegalentitywriter) providers. ## Understanding user-defined identifiers A legal entity must have at least one [user-defined identifier](/v1/docs/what-is-an-identifier). Consider the following JSON fragment defining Acme Inc, which is active in LUSID as both an international bank and as an investment firm, and so has an identifier for each context: ```json "displayName": "Acme Inc", "description": "An international bank and investment firm", "lusidLegalEntityId": "LUID_00003D4V", "identifiers": {  "LegalEntity/InternationalBanks/BankId": {     "key": "LegalEntity/InternationalBanks/BankId",     "value": {       "labelValue": "Bank1"     }   },   "LegalEntity/InvestmentFirms/InvestId": {    "key": "LegalEntity/InvestmentFirms/InvestId",    "value": {      "labelValue": "Invest5"    }  } }, ... ``` > **Note**: LUSID automatically generates the `LUID_00003D4V` value for the `LusidLegalEntityId` 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 Acme Inc in each of the contexts in which it operates. In this example: | **To uniquely identify Acme Inc as an ...** | **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) | | --- | --- | --- | --- | | International bank | `InternationalBanks` | `BankId` | `Bank1` | | Investment firm | `InvestmentFirms` | `InvestId` | `Invest5` | For each identifier you intend to give a legal 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 `LegalEntity`. - 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 legal 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%LegalEntity%27"   -H "Authorization: Bearer " ``` ### Creating a property type to constitute an 'investment firm' identifier The following call creates a property type with a 3-stage property key of `LegalEntity/InvestmentFirms/InvestId`: ```json curl -X POST "https://.lusid.com/api/api/propertydefinitions"  -H "Content-Type: application/json-patch+json"  -H "Authorization: Bearer "  -d '{  "domain": "LegalEntity",  "scope": "InvestmentFirms",  "code": "InvestId",  "displayName": "Investment firm identifier for Legal entities",  "dataTypeId": { "scope": "system", "code": "string" },  "lifeTime": "Perpetual",  "constraintStyle": "Identifier" }' ``` ### Creating a property type to constitute an 'international bank' identifier The following call creates a property type with a 3-stage property key of `LegalEntity/InternationalBanks/BankId`: ```json curl -X POST "https://.lusid.com/api/api/propertydefinitions"  -H "Content-Type: application/json-patch+json"  -H "Authorization: Bearer "  -d '{  "domain": "LegalEntity",  "scope": "InternationalBanks",  "code": "BankId",  "displayName": "International bank identifier for Legal entities",  "dataTypeId": { "scope": "system", "code": "string" },  "lifeTime": "Perpetual",  "constraintStyle": "Identifier" }' ``` ## Creating a legal entity with a unique identifier value You can now call the [UpsertLegalEntity](https://www.lusid.com/docs/api#operation/UpsertLegalEntity) API to create a single legal entity for Acme Inc with an investment firm identifier (you can add the international bank identifier [retrospectively](/v1/docs/representing-institutions-in-lusid-using-legal-entities#adding-and-removing-identifiers-retrospectively)). > **Note**: You can call the [UpsertLegalEntities](https://www.lusid.com/docs/api#operation/UpsertLegalEntities) API to create multiple legal entities, and decide whether to fail the entire operation if one fails validation. Note the following: - The `key` of the investment firm identifier must be the 3-stage property key for the underlying property type, in this case `LegalEntity/InvestmentFirms/InvestId`. - The `labelValue` you give the investment firm identifier must be unique among all investment firms represented in LUSID, in this case `Invest5`. ```json curl -X POST "https://.lusid.com/api/api/legalentities"  -H "Content-Type: application/json-patch+json"  -H "Authorization: Bearer "  -d '{  "identifiers": {    "LegalEntity/InvestmentFirms/InvestId": {      "key": "LegalEntity/InvestmentFirms/InvestId",      "value": {        "labelValue": "Invest5"      }    }  },  "displayName": "Acme Inc",  "description": "An international bank and investment firm" }' ``` Providing the request is successful, the response is as follows: ```json {     "displayName": "Acme Inc",     "description": "An international bank and investment firm",     "lusidLegalEntityId": "LUID_00003D4V",     "identifiers": {         "LegalEntity/InvestmentFirms/InvestId": {             "key": "LegalEntity/InvestmentFirms/InvestId",             "value": {                 "labelValue": "Invest5"             },             "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",             "effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"         }     },     "properties": {},     "version": {         "effectiveFrom": "2022-09-13T11:09:01.5629800+00:00",         "asAtDate": "2022-09-13T11:09:01.6943670+00:00"     },     ... } ``` ## Adding and removing identifiers retrospectively Once a legal entity exists, you can call the [SetLegalEntityIdentifiers](https://www.lusid.com/docs/api#operation/SetLegalEntityIdentifiers) API to add additional identifier(s), specifying an identifier value (that is, `code`) unique to the context. For example, to retrospectively add an international bank identifier to Acme Inc (assuming the underlying property type [already exists](/v1/docs/representing-institutions-in-lusid-using-legal-entities#creating-a-property-definition-to-constitute-an-international-bank-identifier)), and give it the value `Bank1`: ```json curl -X POST "https://.lusid.com/api/api/legalentities/InvestmentFirms/InvestId/Invest5/identifiers"   -H "Content-Type: application/json-patch+json"   -H "Authorization: Bearer "    -d '{   "identifiers": {     "LegalEntity/InternationalBanks/BankId": {       "key": "LegalEntity/InternationalBanks/BankId",       "value": {         "labelValue": "Bank1"       }     }   } }' ``` To remove an identifier (providing it is not the last one), call the [DeleteLegalEntityIdentifiers](https://www.lusid.com/docs/api#operation/DeleteLegalEntityIdentifiers) API. ## Retrieving legal entities and their relationships You can retrieve: - Every legal entity using the [ListAllLegalEntities](https://www.lusid.com/docs/api#operation/ListAllLegalEntities) API. - Every legal entity with a particular identifier (for example, all the international banks or all the investment firms) using the [ListLegalEntities](https://www.lusid.com/docs/api#operation/ListLegalEntities) API. - A particular legal entity using the [GetLegalEntity](https://www.lusid.com/docs/api#operation/GetLegalEntity) 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[LegalEntity/InternationalBanks/BankId] startswith 'Bank' ``` You can retrieve relationships created between a legal entity and other types of entity using the [GetLegalEntityRelationships](https://www.lusid.com/docs/api#operation/GetLegalEntityRelationships) API.