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.

Note the following:

A legal 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 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 concept and structure to an instrument's LUID.
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 to record a 20-character alpha-numeric code based on the ISO 17442 standard.
You can add custom properties to a legal entity in the normal way to extend the information stored about them.
You can create relationships 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 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, you can interact with a legal entity (and any relationships it might have):

Using the LUSID API endpoints in the Legal Entities 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 legal entity must have at least one user-specified 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:

"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 and call the CreatePropertyDefinition API for your LUSID domain to create a property definition with the following mandatory characteristics:

A domain of LegalEntity.
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 legal 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%LegalEntity%27"
  -H "Authorization: Bearer <your-API-access-token>"

Creating a property definition to constitute an 'investment firm' identifier

The following call creates a property definition with a 3-stage property key of LegalEntity/InvestmentFirms/InvestId:

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": "LegalEntity",
  "scope": "InvestmentFirms",
  "code": "InvestId",
  "valueRequired": true,
  "displayName": "Investment firm identifier for Legal entities",
  "dataTypeId": { "scope": "system", "code": "string" },
  "lifeTime": "Perpetual",
  "constraintStyle": "Identifier",
}'

Creating a property definition to constitute an 'international bank' identifier

The following call creates a property definition with a 3-stage property key of LegalEntity/InternationalBanks/BankId:

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": "LegalEntity",
  "scope": "InternationalBanks",
  "code": "BankId",
  "valueRequired": true,
  "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 API to create a single legal entity for Acme Inc with an investment firm identifier (you can add the international bank identifier retrospectively).

Note: You can call the 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 definition, 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.

curl -X POST "https://<your-domain>.lusid.com/api/api/legalentities"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>"
  -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:

{
    "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 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 definition already exists), and give it the value Bank1:

curl -X POST "https://<your-domain>.lusid.com/api/api/legalentities/InvestmentFirms/InvestId/Invest5/identifiers"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>" 
  -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 API.

Retrieving legal entities and their relationships

You can retrieve:

Every legal entity using the ListAllLegalEntities API.
Every legal entity with a particular identifier (for example, all the international banks or all the investment firms) using the ListLegalEntities API.
A particular legal entity using the GetLegalEntity 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[LegalEntity/InternationalBanks/BankId] startswith 'Bank'

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