Business 360 REST API Reference > Business 360 REST API > Relationship API
  

Relationship API

Use the relationship resource to filter, create, read, update, and delete business entity relationships.

Metadata API

Use the Metadata API to get the relationship_Internal_ID parameter required for the Relationship APIs. The response also contains the relationship attributes that you can include in the request body of the Create Relationship and Update Relationship APIs.
The API supports the GET method.

GET request

To get the relationship_Internal_ID parameter, submit a GET request with the following URI:
GET <baseApiURL>/metadata/api/v2/objects/relationship/?name=<>
You can use the following parameter in the request:
Parameter
Type
Description
name
String
The name of the relationship.

GET response

The response is in the JSON format. The response body contains the relationship_internal_ID parameter required for the Relationship APIs and the relationship attributes you can include in the request body of the Create Relationship and Update Relationship APIs.
Note: In the response, guid is the relationship_internal_ID parameter and name under field is a relationship attribute.

GET example

You might use the following request to get the relationship_Internal_ID parameter and relationship attributes based on the relationship name "Work for":
GET <baseApiURL>/metadata/api/v2/objects/relationship/?name=Work+for
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The sample response shows the HTTP 200 OK response code and retrieves the relationship_Internal_ID parameter and the relationship attributes:
{
"last": true,
"size": 1000,
"number": 0,
"sort": [],
"first": true,
"numberOfElements": 1,
"content": [
{
"eClass": "http://informatica.com/mdm/v2/Core#//Relationship",
"guid": "c360_person_to_c360_organization",
"storage": "hierarchy",
"name": "Work for",
"_meta": {
"eClass": "http://informatica.com/mdm/v2/Core#//Meta",
"creationDate": 1633713964007,
"lastUpdatedDate": 1634039933086,
"createdByUser": "jacobkb_mrel",
"lastUpdatedByUser": "jacobkb_mrel",
"version": 2,
"references": [
{
"eClass": "http://informatica.com/mdm/v2/Core#//
MetadataReference",
"referencePath": "//@businessEntity[guid='c360.person']",
"elementPath": "//@relationship[guid='c360_person_to_
c360_organization']/@from"
},
{
"eClass": "http://informatica.com/mdm/v2/Core#//
MetadataReference",
"referencePath": "//@businessEntity[guid='c360.organization']",
"elementPath": "//@relationship[guid='c360_person_to_
c360_organization']/@to"
}
]
},
"field": [
{
"eClass": "http://informatica.com/mdm/v2/Core#//IntegerField",
"name": "employee_number",
"description": "",
"mandatory": false,
"position": 0,
"defaultValue": 0,
"allowMany": false,
"hasDefaultValue": false,
"options": {
"eClass": "http://informatica.com/mdm/v2/Core#//FieldOptions",
"uiConfiguration": {
"eClass": "http://informatica.com/mdm/v2/Core#//
FieldUIConfiguration",
"primary": true
}
},
"label": {
"eClass": "http://informatica.com/mdm/v2/Core#//LocalizedText",
"en": "Employee Number"
}
},
{
"eClass": "http://informatica.com/mdm/v2/Core#//TextField",
"name": "details",
"description": "",
"mandatory": false,
"position": 0,
"length": 255,
"allowMany": false,
"hasDefaultValue": false,
"options": {
"eClass": "http://informatica.com/mdm/v2/Core#//FieldOptions",
"uiConfiguration": {
"eClass": "http://informatica.com/mdm/v2/Core#//
FieldUIConfiguration",
"primary": true
}
},
"label": {
"eClass": "http://informatica.com/mdm/v2/Core#//LocalizedText",
"en": "Details"
}
}
],
"label": {
"eClass": "http://informatica.com/mdm/v2/Core#//LocalizedText",
"en": "Work for"
},
"from": {
"eClass": "http://informatica.com/mdm/v2/Core#//BusinessEntityReference",
"name": "_from",
"mandatory": true,
"role": "",
"businessEntity": {
"$ref": "c360.person"
}
},
"to": {
"eClass": "http://informatica.com/mdm/v2/Core#//BusinessEntityReference",
"name": "_to",
"mandatory": true,
"role": "",
"businessEntity": {
"$ref": "c360.organization"
}
}
}
]
}

Filter Relationship

Use the Filter Relationship API to retrieve a list of business entities in a relationship.
The API supports the POST method.

POST request

To filter a relationship, submit a POST request with the following URI:
POST <baseApiURL>/business-entity/public/api/v1/relationship/<relationship_Internal_ID>/filter
You can use the following parameters in the request:
Parameter
Type
Description
relationship_Internal_ID
String
Internal ID of the relationship. To get the internal ID, use the Metadata API. For more information, see Metadata API.
You can use the following parameters in the request body:
Parameter
Type
Description
pageOffset
Integer
Number of pages to skip. For example, pageOffset=2 means that the search must skip the first two pages of the search results. Minimum value is 0.
pageSize
Integer
Number of search results to display on each page. Minimum value is 1.
filter
String
The relationship information that needs to be filtered.
_from
String
The business entity that you want to start the relationship from.
_to
String
The business entity that you want to link the relationship to.
businessEntity
String
The internal ID of the business entity.
businessId
String
Unique identifier of the business entity.

POST response

The response is in the JSON format. The response shows the list of business entities in a relationship.
The POST response includes the following parameters:
Parameter
Type
Description
first
Boolean
The first page indicator.
last
Boolean
The last page indicator.
page
Integer
The page number.
size
Integer
The requested page size.
numberOfElements
Integer
The actual number of elements on the current page.
totalNumberofElements
Integer
The total number of elements in the collection.
The POST response includes the following meta parameters:
Parameter
Type
Description
relationship
String
The internal ID of the relationship.
businessId
String
Unique identifier of the business entity relationship.
state
String
Indicates the state of the relationship. For example, indicates whether the relationship is active.
createdBy
String
Name of the person who created the relationship.
creationDate
String
Date when the relationship was created.
updatedBy
String
Name of the person who updated the relationship.
lastUpdateDate
String
Date when the relationship was last updated.

POST example

You might use the following request to filter a relationship:
POST <baseApiUrl>/business-entity/public/api/v1/relationship/colleague_of/filter
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

{
"pageoffset": "0",
"pageSize": "5",
"filter": {
"_from": {
"businessEntity": "c360.person",
"businessId": "29846697843782815893804472910"
},
"_to": {
"businessEntity": "c360.organization",
"businessId": "29843230161211928798481229322"
}
}
}
You get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

{
"first": true,
"last": true,
"page": 0,
"size": 10,
"numberOfElements": 1,
"totalNumberOfElements": 1,
"content": [
{
"employee_id": 1031,
"_from": {
"businessEntity": "c360.person",
"businessId": "29846697843782815893804472910"
},
"_to": {
"businessEntity": "c360.organization",
"businessId": "29843230161211928798481229322"
},
"_meta": {
"relationship": "c360_person_to_c360_organization",
"businessId": "30200631346953769148683291539",
"state": "ACTIVE",
"createdBy": "bjacob_PM",
"creationDate": 1637179505098,
"updatedBy": "bjacob_PM",
"lastUpdateDate": 1637179669092
}
}
]
}

Create Relationship

Use the Create Relationship API to create a relationship between two business entities.
The API supports the POST method.

POST request

To create a relationship, submit a POST request with the following URI:
POST <baseApiURL>/business-entity/public/api/v1/relationship/<relationship_Internal_ID>?sourceSystem=<sourceSystem>[&hierarchyType=<model name>][&hierarchyId=<ID of hierarchy>]
You can use the following parameters in the request:
Note: The hierarchyType and hierarchyId parameters apply only to hierarchical relationships.
Parameter
Type
Description
relationship_Internal_ID
String
Internal ID of the relationship. To get the internal ID, use the Metadata API. For more information, see Metadata API.
sourceSystem
String
Internal ID of the source system to which the relationship belongs.
hierarchyType
String
Optional. Name of the hierarchy model you want to base your hierarchy on.
hierarchyId
String
Optional. The business ID of the hierarchy model.
You can use the following parameters in the request body:
Parameter
Type
Description
_from
String
The business entity that you want to start the relationship from.
_to
String
The business entity that you want to link the relationship to.
businessEntity
String
The internal ID of the business entity.
businessId
String
Unique identifier of the business entity.

POST response

The response is in the JSON format. The response shows the HTTP 200 OK response code and retrieves the business ID of the relationship you created. When you submit a REST API request to create a relationship, Business 360 verifies your existing user role permissions and the approval workflow configuration. The response indicates whether a data steward must approve the records you created.

POST example

You might use the following request to create a relationship between two business entities:
POST <baseApiUrl>/business-entity/public/api/v1/relationship/colleague_of?sourceSystem=c360.default.system&hierarchyType=organization&hierarchyId=20142786670219119049037064968
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

{
"_from": {
"businessEntity": "c360.person",
"businessId": "30136693806248569236179512998"
},
"_to": {
"businessEntity": "c360.person",
"businessId": "30136693824695313309889064620"
}
}
In the request example, location and details are relationship attributes that you can add to the request body. For more information about relationship attributes, see Define the Data Model. You can use the Metadata API to get the relationship attributes. For more information, see Metadata API.
If no approval workflow is configured, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

{
"approvalRequired": false,
"businessId": "30142770971179375003667162584"
}
If the approval workflow is configured, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

{
"approvalRequired": true,
"businessId": "30142770971179375003667162584"
}

Note: You might use the business ID to retrieve the relationship. For more information, see Read Relationship by Business ID.

Read Relationship by Business ID

Use the Read Relationship by Business ID API to retrieve an active business entity relationship based on the business ID of the relationship.
Before you begin, you must know the business ID of the relationship. To get the business ID of a relationship, you can submit a search request.
The API supports the GET method.

GET request

To retrieve a business entity relationship, submit a GET request with the following URI:
GET <baseApiURL>/business-entity/public/api/v1/relationship/<relationship_Internal_ID>/<businessId>
The GET request contains the following path parameters:
Parameter
Type
Description
relationship_Internal_ID
String
Internal ID of the relationship. To get the internal ID, use the Metadata API. For more information, see Metadata API.
businessId
String
Unique identifier of the business entity relationship.

GET response

The response is in the JSON format. The response body contains the business entity relationship data.
The GET response includes the following _meta parameters:
Parameter
Type
Description
relationship
String
The internal ID of the relationship.
businessId
String
Unique identifier of the business entity relationship.
state
String
Indicates the state of the relationship. For example, indicates whether the relationship is active.
createdBy
String
Name of the user who created the relationship.
creationDate
String
Date when the relationship was created in the Unix epoch time format.
updatedBy
String
Name of the user who last updated the relationship.
lastUpdateDate
String
Date when the relationship was last updated.

GET examples

You might use the following request to retrieve an active relationship based on the business id 30142770971179375003667162584:
GET <baseApiURL>/business-entity/public/api/v1/relationship/colleague_of/30142770971179375003667162584
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The sample response shows the HTTP 200 OK response code and retrieves the business entity relationship that matches the specified business ID.

{
"_from": {
"businessEntity": "c360.person",
"businessId": "30136693806248569236179512998"
},
"_to": {
"businessEntity": "c360.person",
"businessId": "30136693824695313309889064620"
},
"_meta": {
"relationship": "colleague_of",
"businessId": "30142770971179375003667162584",
"state": "ACTIVE",
"createdBy": "JACOBKB_MREL",
"creationDate": 1634050073948,
"updatedBy": "JACOBKB_MREL",
"lastUpdateDate": 1634763714047
}
}
To get the content metadata, add _showContentMeta=true at the end of the request URI. You might use the following request to retrieve the active relationship with the content meta:
GET <baseApiURL>/business-entity/public/api/v1/relationship/colleague_of/30142770971179375003667162584_showContentMeta=true
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

{
"_from": {
"businessEntity": "c360.person",
"businessId": "30136693806248569236179512998"
},
"_to": {
"businessEntity": "c360.person",
"businessId": "30136693824695313309889064620"
},
"_meta": {
"relationship": "colleague_of",
"businessId": "30142770971179375003667162584",
"state": "ACTIVE",
"createdBy": "JACOBKB_MREL",
"creationDate": 1634050073948,
"updatedBy": "JACOBKB_MREL",
"lastUpdateDate": 1634763714047
},
"_contentMeta": {
"trust": {
"fieldData": [
{
"fieldRef": "/",
"lastUpdatedDate": 1634763714047,
"manualOverride": false,
"sourcePrimaryKey": "617083c2030f0f0759d5594b",
"sourceSystem": "c360.default.system",
"trustRule": "NoRule",
"trustScore": 0.0
}
]
}
}
}
For more information about content metadata, see Read content meta .

Update Relationship

Use the Update Relationship API to update an existing relationship between two business entities.
The API supports the PUT method.

PUT request

To update an existing relationship between two business entities, submit a PUT request with the following URI:
PUT <baseApiURL>/business-entity/public/api/v1/relationship/<rel_name>/<businessId>?sourceSystem=<sourceSystem>[&hierarchyType=<model name>][&hierarchyId=<ID of hierarchy>]
You can use the following parameters in the request:
Note: The hierarchyType and hierarchyId parameters apply only to hierarchical relationships.
Parameter
Type
Description
relationship_Internal_ID
String
Internal ID of the relationship. To get the internal ID, use the Metadata API. For more information, see Metadata API.
businessId
String
Unique identifier of the relationship.
sourceSystem
String
Internal ID of the source system to which the record belongs.
hierarchyType
String
Optional. Name of the hierarchy model you want to base your hierarchy on.
hierarchyId
String
Optional. The business ID of the hierarchy model.

PUT response

The response is in the JSON format. The PUT response returns HTTP 200 success code. When you submit a REST API request to update a relationship, Business 360 verifies your existing user role permissions and the approval workflow configuration. The response indicates whether a data steward must approve the relationship you updated.

PUT example

You might use the following request to update a relationship between two business entities:

PUT <baseApiUrl>/business-entity/public/api/v1/relationship/colleague_of/30142786670219119049037064968?sourceSystem=c360.default.system&hierarchyType=organization&hierarchyId=20142786670219119049037064968
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

{
"location": "North America",
"details": "New Employee",
}
Note: In the request example, location and details are relationship attributes that you can add to the request body. For more information about relationship attributes, see Define the Data Model. You can use the Metadata API to get the relationship attributes. For more information, see Metadata API.
If no approval workflow is configured, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

{
"approvalRequired": false,
}
If the approval workflow is configured, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

{
"approvalRequired": true,
}

Delete Relationship

Use the Delete Relationship API to delete a relationship between two business entities.
The API supports the DELETE method.

DELETE request

To delete a relationship, submit a DELETE request with the following URI:
DELETE <baseApiURL>/business-entity/public/api/v1/relationship/<rel_name>/<businessId>?sourceSystem=<sourceSystem>[&hierarchyType=<model name>][&hierarchyId=<ID of hierarchy>]
The DELETE request contains the following path parameters:
Note: The hierarchyType and hierarchyId parameters apply only to hierarchical relationships.
Parameter
Type
Description
relationship_Internal_ID
String
Internal ID of the relationship. To get the internal ID, use the Metadata API. For more information, see Metadata API.
businessId
String
Unique identifier of the relationship.
sourceSystem
String
Internal ID of the source system to which the record belongs.
hierarchyType
String
Optional. Name of the hierarchy model that you want to delete.
hierarchyId
String
Optional. The business ID of the hierarchy model.

DELETE example

You might use the following request to delete the active relationship based on the business ID 30142786670219119049037064968:

DELETE <baseApiURL>/business-entity/public/api/v1/relationship/colleague_of/30142786670219119049037064968?sourceSystem=c360.default.system&hierarchyType=organization&hierarchyId=20142786670219119049037064968
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
If no approval workflow is configured, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

{
"approvalRequired": false,
}
If the approval workflow is configured, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

{
"approvalRequired": true,
}