Accelerate the Value of Data

Create relationships

This operation creates a collection of relations in the Reltio Platform according to the JSON object definition.

Describe startObject or/and endObject by the referenced entityURI or by the referenced entity crosswalk.
Note: 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.

Request

POST {TenantURL}/relations
Table 1. Parameters
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:
  • sendHidden - disabled by default, a relation's JSON in response will contain hidden attributes if this option is enabled.
  • partialOverride - disabled by default. If there was a relation override when a match with an existing relation is found, only attributes that are provided in a request will be updated if this option is enabled, all other attributes won’t be affected.
  • updateAttributeUpdateDates - disabled by default. If there was a relation override when a match with an existing entity is found, "singleAttributeUpdateDates" property of crosswalks will be updated for changed and new attributes if this option is present.
  • rejectRelationsToInactiveObjects - disabled by default. When this option is used, a relationship isn’t created if the start, or end object of the relationship is inactive.
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"
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
}]