Business 360 REST API Reference > Business 360 REST API > Source record API
  

Source record API

Use the source record API to read, update, delete, or restore a source record based on the business entity, source system, and the primary key. The API uses the entity-xref resource.

Read Source Record

Use the Read Source Record API to retrieve a business entity source record based on the source system and the primary key of the record that you specify.
The API supports the GET method.

GET request

To retrieve a source record, submit a GET request with the following URI:
GET <baseApiURL>/business-entity/public/api/v1/entity-xref/<businessEntity>/<sourceSystem>/<sourcePKey>[&_resolveCrosswalk=true|false]
The GET request contains the following parameters:
Parameter
Description
businessEntity
Internal ID of the business entity for which you want to retrieve the source record.
sourceSystem
Internal ID of the source system to which the record belongs.
sourcePKey
The primary key of the source record.
_resolveCrosswalk
Indicates whether to standardize picklist values based on the source system configuration.
Set to true to standardize the picklist values. When you specify this parameter, you must set the sourceSystem parameter.
Default is false.
For more information about standardizing picklist values, see Define Source Systems.

GET response

The response is in the JSON format. The response body contains the business entity source record data.
The GET response includes the following _meta parameters:
Parameter
Type
Description
businessId
String
Unique identifier of the business entity record.
id
String
Unique identifier of the business entity record. Do not use.
businessEntity
String
Internal ID of the business entity from which you retrieved the master record.
createdBy
String
Name of the person that created the record.
creationDate
String
Date when the record was created.
updatedBy
String
Name of the user who last updated the record.
lastUpdateDate
String
Date when the master record was last updated.
sourceLastUpdatedDate
String
Date when the source record was last updated.
states
String
The different statuses of the active source record.
Source records can have the following statuses:
  • - base. The current status of the source record. The base value is ACTIVE.
  • - consolidation. The status of the source record in the match and merge process.
    • - MATCH_DIRTY. Indicates that the source record is a new record that didn't undergo the match process.
    • - MATCH_INDEXED. Indicates that the record is indexed and can be matched. During indexing, match candidates are generated for use in the match process.
    • - MATCHED. Indicates that the record is matched and ready to be merged.
    • - CONSOLIDATED. Indicates that the source record is merged, determined to be unique, and represents the best version of the truth.
  • - searchIndex. Indicates that the record is in a SEARCH_DIRTY state and is not searchable. In the current release, source records are not searchable.
  • - validation. Indicates the validation status of the record.
    • - PENDING. Indicates that the record is not yet validated.
    • - PASSED. Indicates that the record is validated and has no errors.
    • - FAILED. Indicates that the record is validated and has validation and data quality errors.

GET examples

You might use the following request to retrieve the source record for the Person business entity associated with the c360.default.system source system and the primary key 611d13e9e6dbd16ffa69a143:
GET <baseApiUrl>/business-entity/public/api/v1/entity-xref/c360.person/c360.default.system&_resolveCrosswalk=true/611d13e9e6dbd16ffa69a143 HTTP/1.1
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json
The GET response returns HTTP 200 success code and retrieves the matching source record.
HTTP/1.1 200 OK
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

{
"firstName":"john",
"lastName":"hedge",
"fullName":"john hedge",
"prefixName":{
"Code":"Dr.",
"Name":"Dr."
},
"_meta":{
"businessId":"30007199962170814218819710935",
"id":"30007199962170814218819710935",
"businessEntity":"c360.person",
"createdBy":"bejoyjacob",
"creationDate":1626693564993,
"updatedBy":"iansmith",
"lastUpdateDate":1626694724610,
"states":{
"base":"ACTIVE",
"consolidation":"MATCH_INDEXED",
"searchIndex":"SEARCH_DIRTY"
},
"sourceSystem":"c360.default.system",
"sourcePrimaryKey":"611d13e9e6dbd16ffa69a143",
"xrefType":"DATA"
}
}
To get the content metadata, add _showContentMeta=true at the end of the request URL. You might use the following request to retrieve the source record for the Person business entity, which is associated with the c360.default.system source system and the 610959f149cba67ca253a872 primary key:
GET <baseApiUrl>/business-entity/public/api/v1/entity-xref/c360.person/c360.default.system&_resolveCrosswalk=true/610959f149cba67ca253a872?_showContentMeta=true
The sample response shows the HTTP 200 OK response code and retrieves the source record that matches the specified source name and sourcePKey. The response shows the content metadata in the _contentMeta section.
{
"PhoneCommunication": [
{
"_id": "pkeyPhone03",
"phoneNumber": "9900201000",
"phoneType": {
"Code": "Cell",
"Name": "Cell"
}
}
],
"PostalAddress": [
{
"_id": "padd061",
"addressLine1": "Bagmane Tech Park",
"addressLine2": "CV Raman Nagar",
"addressLine3": "Bengaluru",
"city": "Bangalore",
"country": {
"Code": "US",
"Name": "United States"
},
"state": {
"Code": "AK",
"Name": "Alaska"
}
}
],
"name": "Informatica",
"numberOfEmployees": 5555,
"_meta": {
"id": "MDM0000005CWG0",
"businessId": "MDM0000005CWG0",
"businessEntity": "c360.organization",
"createdBy": "c360_delta_automation_org_Target",
"creationDate": 1662452659261,
"updatedBy": "c360_delta_automation_org_Target",
"lastUpdateDate": 1662452659261,
"states": {
"base": "ACTIVE",
"consolidation": "MATCH_INDEXED",
"searchIndex": "SEARCH_DIRTY"
},
"sourceSystem": "sals_bid",
"sourcePrimaryKey": "pkey190",
"xrefType": "DATA"
},
"_contentMeta": {
"trust": {
"updateCount": 1,
"fieldData": [
{
"fieldRef": "PostalAddress[padd061]",
"lastUpdatedDate": 1662452659261,
"downgradeTrustScorePercent": 0.0,
"sourceLastUpdatedDate": 1656996071000
},
{
"fieldRef": "PhoneCommunication[pkeyPhone03]",
"lastUpdatedDate": 1662452659261,
"downgradeTrustScorePercent": 0.0,
"sourceLastUpdatedDate": 1657428071000
},
{
"fieldRef": "/",
"lastUpdatedDate": 1662452659261,
"downgradeTrustScorePercent": 0.0,
"sourceLastUpdatedDate": 1657428071000
}
]
}
}
}



For more information about content meta, see Read content meta .

Update Source Record

Use the Update Source Record API to update a business entity source record based on the source system and the primary key of the record that you specify. If you try to update a deleted source record, the API first restores it and then updates it.
The API supports the PUT method.

PUT request

To update a source record, submit a PUT request with the following URI:
PUT <baseApiURL>/business-entity/public/api/v1/entity-xref/<businessEntity>/<sourceSystem>/<sourcePKey>[?_forceUpdate=true|false][&_resolveCrosswalk=true|false][&notReadyForMatch=true|false]
The PUT request contains the following parameters:
Parameter
Description
businessEntity
Internal ID of the business entity for which you want to update the source record.
sourceSystem
Internal ID of the source system to which the source record belongs.
sourcePKey
The primary key of the source record.
The source primary keys can contain the following characters:
~!'={}|:@#$^&*()-_+,<>?`
_forceUpdate
Optional. Specifies whether to force update existing records irrespective of their source last updated dates. Default is false.
_resolveCrosswalk
Optional. Indicates whether to standardize picklist values based on the source system configuration.
To standardize the picklist values, set to true. If set to true, ensure that the picklist values belong to a code list that's part of a crosswalk.
Default is false.
For more information about standardizing picklist values, see Define Source Systems.
notReadyForMatch
Optional. Specifies whether a source record can participate in the match process.
Default is false.

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 source record, Business 360 verifies your existing user role permissions and the approval workflow configuration. The response indicates whether a data steward must approve the source records you updated.

PUT example

The following request force updates a record that belongs to the Person business entity associated with the c360.default.system source system:
PUT <baseApiUrl>/business-entity/public/api/v1/entity-xref/c360.person/c360.default.system/pkey600?_forceUpdate=true&_resolveCrosswalk=true&notReadyForMatch=true
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
{
"firstName":"john",
"lastName":"smith",
"middleName":"hedge",
"title":"F1 Driver",
"designation":"Aston Martin",
"PostalAddress":[
{
"_id":"0dec181346114a6196d1313ca135bcee",
"defaultIndicator":true,
"addressType":{
"Name":"Home",
"Code":"Home"
},
"usageType":{
"Name":"Home",
"Code":"Home"
},
"addressStatus":{
"Name":"Active",
"Code":"Active"
},
"addressLine1":"7777, park road",
"country":{
"Name":"United States",
"Code":"US"
},
"state":{
"Name":"California",
"Code":"CA"
},
"city":"BLR"
},
{
"_id":"1dec181346114a6196d1313ca135bcee",
"defaultIndicator":true,
"addressType":{
"Name":"Home",
"Code":"Home"
},
"usageType":{
"Name":"Home",
"Code":"Home"
},
"addressStatus":{
"Name":"Active",
"Code":"Active"
},
"addressLine1":"7777, park road",
"country":{
"Name":"United States",
"Code":"US"
},
"state":{
"Name":"California",
"Code":"CA"
},
"city":"MYS"
}
],
"Phone":[
{
"_id":"5d14a94931db4515857465c950f9b997",
"phoneUsageType":{
"Name":"Home",
"Code":"Home"
},
"phoneType":{
"Name":"Mobile",
"Code":"Mobile"
},
"phoneNumber":"9900223344"
}
],
"_contentMeta":{
"trust":{
"fieldData":[
{
"fieldRef":"/",
"sourceLastUpdateDate":1654836010000 // An earlier source last updated date
},
{
"fieldRef":"PostalAddress[0dec181346114a6196d1313ca135bcee]",
"sourceLastUpdateDate":1657428010000
},
{
"fieldRef":"PostalAddress[1dec181346114a6196d1313ca135bcee]",
"sourceLastUpdateDate":1657428010000
},
{
"fieldRef":"Phone[5d14a94931db4515857465c950f9b997]",
"sourceLastUpdateDate":1657428010000
}
]
}
}
}
If the _forceUpdate parameter isn't set to true, you get the following response:
{
"path":"PostalAddress[0dec181346114a6196d1313ca135bcee]",
"errorCode":"BES.00092.4",
"message":"Cannot update the field group with a sourceLastUpdateDate value older or equal to the sourceLastUpdateDate value in the existing record.",
"localizedMessage":"Cannot update the field group with a sourceLastUpdateDate value older or equal to the sourceLastUpdateDate value in the existing record."
}
Note: You can't force update a record if the source last updated date is later than current system date.
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
}

Update Source Record Field

Use the Update Source Record Field API to add, replace, or remove a field in a business entity source record based on the source system and the primary key of the record that you specify.
The API supports the PATCH method.
To update values of root fields, ensure that you specify all the fields in the root section.
To update values of fields in a field group, ensure that you specify only the fields that you want to update.
Note: If you specify all the fields in the request, the Update Source Record Field API overwrites the other field values.

PATCH request

To update a business entity source record associated with a business ID, submit a PATCH request with the following URI:
PATCH <baseApiURL>/business-entity/public/api/v1/entity-xref/<businessEntity>/<sourceSystem>/<sourcePKey>[?_forceUpdate=true|false][&_resolveCrosswalk=true|false][&notReadyForMatch=true|false]
You can use the following parameters in the request:
Parameter
Description
businessEntity
Internal ID of the business entity for which you want to update the source record.
sourceSystem
Internal ID of the source system to which the source record belongs.
sourcePKey
The primary key of the source record.
_forceUpdate
Specifies whether to force update existing records irrespective of their source last updated dates. Default is false.
_resolveCrosswalk
Indicates whether to standardize picklist values based on the source system configuration.
To standardize the picklist values, set to true. If set to true, ensure that the picklist values belong to a code list that's part of a crosswalk.
Default is false.
For more information about standardizing picklist values, see Define Source Systems.
notReadyForMatch
Specifies whether a source record can participate in the match process.
Default is false.
You can use the following parameters in the request body:
Parameter
Description
op
The operator that indicates the type of update.
You can specify the following operators:
  • - add. Adds new data to the record.
    • Use the add operator when you add a root field or a field group to a record.
  • - replace. Replaces the existing data.
    • Use the replace operator when you update a root field or a field group of a record.
  • - remove. Removes the data from the source record.
  • - setSourceLastUpdateDate. Sets the last updated date for a root or a field group of a source record.
path
The internal ID of the field you want to update.
Note: If the field contains multiple values, specify the name and the internal ID of the field. For example, the Postal Address field contains multiple values.
value
Contains the values that you want to use to update the source record.

PATCH response

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

PATCH example

The following request force updates the first name, last name, and the source last updated date in the business entity source record:

PATCH <baseApiUrl>/business-entity/public/api/v1/entity-xref/c360.person/c360.default.system/pkey3132?_forceUpdate=true&_resolveCrosswalk=true&notReadyForMatch=true
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

[
{ "op": "replace", "path": "firstName", "value": "john" },
{ "op": "replace", "path": "lastName", "value": "hedge" },
{ "op": "setSourceLastUpdateDate", "path": "/",
"value": 1668487210000 // An earlier source last updated date
}
]

If the _forceUpdate parameter isn't set to true, you get the following response:
{
"path":"PostalAddress[0dec181346114a6196d1313ca135bcee]",
"errorCode":"BES.00092.4",
"message":"Cannot update the field group with a sourceLastUpdateDate value older or equal to the sourceLastUpdateDate value in the existing record.",
"localizedMessage":"Cannot update the field group with a sourceLastUpdateDate value older or equal to the sourceLastUpdateDate value in the existing record."
}
Note: You can't force update a record if the source last updated date is later than current system date.
The following request updates phone number and phone type fields in the phone field group of a business entity source record:
[
{
"op": "replace",
"path": "Phone[cc0c54d2f59d477dabede70b3e040119].phoneNumber",
"value": "9080908090"
},
{
"op": "replace",
"path": "Phone[cc0c54d2f59d477dabede70b3e040119].phoneType",
"value": {
"Name": "Cell",
"Code": "Cell"
}
}
]
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
}
The following request updates the values of the address line 1 and city fields in the postal address field group of a business entity source record:
[
{
"op": "replace",
"path": "PostalAddress[0dec181346114a6196d1313ca135bcee]",
"value": {
"addressLine1": "Plaza200",
"city": "chennai"
}
}
]
Note: The request removes the other field values in the field group and updates the address line 1 and city field values.
The following request updates specific field values in the postal address field group of a business entity source record without removing the other field values of the field group:
[
{
"op": "replace",
"path": "PostalAddress[0dec181346114a6196d1313ca135bcee].addressLine1",
"value": "Plaza200"
},
{
"op": "replace",
"path": "PostalAddress[1dec181346114a6196d1313ca135bcee].city",
"value": "mumbai"
}
]
The following request removes the postal address field group of a business entity source record:
{
"op": "remove",
"path": "PostalAddress[60f01672b9bac05632a3d522]"
}
Note: Ensure that you specify the field group name and ID in the path.
The following request removes the city field value in the postal address field group of a business entity source record:
{
"op": "remove",
"path": "PostalAddress[60f01672b9bac05632a3d522].city"
}
Note: Ensure that you specify the field group name, ID, and the field name in the path.

Delete Source Record

Use the Delete Source Record API to delete a source record based on the primary key of the source record. The API doesn't permanently delete the record from the data store, and you can search for the associated master record to view the deleted source record.
The API supports the DELETE method.

DELETE request

To delete a source record, submit a DELETE request with the following URI:
DELETE <baseApiURL>/business-entity/public/api/v1/entity-xref/<businessEntity>/<sourceSystem>/<sourcePKey>
Use the following parameters in the DELETE request:
Parameter
Description
businessEntity
Internal ID of the business entity for which you want to delete the source record.
sourcePKey
The source primary key of the record that you want to delete.
sourceSystem
Internal ID of the source system that the record belongs to.

DELETE response

The DELETE response returns the HTTP 200 success code. When you submit a REST API request to delete a record, MDM SaaS verifies the permissions of your user role and the approval workflow configuration. The response indicates whether the deletion request requires an approval.
If no approval workflow is configured for your user role, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

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

{
"approvalRequired":true
}

DELETE example

You can use the following request to delete an active source record based on the source primary key:
DELETE https://qa-pod1-mdm.mrel.infaqa.com/business-entity/public/api/v1/entity-xref/c360.person/HRSource/SFDC_567
If no approval workflow is configured, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

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

{
"approvalRequired": true,
}

Restore Source Record

Use the Restore Source Record API to restore a deleted source record.
The API supports the PUT method.

PUT request

To restore a source record, submit a PUT request with the following URI:
PUT <baseApiURL>/business-entity/public/api/v1/entity-xref/<businessEntity>/<sourceSystem>/<sourcePKey>[?_operationType=restore]
Use the following parameters in the PUT request :
Parameter
Description
businessEntity
Internal ID of the business entity for which you want to restore the deleted source record.
sourcePKey
The source primary key of the record that you want to restore.
sourceSystem
Internal ID of the source system that the record belongs to.
_operationType
Optional. Type of operation that you want to perform on the deleted source record. The supported value is restore.
If you don't specify the operation type, the API restores and updates the source record.

Request body

If you set the _operationType parameter to restore, you must include a request body that's blank {} for the PUT request to succeed. If you specify any values in the request body, the values are ignored.
If you don't specify the _operationType parameter and include a request body with field values, the request first restores the source record and then updates the field values that you specify in the request body.

PUT response

The PUT response returns the HTTP 200 success code. When you submit a REST API request to restore a source record, MDM SaaS verifies the permissions of your user role and the approval workflow configuration. The response indicates whether the restore request requires an approval.
If no approval workflow is configured for your user role, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

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

{
"approvalRequired":true
}

PUT example

If you specify the _operationType parameter to restore a deleted source record, you can submit the following request:
PUT <baseApiURL>/business-entity/public/api/v1/entity/c360.person/HRSource/SFDC_148?_operationType=restore
Include a blank request body in the following format:
{}
If you don't specify the _operationType parameter, you can use the following request:
PUT <baseApiURL>/business-entity/public/api/v1/entity/c360.person/HRSource/SFDC_148

Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
{
"firstName":"Tom",
"lastName":"smith",
"middleName":"H",
"title":"Sales",
"designation":"Manager",

"Phone":[
{
"_id":"5d14a94931db4515857465c950f9b997",
"phoneUsageType":{
"Name":"Home",
"Code":"Home"
},
"phoneType":{
"Name":"Mobile",
"Code":"Mobile"
},
"phoneNumber":"9900223344"
}
]

}
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,
}