Creating relationships between certain types of entity

You can create a relationship between any two of the following types of entity in LUSID, to represent a real-world connection between them:

For example, you could create a relationship between a portfolio and the person who manages that portfolio. Note the following:

  • A relationship must have a relationship type that specifies the source and target entity types, and other characteristics such as cardinality. It follows that you must create a relationship type before you can create relationships of that type.

  • A relationship is bi-directional; one entity is defined as the source and the other as the target, but you can query the relationship from either end.

  • You can create a relationship between two entities of the same type, for example from one instrument to another.

Providing you have appropriate access control permissions, you can create relationship types and then relationships:

  • Using the LUSID API endpoints in the Relationship Definitions and then the Relationships collections. Note the Relation Definitions and Relation collections are now deprecated.

  • Using the Data Management > Relationships dashboard in the LUSID web app to create relationship types, and then dedicated dashboards for supported entities to create relationships, for example Data Management > Instruments.

  • If you have a Luminesce license, using dedicated providers for relationship types (read/write) and relationships (read/write).

Creating a relationship type

The first task is to create a relationship type specifying the source and target entity types. You can then create as many relationships between pairs of these entities as you need.

To do this, obtain an API token and call the CreateRelationshipDefinition API for your LUSID domain, specifying:

  • A scope and code that together uniquely identify the relationship type.

  • A friendly displayName.

  • A sourceEntityType that identifies the 'left hand side' of the relationship. This must be one of the entity types listed at the top.

  • A targetEntityType that identifies the 'right hand side' of the relationship. This must be one of the entity types listed at the top, and can be the same entity type.

  • An outwardDescription that describes the nature of the relationship from the perspective of the source entity type.

  • An inwardDescription that describes the nature of the relationship from the perspective of the target entity type.

  • A lifeTime of either Perpetual (the default) or TimeVariant. For example, the relationship between a person and their biological parent would typically be modelled as perpetual, whilst the relationship between a person and their employer would be time-variant. 

  • A relationshipCardinality from the source to the target of either ManyToMany (the default) or ManyToOne.

For example, to create a relationship type between portfolio entities (as the source) and person entities (as the target):

curl -X POST "https://<your-domain>.lusid.com/api/api/relationshipdefinitions"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>"
  -d '{
  "scope": "PortfolioManagementTeam",
  "code": "Managers",
  "sourceEntityType": "Portfolio",
  "targetEntityType": "Person",
  "displayName": "Authorised managers for portfolios",
  "outwardDescription": "Is managed by",
  "inwardDescription": "Manages",
  "lifeTime": "TimeVariant",
  "relationshipCardinality": "ManyToMany"
}'

Providing the request is successful, the response is as follows. Note the relationshipDefinitionId is comprised of the scope and code (in red):

{
    "version": {
        "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",
        "asAtDate": "2022-09-14T09:37:02.3987300+00:00"
    },
    "relationshipDefinitionId": {
        "scope": "PortfolioManagementTeam",
        "code": "Managers"
    },
    "sourceEntityType": "Portfolio",
    "targetEntityType": "Person",
    "displayName": "Authorised managers for portfolios",
    "outwardDescription": "Is managed by",
    "inwardDescription": "Manages",
    "lifeTime": "TimeVariant",
    "relationshipCardinality": "ManyToMany",
    ...
}

The following picture summarises this relationship type:

Creating a relationship between a pair of entities

You can now call the CreateRelationship API to establish as many connections between pairs of portfolio and person entities as you need. Note the following:

  • The underlying relationship type is identified by its scope and code in the URL of the CreateRelationship API.

  • The source and target entities are identified by their identifiers. Note identifiers for different entity types can have different components:

    Entity type

    Components of identifier

    LegalEntity, Person

    idTypeScope, idTypeCode, code

    Instrument

    identifierType, identifierValue, scope (if not in the default scope)

    Custom entity

    identifierType, identifierScope, identifierValue

    All other types, including Portfolio and PortfolioGroup

    scope, code

    For more information, consult this table of entities and their identifiers.

For example, to establish a relationship between a particular portfolio and person using the relationship type above:

  • The API URL should be api/relationshipdefinitions/PortfolioManagementTeam/Managers/relationships.

  • The portfolio entity should be identified by its scope and code.

  • The person entity should be identified by its idTypeScope, idTypeCode and code.

curl -X POST "https://<your-domain>.lusid.com/api/api/relationshipdefinitions/PortfolioManagementTeam/Managers/relationships"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-API-access-token>"
  -d '{
   "sourceEntityId": { 
      "scope": "Finbourne-Examples",
      "code": "Global-Equity"  
   },  
   "targetEntityId": {  
      "idTypeScope": "PortfolioManagers", 
      "idTypeCode": "ManagerId", 
      "code": "PortMan1"  
   }, 
  "effectiveFrom": "2022-01-01T12:00:00.0000000+00:00",
}'

Providing the request is successful, the response is as follows:

{
    "version": {
        "effectiveFrom": "2022-01-01T00:00:00.0000000+00:00",
        "asAtDate": "2022-01-01T10:54:42.8103690+00:00"
    },
    "relationshipDefinitionId": {
        "scope": "PortfolioManagementTeam",
        "code": "Managers"
    },
    "sourceEntity": {
        "entityType": "Portfolio",
        "entityId": {
            "scope": "Finbourne-Examples",
            "code": "Global-Equity"
        },
        "displayName": "Global Equity Fund",
        "properties": {},
        "scope": "Finbourne-Examples",
        "identifiers": [
            {
                "identifierType": "code",
                "identifierValue": "Global-Equity"
            }
        ]
    },
    "targetEntity": {
        "entityType": "Person",
        "entityId": {
            "idTypeScope": "PortfolioManagers",
            "idTypeCode": "ManagerId",
            "code": "PortMan1"
        },
        "displayName": "John Doe",
        "properties": {},
        "scope": "Finbourne-Examples",
        "identifiers": [
            {
                "identifierScope": "PortfolioManagers",
                "identifierType": "ManagerId",
                "identifierValue": "PortMan1"
            }
        ]
    },
    "outwardDescription": "Is managed by",
    "inwardDescription": "Manages",
    "effectiveFrom": "2022-01-01T00:00:00.0000000+00:00",
    "effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"
}

Retrieving a relationship

You can query a relationship from either end.

For example, to retrieve details of all the entities related to the Global Equity portfolio, call the GetPortfolioRelationships API with the portfolio's scope and code:

curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios/Finbourne-Examples/Global-Equity/relationships"
  -H "Authorization: Bearer <your-API-access-token>"

To retrieve details of all the entities related to John Doe, call the GetPersonRelationships API with that person's idTypeScope, idTypeCode and code:

curl -X GET "https://<your-domain>.lusid.com/api/api/persons/PortfolioManagers/ManagerId/PortMan1/relationships"
  -H "Authorization: Bearer <your-API-access-token>"

For either API, you can perform a filter operation to restrict the entities retrieved to just those with a matching set of relationships.

Deleting a relationship

To delete a relationship between a pair of entities, use the DeleteRelationship API.

For time-variant relationships, the relationship is deleted from the effectiveFrom date provided in the request. For example, if you deleted the relationship between the Global Equity portfolio and John Doe effective 30 March 2022, the relationship would remain in place between 1 January 2022 and 29 March 2022.

Deprecated endpoints

Please note that the LUSID API documentation refers to several Relations (as opposed to Relationships) endpoints, which represent a former iteration of the relationships model. Whilst they are fully compatible with the relationships described above, these endpoints will shortly be marked as deprecated and should no longer be used. The full list of deprecated endpoints is as follows: 

Relation Definitions:

  • POST /api/relationdefinitions 

  • GET /api/relationdefinitions/{scope}/{code} 

Relations:

  • POST /api/relations/{scope}/{code}

  • POST /api/relations/{scope}/{code}/$delete

Retrieve Relations:

  • GET /api/legalentities/{idTypeScope}/{idTypeCode}/{code}/relations

  • GET /api/persons/{idTypeScope}/{idTypeCode}/{code}/relations

  • GET /api/portfoliogroups/{scope}/{code}/relations

  • GET /api/portfolios/{scope}/{code}/relations