Relations API

Relationships, as well as entities, are the building blocks of the relationship graph. These are links between objects (entity-entity or relationship-entity). You can define different types of relationships and their taxonomies in the Business Model (for example, Spousal (family), Employment (professional), or Friend (affiliate) relationship types). As for entities, we support the "catchAll" bucket.

Relationship types can be categorized based on the following criteria:

Based on usability, relationship types are of the following types:
- Implicit- The relationships that enable you to build entity reference attributes.
- Explicit- The relationships which you want to track in a graph.

Based on direction relationships can be directed, undirected, bidirectional, or, self-pointing (an entity to itself).

Relationships can have attributes and tags assigned to them. For example, there is an Employment relationship between an Individual and an Organization. This relationship can have a Title attribute.

Table 1. Relationship Object
Property	Description	Type
`URI`	Path that is used to reach a relation object. Format: `relations/{relation_id}` Example: `relations/r1`	String, URI
`type`	Relationship type. Example: `configuration/relationTypes/Employment`	String, Relation Types URI
`startObject`	Entity declared as the start object of the relationship. Contains properties: start object URI object type object label (displayable name of the rel type) label for the relationship, from the start object's perspective Example: `{ "URI":"relations/r1/startObject", "objectURI":"entities/e1", "type":"configuration/entityTypes/Individual", "label":"John Smith", "directionalLabel":"employee"}`	JSON Object
`endObject`	End object of a relationship. Contains properties: end object URI object type object label (displayable name of the rel type) label for the relationship, from the end object's perspective Example: `{` `"URI":"relations/r1/endObject", "objectURI":"entities/e2", "type":"configuration/entityTypes/Organization", "label":"Super Company", "directionalLabel":"employer"` `}`	JSON Object
`attributes`	Attributes that relationship object has-this includes simple, nested attributes. Each attribute has a reference to its configuration type. Attributes are grouped by attribute configuration. Example: `{ "URI": "relations/r1/attributes", "Title":[ { "URI": "relations/r1/attributes/Title/1", "type": "configuration/relationTypes/Employment/attributes/Title", "value":"CEO" } ]}`	Array of Attributes
`crosswalks`	These are crosswalks to source systems and data in these source systems that are associated with an object.
`createdBy`	User who created the object.	UTC timestamp, ms
`createdTime`	Timestamp when record was created, in milliseconds.	UTC timestamp, ms
`updatedTime`	Timestamp when record was most recently updated, in milliseconds.	UTC timestamp, ms
`startDate`	This is an optional property that represents the date from which an object starts being `Active`. From that day onwards, a relation is considered as `Active` and can start connecting two objects.	UTC timestamp, ms (13 digit long value)
`endDate`	This is an optional property that represents the date on which an object was marked `Inactive`. This property serves the same purpose as the `soft-delete` functionality. This means that from the `endDate`, a relation becomes `Inactive` and stops connecting two objects. Also, the reference attributes are no longer visible based on this relation.	UTC timestamp, ms (13 digit long value)

Note:

If you are processing messages using message streaming, to identify the latest event amongst several events for an object, use the objectVersion property. The objectVersion property identifies the message with the latest object state. For more information, see CRUD events.
You cannot use the timestamp in the createdTime and updatedTime properties since it is only used to indicate the start of the operation that creates or updates the object record. The timestamp does not indicate the time when the object record is committed to the database. When two or more operations are executed simultaneously, the updatedTime property may not reflect the latest object state if one operation started earlier than the other but is not committed to the database immediately. For more information, see Message streaming.
If the startDate option is later than the endDate option, then the END_DATE_EARLIER_THEN_START(600) exception is displayed. For more information on overwriting of endDate, startDate, and tags, see Retrieve or modify the entity startDate and endDate.

Relationship Object Example

{
   "URI":"relations/r1",
   "type":"configuration/relationTypes/Employment",
   "createdTime":1351899105569,
   "createdBy":"admin",
   "updatedTime":1353933493738,
   "updatedBy":"fadler",
   "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"
         ]
      }
   ]
}

Self Pointing Relationships

Normally you use a crosswalk to define a relationship between one entity and another. Occasionally, you need to define a relationship between a given entity and itself. This example is an entity that needs to ship to itself. The API supports requests such as:

{
   "type":"configuration/relationTypes/HasShipTo",
   "crosswalks":[
      {
         "type":"configuration/sources/HCS",
         "value":"HasShipTo_HCS_00370257_00370257"
      }
   ],
   "startObject":{
      "crosswalks":[
         {
            "type":"configuration/sources/HCS",
            "value":"00370257"
         }
      ]
   },
   "endObject":{
      "crosswalks":[
         {
            "type":"configuration/sources/HCS",
            "value":"00370257"
         }
      ]
   }
}

This relationType defines a crosswalk that has the same startObject as the endObject. This example is based on an entity that needs to ship a product to itself. In this way you can define self-pointing objects.

Note: Reference attributes for the relations of the same type are not supported.

Supported Operations

Note: All Data API requests must be signed with an access token. For more information, see Authentication API.

Unify and manage your data

Relations API

Self Pointing Relationships

Supported Operations

Footer