When you retrieve entities that support relationships in LUSID, you can additionally retrieve information about related entities. This can be both their core data fields and, optionally, properties.
Note: For information on filtering entities based on attributes of related entities, see this article. For information on including properties of related entities in valuation reports, see this article.
For example, consider an instrument representing BP shares related to a BP PLC legal entity representing the issuer:
You can query LUSID for the BP instrument and retrieve information about the related PB PLC legal entity using either the REST API or the web app. Note you could alternatively query LUSID for the BP PLC legal entity and retrieve information about the related BP instrument; a relationship is bi-directional.
Retrieving related entities for BP using the LUSID REST API
Retrieving every related entity
To retrieve every entity related to the BP instrument by any relationship type, call the GetInstrumentRelationships API, for example:
curl -X GET 'https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D9N/relationships?scope=default' -H 'Authorization: Bearer <your-API-access-token>'
The response might be as follows. Note properties of related entities are not included (highlighted in red):
{
"values": [
{
"relationshipDefinitionId": {
"scope": "InstrumentIssuer",
"code": "IssuerId"
},
"relatedEntity": {
"entityType": "LegalEntity",
"entityId": {
"idTypeScope": "GLEIF",
"idTypeCode": "LEI",
"code": "213800LH1BZH3DI6G"
},
"displayName": "BP PLC",
"description": "Legal responsibility for shares",
"properties": {},
"identifiers": [
{
"identifierScope": "GLEIF",
"identifierType": "LEI",
"identifierValue": "213800LH1BZH3DI6G"
}
]
},
"traversalDirection": "Out",
"traversalDescription": "Issued by",
"effectiveFrom": "2023-09-01T12:29:36.2340000+00:00",
"effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"
}
]
...
}
Retrieving particular related entities
To retrieve every entity related to BP by a particular relationship type, call the GetInstrument API (or GetInstruments or ListInstruments) with the relationshipDefinitionIds parameter, separating the relationship type scope and code with a / character (the %2F UTF-8 encoding), for example:
curl -X GET 'https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D9N?scope=default&
relationshipDefinitionIds=InstrumentIssuer%2FIssuerId'
-H 'Authorization: Bearer <your-API-access-token>'
The response might be as follows. Note that, by default, properties of related entities are not included:
{
"scope": "default",
"lusidInstrumentId": "LUID_00003D9N",
"name": "BP",
"identifiers": {"LusidInstrumentId": "LUID_00003D9N"},
"properties": [],
"instrumentDefinition": {"domCcy": "GBP", "instrumentType": "Equity"},
"state": "Active",
"assetClass": "Equities",
"domCcy": "GBP",
"relationships": [
{
"relationshipDefinitionId": {
"scope": "InstrumentIssuer",
"code": "IssuerId"
},
"relatedEntity": {
"entityType": "LegalEntity",
"entityId": {
"idTypeScope": "GLEIF",
"idTypeCode": "LEI",
"code": "213800LH1BZH3DI6G"
},
"displayName": "BP PLC",
"description": "Legal responsibility for shares",
"properties": {},
"identifiers": [
{
"identifierScope": "GLEIF",
"identifierType": "LEI",
"identifierValue": "213800LH1BZH3DI6G"
}
]
},
"traversalDirection": "Out",
"traversalDescription": "Issued by",
"effectiveFrom": "2023-09-01T12:29:36.2340000+00:00",
"effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"
}
],
...
}
Retrieving properties for particular related entities
To additionally retrieve properties for entities related to BP by a particular relationship type, call the GetInstrument API with the propertyKeys as well as the relationshipDefinitionIds parameter, separating each stage of the 3-stage property key with a / character:
curl -X GET 'https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D9N?scope=default&
relationshipDefinitionIds=InstrumentIssuer%2FIssuerId&
propertyKeys=LegalEntity%2FScores%2FDEIScore'
-H 'Authorization: Bearer <your-API-access-token>'
The response might be as follows:
{
"scope": "default",
"lusidInstrumentId": "LUID_00003D9N",
"name": "BP",
"identifiers": {"LusidInstrumentId": "LUID_00003D9N"},
"properties": [],
"instrumentDefinition": {"domCcy": "GBP", "instrumentType": "Equity"},
"state": "Active",
"assetClass": "Equities",
"domCcy": "GBP",
"relationships": [
{
"relationshipDefinitionId": {
"scope": "InstrumentIssuer",
"code": "IssuerId"
},
"relatedEntity": {
"entityType": "LegalEntity",
"entityId": {
"idTypeScope": "GLEIF",
"idTypeCode": "LEI",
"code": "213800LH1BZH3DI6G"
},
"displayName": "BP PLC",
"description": "Legal responsibility for shares",
"properties": {
"LegalEntity/Scores/DEIScore": {
"key": "LegalEntity/Scores/DEIScore",
"value": {
"metricValue": {
"value": 33.5
}
},
"effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",
"effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"
}
},
"identifiers": [
{
"identifierScope": "GLEIF",
"identifierType": "LEI",
"identifierValue": "213800LH1BZH3DI6G"
}
]
},
"traversalDirection": "Out",
"traversalDescription": "Issued by",
"effectiveFrom": "2023-09-01T12:29:36.2340000+00:00",
"effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"
}
],
...
}
Retrieving related entities for BP using the LUSID web app
Retrieving every related entity
To retrieve every entity related to the BP instrument by any relationship type, sign in to the LUSID web app, navigate to the Data Management > Instruments dashboard, locate the instrument and then select Map of relationships:
Retrieving particular related entities and their properties
To retrieve every entity related to BP by a particular relationship type, click the Lusid Instrument ID link in the dashboard above to view the instrument details, click the Relationships tab (highlighted in red below) and then select the type of relationship. To additionally see properties for related entities, click the Configuration icon (highlighted in green) to add appropriate properties to the dashboard, for example Diversity score: