Views:

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 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.
  • A relationship must have a relationship definition that specifies the source and target entity types, and other characteristics such as cardinality.

Providing you have appropriate access control permissions, you can interact with relationships:

Note you cannot interact via the LUSID web app at this time.

Creating a relationship definition

The first task is to create a relationship definition 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 definition.
  • 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 definition 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 definition:



 

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 definition 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 typeComponents of identifier
    LegalEntity, PersonidTypeScope, idTypeCode, code
    InstrumentidentifierType, identifierValue, scope (if not in the default scope)
    Custom entityidentifierType, identifierScope, identifierValue
    All other types, including Portfolio and PortfolioGroupscope, 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 definition 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 relationship details

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 its 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 his 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 retrieve just a matching set of relationships.

Deleting relationships

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/relationdefinition
  • 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