Retrieving related entities and their properties

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.

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:

{
  "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"
    }
  ]
  ...
}

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

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

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:

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: