Create relationships
Learn how to create relationships via the API.
Create a collection of relations in the platform according to a given JSON object definition.
Describe startObject or/and endObject by the referenced entityURI or by the referenced entity crosswalk.
We recommend that you only create relations using crosswalks (and avoid using URIs to do so). If you do need to use URIs for creating relations, set the connectRelationsToDefaultCrosswalk property to true. This ensures that a new relation created for the entity doesn’t have the same end date as an earlier relation that has been end-dated. For more information, see The connectRelationsToDefaultCrosswalk Property.
To consolidate relation crosswalk entries, ensuring that only the most recent crosswalk from the same contributor is retained, see topic Consolidating relationship crosswalks.
Request
POST {TenantURL}/relations| Parameter | Required | Details | |
|---|---|---|---|
| Headers | Authorization
| Yes | Information about authentication access token in format "Bearer <accessToken>" (see details in Authentication API ). |
Content-Type | Yes | Must be "Content-Type: application/json". | |
| Query | returnObjects
| No | Specifies if response must contain created objects. Default is false. |
options
| No | Comma-separated list of different options that affect a relation's JSON content in the response and the override process. Available options:
| |
alwaysCreateDCR | No |
A new DCR is created with new relation changes. See also:About Data Change Request. | |
| Yes | JSON Array with objects representing relations to be created. Each object must have a "type" property but won’t have "URI", "createdBy", "createdTime", "label", "updatedTime" properties (they’ll be provided/generated by a Reltio API). A request for create relationship contains the "crosswalks" property. If in relation startObject or endObject is described by a crosswalk, it must contain the "crosswalks" section defining the referencing entity crosswalk. This section must contain "type", "value" properties and optionally "sourceTable". | ||
| Body | Yes | JSON Array with objects representing relations to be created. Each object must have a "type" property but won’t have "URI", "createdBy", "createdTime", "label", "updatedTime" properties (they’ll be provided/generated by a Reltio API). A request for create relationship contains the "crosswalks" property. If in relation startObject or endObject is described by a crosswalk, it must contain the "crosswalks" section defining the referencing entity crosswalk. This section must contain "type", "value" properties and optionally "sourceTable". | |
Response:
Array with results for each element of a request. Each result will have the following properties:
index- index of a relation object in JSON Array to be created. Required in a response.URI- URI of relationship object that is created. Returned only if an object was created successfully.error- if object can't be created for some reason. Contains details of the problem. Returns only if an object wasn't created.- Possible Errors:
warning- if an object is created but there were some problems.status- result of an operation; possible values are "OK" or "failed"
- Possible Errors:
Example 1: Describe
startObject and endObject by objectURI
Request: Add Relationship
POST {TenantURL}/relations
Headers: Source-System: configuration/sources/XYZ, Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512, Content-Type: application/json
Body:
[
{
"type":"configuration/relationTypes/Employment",
"startDate": "1657717450338",
"startObject":{
"objectURI":"entities/e1"
},
"endObject":{
"objectURI":"entities/e2"
},
"attributes":{
"Title":[
{
"value":"CEO"
}
]
}
}
]Response
POST {TenantURL}/relations
Headers: Source-System: configuration/sources/XYZ, Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512, Content-Type: application/json
[
{
"index": 1,
"URI": "relations/r0",
"object": {
"URI":"relations/r1",
"type":"configuration/relationTypes/Employment",
"startObject":{
"URI":"relations/r1/startObject",
"objectURI":"entities/e1",
"type":"configuration/entityTypes/Individual",
"label":"John Smith",
"directionalLabel":"employee"
},
"endObject":{
"URI":"relations/r1/endObject",
"objectURI":"entities/e2",
"type":"configuration/entityTypes/Organization",
"label":"Super Company",
"directionalLabel":"employer"
},
"attributes":{
"URI": "relations/r1/attributes",
"Title":[
{
"URI": "relations/r1/attributes/Title/1",
"type": "configuration/relationTypes/Employment/attributes/Title",
"value":"CEO"
}
]
},
"crosswalks":[
{
"URI": "relations/r1/crosswalks/1",
"type":"configuration/sources/MDM",
"value":"Employemnt.1000",
"attributes": [
"relations/r1/attributes/Title/1"
]
}
],
"createdTime":1351899105569,
"createdBy":"admin",
"updatedTime":1353933493738,
"updatedBy":"fadler",
"startDate": 1657717450338
},
"successful": true
}
]Example 2: Describe startObject by objectURI and endObject by Crosswalk
Request: Add Relationship
POST {TenantURL}/relations
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512, Content-Type: application/json
Body:
[{
"type":"configuration/relationTypes/Employment",
"startObject":{
"objectURI":"entities/00005KL"
},
"endObject":{
"crosswalks":[
{
"type":"configuration/sources/MDM",
"value":"Organization.1"
}
]
}
}]Response
POST {TenantURL}/relations
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512, Content-Type: application/json
[{
"index": 0,
"object": {
"uri": "relations/00006OP",
"type": "configuration/relationTypes/Employment",
"startObject": {
"objectURI": "entities/00005KL",
"uri": "relations/00006OP/startObject",
"type": "configuration/entityTypes/Individual",
"label": null,
"directionalLabel": "employee"
},
"endObject": {
"objectURI": "entities/00009ab",
"uri": "relations/00006OP/endObject",
"type": "configuration/entityTypes/Organization",
"label": "Super Company",
"directionalLabel": "employer"
},
"attributes": {},
"crosswalks": [{
"uri": "relations/00006OP/crosswalks/X3",
"type": "configuration/sources/Reltio",
"value": "00006OP",
"attributes": []
}]
},
"successful": true
}]