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
andRelation
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
andcode
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 eitherPerpetual
(the default) orTimeVariant
. 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 eitherManyToMany
(the default) orManyToOne
.
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
andcode
in the URL of theCreateRelationship
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 thedefault
scope)Custom entity
identifierType
,identifierScope
,identifierValue
All other types, including
Portfolio
andPortfolioGroup
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
andcode
.The person entity should be identified by its
idTypeScope
,idTypeCode
andcode
.
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