--- title: "Retrieving related entities and their properties" slug: "retrieving-related-entities-and-their-properties" updated: 2024-08-30T14:27:33Z published: 2024-08-30T14:27:33Z canonical: "support.lusid.com/retrieving-related-entities-and-their-properties" --- > ## 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. # Retrieving related entities and their properties When you retrieve [entities that support relationships in LUSID](/v1/docs/creating-relationships-between-certain-types-of-entity), 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](/v1/docs/filtering-entities-based-on-attributes-of-related-entities). For information on including properties of related entities in valuation reports, see [this article](/v1/docs/including-properties-and-derived-properties-in-valuation-reports). For example, consider an instrument representing BP shares related to a BP PLC legal entity representing the issuer: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/a229c7c8-9aef-4ba2-a2d5-ea3798db034b.png) You can query LUSID for the BP instrument and retrieve information about the related PB PLC legal entity using either the [REST API](/v1/docs/retrieving-related-entities-and-their-properties#retrieving-related-entities-for-bp-using-the-lusid-rest-api) or the [web app](/v1/docs/retrieving-related-entities-and-their-properties#retrieving-related-entities-for-bp-using-the-lusid-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](/v1/docs/creating-relationships-between-certain-types-of-entity#creating-a-relationship-type), call the [GetInstrumentRelationships](https://www.lusid.com/docs/api#operation/GetInstrumentRelationships) API, for example: ```json curl -X GET 'https://.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D9N/relationships?scope=default'  -H 'Authorization: Bearer ' ``` The response might be as follows. Note properties of related entities are *not* included: ```json {  "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](https://www.lusid.com/docs/api#operation/GetInstrument) API (or [GetInstruments](https://www.lusid.com/docs/api#operation/GetInstruments) or [ListInstruments](https://www.lusid.com/docs/api#operation/ListInstruments)) with the `relationshipDefinitionIds` parameter, separating the relationship type scope and code with a `/` character (the `%2F` UTF-8 encoding), for example: ```json curl -X GET 'https://.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D9N?scope=default&     relationshipDefinitionIds=InstrumentIssuer%2FIssuerId'  -H 'Authorization: Bearer ' ``` The response might be as follows. Note that, by default, properties of related entities are *not* included: ```json {  "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](https://www.lusid.com/docs/api#operation/GetInstrument) API with the `propertyKeys` as well as the `relationshipDefinitionIds` parameter, separating each stage of the 3-stage property key with a `/` character: ```json curl -X GET 'https://.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D9N?scope=default&     relationshipDefinitionIds=InstrumentIssuer%2FIssuerId&     propertyKeys=LegalEntity%2FScores%2FDEIScore'  -H 'Authorization: Bearer ' ``` The response might be as follows: ```json {  "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](https://www.lusid.com/app/home), navigate to the **Data Management > Instruments** dashboard, locate the instrument and then select **Map of relationships**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(60).png) ### 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**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(61).png)