Business 360 REST API Reference > Business 360 REST API > Business entity record APIs
  

Business entity record APIs

Use the business entity record APIs to read, create, update, delete, or restore master records. These APIs use the entity resource.
Ensure that you have the required privileges to create, update, read, or delete a record.
Note: If you don't have the read privilege for a field, the response of Business Entity Record REST APIs don't include the field.
For more information about record and field privileges, see Configure field privileges for business application user roles and Configure record privileges for business application user roles

Create Master Record

Use the Create Master Record API to create a master record for a business entity.
The API supports the POST method.

POST request

To create a business entity master record, submit a POST request with the following URI:
POST <baseApiURL>/business-entity/public/api/v1/entity/<businessEntity>?sourceSystem=<sourceSystem>[&sourcePKey=<pkey>][&_resolveCrosswalk=true|false]
[&businessId=999456789222123
The following table lists the parameters that you can use in the URI:
Name
Description
businessEntity
Internal ID of the business entity for which you want to create a master record.
sourceSystem
Internal ID of the source system to which the record belongs.
sourcePKey
The primary key of the source record.
The source primary keys can contain the following characters:
~!'={}|:@#$^&*()-_+,<>?`
_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.
businessId
Unique identifier of the business entity record.
When you specify a custom business ID for records, ensure that its length doesn't match the length that the business entity uses for the business ID format. For example, if you specified 111 as the prefix and 15 as the length in the business ID format for a business entity, ensure that you don't use 111560000800000 as a custom business ID. However, you can use a custom business ID with a prefix of 111 but with a different length.
For more information about the business ID format, see Business ID format.

Request body

You must include the record details in the request body.
If a business entity field in a field group has a data quality rule, specify the _id parameter value for the field group entry that you create. For example, if the Postal Code field in the Address field group has a data quality rule, specify an ID for an address entry that you create.
For more information about data quality rules, see Configure Data Quality.

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 record you created. When you submit a REST API request to create a record, 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 master record for the c360.organization business entity:
POST <baseApiUrl>/business-entity/public/api/v1/entity/c360.organization?sourceSystem=c360.default.system&sourcePKey=pkey910&_resolveCrosswalk=true
&businessId=999456789222123
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX


{

"firstName": "Lewis",
"lastName": "Hamilton",
"middleName": "Decay",
"PostalAddress": [
{
"_id": "3d4a8f4d07cb4f0db9ea1be9bf8d27e8",
"defaultIndicator": true,
"addressType": {
"Name": "Home",
"Code": "Home"
},
"usageType": {
"Name": "Home",
"Code": "Home"
},
"addressStatus": {
"Name": "Active",
"Code": "Active"
},
"addressLine1": "789456, park road",
"country": {
"Name": "United States",
"Code": "US"
},
"state": {
"Name": "California",
"Code": "CA"
},
"city": "California"
}
],
"Phone": [
{
"_id": "f142a11b916c4a1b8239466f15852",
"phoneUsageType": {
"Name": "Home",
"Code": "Home"
},
"phoneType": {
"Name": "Mobile",
"Code": "Mobile"
},
"phoneNumber": "9900202777"
}
],
"_contentMeta": {
"trust": {
"fieldData": [
{
"fieldRef": "/",
"sourceLastUpdateDate": 1654058410000
},
{
"fieldRef": "PostalAddress[3d4a8f4d07cb4f0db9ea1be9bf8d27e8]",
"sourceLastUpdateDate": 1654058410000
},
{
"fieldRef": "Phone[f142a11b916c4a1b8239466f15852]",
"sourceLastUpdateDate": 1654839671000
}
]

}
}
}

If no approval workflow is configured, you get the following response:
HTTP/1.1 200 OK
Content-Type: application/json

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

{
"approvalRequired":true,
"id":"999456789222123",
"businessId:"999456789222123"
}
Note: You might use the business ID to retrieve the business entity master record. For more information, see Read Master Record by Business ID .

Read Master Record by Business ID

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

GET request

To retrieve a business entity master record, submit a GET request with the following URI:
GET <baseApiURL>/business-entity/public/api/v1/entity/<businessEntity>/<businessId>
The GET request contains the following parameters that you can use in the URI:
Name
Description
businessEntity
Internal ID of the business entity from which you want to retrieve the master record.
businessId
Unique identifier of the business entity record.

GET response

The response is in the JSON format. The response body contains the business entity master record data.
The GET response includes the following _meta parameters:
Name
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 who 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.
state
String
Indicates whether the record is active, inactive, or in pending state.
validation
String
Indicates the validation status of the record.
The record can have one of the following statuses:
  • - 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 active master record based on the business ID 30021755350133630729399872184:
GET <baseApiURL>/business-entity/public/api/v1/entity/c360.organization/30021755350133630729399872184 HTTP/1.1
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json
The sample response shows the HTTP 200 OK response code and retrieves the business entity master record that matches the specified business ID.
{
"name": "NewElectronics",
"numberOfEmployees": 12,
"companyType": {
"Code": "Chartered",
"Name": "Chartered"
},
"dateOfIncorporation": "2021-06-01",
"TaxDetail": [
{
"_id": "610169fa9f45df408e8caab7",
"taxNumberType": {
"Code": "ITIN",
"Name": "Individual Taxpayer Identification Number"
},
"taxNumber": "12"
}
],
"_meta": {
"businessId": "30021755350133630729399872184",
"id": "30021755350133630729399872184",
"businessEntity": "c360.organization",
"createdBy": "bejoyjacob",
"creationDate": 1627482617102,
"updatedBy": "iansmith,
"lastUpdateDate": 1627482617102,
"state": "ACTIVE"
}
}
To get the content meta, add _showContentMeta=true at the end of the request URL. You might use the following request to retrieve the Person business entity master record with the business ID MDM00000000020:
GET <baseApiURL>/business-entity/public/api/v1/entity/c360.person/MDM00000000020?_showContentMeta=true
The sample response shows the HTTP 200 OK response code and retrieves the business entity master record that matches the specified business ID. The response shows the content metadata in the _contentMeta section.

{
"firstName": "Sarvesh",
"lastName": "K",
"fullName": "Sarvesh K",
"_meta": {
"id": "MDM00000000020",
"businessEntity": "c360.person",
"businessId": "MDM00000000020",
"state": "ACTIVE",
"validation": "PASSED",
"createdBy": "shan_jan_26_2024_1",
"creationDate": 1713198564330,
"updatedBy": "shan_jan_26_2024_1",
"lastUpdateDate": 1713198565031
},
"_contentMeta": {
"trust": {
"fieldData": [
{
"fieldRef": "/",
"lastUpdatedDate": 1713198565031,
"manualOverride": false,
"sourcePrimaryKey": "661d55e49f4aec2f78096c17",
"sourceSystem": "c360.default.system",
"trustRule": "SourceRanking",
"trustScore": 0
}
]
}
}
}
For more information about content metadata, see Read content meta .

Read Master Record by SourcePKey

Use the Read Master Record by SourcePKey API to retrieve an active business entity master record associated with a particular source system and the primary key.
The API supports the GET method.

GET request

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

GET response

The response is in the JSON format. The response body contains the business entity master record data.
The GET response includes the following _meta parameters:
Name
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 person that updated the record.
lastUpdateDate
String
Date when the record was last updated.
state
String
Indicates whether the record is active, inactive, or in pending state.
validation
String
Indicates the validation status of the record.
The record can have one of the following statuses:
  • - 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 business entity master record associated with the c360.default.system source system and the ex60dd654d2d1dce73a206edd2 primary key:
GET <baseApiURL>/business-entity/public/api/v1/entity/c360.organization/c360.default.system/ex60dd654d2d1dce73a206edd2 HTTP/1.1
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json
The following sample response shows the active master record that matches the specified source name and sourcePKey:
HTTP/1.1 200 OK
IDS-SESSION-ID: sessionID
Content-Type: application/json

{
"name": "NewElectronics",
"numberOfEmployees": 12,
"companyType": {
"Code": "Chartered",
"Name": "Chartered"
},
"dateOfIncorporation": "2021-06-01",
"TaxDetail": [
{
"_id": "610169fa9f45df408e8caab7",
"taxNumberType": {
"Code": "ITIN",
"Name": "Individual Taxpayer Identification Number"
},
"taxNumber": "12"
}
],
"_meta": {
"businessId": "30021755350133630729399872184",
"id": "30021755350133630729399872184",
"businessEntity": "c360.organization",
"createdBy": "bejoyjacob",
"creationDate": 1627482617102,
"updatedBy": "iansmith",
"lastUpdateDate": 1627482617102,
"state": "ACTIVE"
}
}
To get the content metadata, add _showContentMeta=true at the end of the request URL. You might use the following request to retrieve the active master 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/610959f149cba67ca253a872?_showContentMeta=true
The sample response shows the HTTP 200 OK response code and retrieves the active master record that matches the specified source name and sourcePKey. The response shows the content metadata in the _contentMeta section.
{
"firstName":"Bhavani",
"lastName":"Shankar",
"fullName":"Bhavani Shankar",
"prefixName":{
"Code":"Dr.",
"Name":"Dr."
},
"suffixName":{
"Code":"II",
"Name":"II"
},
"title":"MR",
"designation":"QA",
"PostalAddress":[
{
"_id":"1ebb60fbf93d41518f86f79f7211c3be",
"addressType":{
"Code":"Billing",
"Name":"Billing"
},
"usageType":{
"Code":"Business",
"Name":"Business"
},
"addressStatus":{
"Code":"Active",
"Name":"Active"
},
"addressLine1":"Ali",
"country":{
"Code":"IN",
"Name":"India"
},
"state":{
"Code":"KA",
"Name":"Karnataka"
}
}
],
"_meta":{
"businessId": "30031351063540315477991729267",
"id":"30031351063540315477991729267",
"businessEntity":"c360.person",
"createdBy":"bejoyjacob",
"creationDate":1628002796882,
"updatedBy":"iansmith",
"lastUpdateDate":1628002796882,
"state":"ACTIVE"
},
"_contentMeta":{
"trust":{
"fieldData":[
{
"fieldRef":"lastName",
"lastUpdatedDate":1628002796882,
"manualOverride":false,
"sourcePrimaryKey":"610959f149cba67ca253a872",
"sourceSystem":"c360.default.system",
"trustRule":"SourceRanking",
"trustScore":1.0
},
{
"fieldRef":"prefixName",
"lastUpdatedDate":1628002796882,
"manualOverride":false,
"sourcePrimaryKey":"610959f149cba67ca253a872",
"sourceSystem":"c360.default.system",
"trustRule":"Decay",
"trustScore":0.9
},
{
"fieldRef":"/",
"lastUpdatedDate":1628002796882,
"manualOverride":false,
"sourcePrimaryKey":"610959f149cba67ca253a872",
"sourceSystem":"c360.default.system",
"trustRule":"SourceRanking",
"trustScore":1.0
}
]
}
}
}
For more information about content metadata, see Read content meta .

Update Master Record

Use the Update Master Record API to update an existing active business entity record based on the business ID that you specify.
Before you update a deleted master record, restore it by using the Restore Master Record API.
For more information about the Restore Master Record API, see Restore Master Record.
The API supports the PUT method.

PUT request

To update an active master record associated with a business ID, submit a PUT request with the following URI:
PUT <baseApiURL>/business-entity/public/api/v1/entity/<businessEntity>/<businessId>?sourceSystem=<sourceSystem>[&_resolveCrosswalk=true|false]
The PUT request contains the following parameters that you can use in the URI:
Parameter
Description
businessEntity
Internal ID of the business entity for which you want to update the master record.
businessId
Unique identifier of the business entity record.
When you specify a custom business ID for records, ensure that its length doesn't match the length that the business entity uses for the business ID format. For example, if you specified 111 as the prefix and 15 as the length in the business ID format for a business entity, ensure that you don't use 111560000800000 as a custom business ID. However, you can use a custom business ID with a prefix of 111 but with a different length.
For more information about the business ID format, see Business ID format.
sourceSystem
Internal ID of the source system to which the record belongs.
_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.
If a business entity field in a field group has a data quality rule, specify the _id parameter value for the field group entry that you create. For example, if the Postal Code field in the Address field group has a data quality rule, specify an ID for an address entry that you create.
For more information about data quality rules, see Configure Data Quality.

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 record, 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 updated.

PUT examples

The following request updates a master record for the c360.organization business entity:
PUT <baseApiUrl>/business-entity/public/api/v1/entity/c360.organization/30135099501325521983619650821?sourceSystem=c360.default.system&_resolveCrosswalk=true
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

{
"name": "NewElectronics",
"numberOfEmployees": 12,
"companyType": {
"Code": "Chartered"
},
"dateOfIncorporation": "2021-06-01",
"TaxDetail": [
{
"taxNumberType": {
"Code": "ITIN"
},
"taxNumber": "12"
}
]
}
}
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 Master Record Field

Use the Update Master Record API to add, replace, or remove a field in an existing business entity record based on the business ID that you specify.
The API supports the PATCH method.

PATCH request

To update a business entity master record associated with a business ID, submit a PATCH request with the following URI:
PATCH <baseApiURL>/business-entity/public/api/v1/entity/<businessEntity>/<businessId>?sourceSystem=<sourceSystem>[&_resolveCrosswalk=true|false]
The PATCH request contains the following parameters that you can use in the URI:
Parameter
Description
businessEntity
Internal ID of the business entity for which you want to update the master record.
businessId
Unique identifier of the business entity record.
If you specify the business ID of an inactive merged master record, the active master record, to which the inactive master record is merged, is updated.
sourceSystem
Internal ID of the source system to which the record belongs.
_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.
The PATCH request body includes the following parameters:
Parameter
Description
op
The operator that indicates the type of update. You can specify the following operators:
  • - add. Adds new data to the record.
  • - replace. Replaces the existing data.
  • - remove. Removes the data from the record.
path
The name 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 record.
Note: You can't update dynamic field values and dynamic field definitions.

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 record, 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 updated.

PATCH examples

The following request updates the first name of a person to Marko:
PATCH <baseApiUrl>/business-entity/public/api/v1/entity/c360.person/30007167057089073281821852231?sourceSystem=c360.default.system&_resolveCrosswalk=true
Content-Type: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX


[
{
"op":"replace",
"path":"firstName",
"value":"Marko"
}
]
The following request adds a postal address, replaces a postal address, and removes a postal address:
[{
"op": "add",
"path": "PostalAddress",
"value": {
"_id": "60f01672b9bac05632a3111111",
"addressLine1": "Nikola Tesla Avenue",
"country": {
"Code": "US",
"Name": "America"
},
"state": {
"Code": "CA",
"Name": "California"
}
}
},
{
"op": "replace",
"path": "PostalAddress[1ebb60fbf93d41518f86f79f7211c3be]",
"value": {
"_id": "1ebb60fbf93d41518f86f79f7211c3be",
"addressLine1": "Cambie Street",
"country": {
"Code": "US",
"Name": "America"
}
}
},
{
"op": "remove",
"path": "PostalAddress[60f01672b9bac05632a3d522]"
}
]
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
}

Read Source Records by Master Record

Use the Read Source Records by Master Record API to identify all the source records that contribute to a master record.
Before you begin, you must know the business ID of the master record. To get the business ID of a master record, you can submit a search request.
The API supports the GET method.

GET request

To get the source records that contribute to a master record, submit a GET request with the following URI:
GET <baseApiURL>/business-entity/public/api/v1/entity-member/<businessEntity>/<businessId>
The GET request contains the following parameters that you can use in the URI:
Parameter
Description
businessEntity
Internal ID of the business entity to which the master record belongs.
businessId
Unique identifier of the master record whose source records you want to retrieve.

GET response

The response is in the JSON format. The response body contains the source records that contribute to the specified master record.
Name
Type
Description
sourcePKey
String
Primary source key of the source record.
sourceSystem
String
Unique identifier of the source system for the source record.

GET examples

You might use the following request to retrieve the business entity source member records based on the business ID MDM0000007QMV4:
GET <baseURL>/business-entity/public/api/v1/entity-member/c360.person/
MDM0000007QMV4
The sample response retrieves the source records that contribute to the master record that matches the specified business ID.
{
"content": [
{
"sourcePKey": "ex62854adaf03192610b6ad9c0",
"sourceSystem": "c360.default.system"
},
{
"sourcePKey": "ex628547194fa64531c105625f",
"sourceSystem": "c360.default.system"
},
{
"sourcePKey": "001",
"sourceSystem": "microsoft"
},
{
"sourcePKey": "ex628549c94fa64531c105631c",
"sourceSystem": "c360.default.system"
},
{
"sourcePKey": "001",
"sourceSystem": "salesforce"
}
]
}

Delete Master Record

Use the Delete Master Record API to delete an active master record based on the business ID of the record. The API doesn't permanently delete the record from the data store, and you can search for the deleted record.
The API supports the DELETE method.

DELETE request

To delete a business entity master record, submit a DELETE request with the following URI:
DELETE <baseApiURL>/business-entity/public/api/v1/entity/<businessEntity>/<businessId>?sourceSystem=<source_system>
Use the following parameters in the DELETE request:
Parameter
Description
businessEntity
Internal ID of the business entity for which you want to delete the master record.
businessId
Unique identifier of the master record.
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 master record based on the business ID:
DELETE <baseApiURL>/business-entity/public/api/v1/entity/c360.person/MDM0000007DK79?sourceSystem=c360.default.system
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 Master Record

Use the Restore Master Record API to restore a deleted master record. You can restore a deleted master record if it has at least one active source record.
The API supports the PUT method.

PUT request

To restore a deleted master record, submit a PUT request with the following URI:
PUT <baseApiURL>/business-entity/public/api/v1/entity/<businessEntity>/<businessId>?sourceSystem=<source_system>&_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 a deleted master record.
businessId
Unique identifier of the deleted master record that you want to restore.
sourceSystem
Internal ID of the source system that the record belongs to.
_operationType
Type of operation that you want to perform on the deleted master record. The supported value is restore.

Request body

You must include a blank request body {} for the PUT request to succeed.

PUT response

The PUT response returns the HTTP 200 success code. When you submit a REST API request to restore a master 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

To restore a deleted master record, you can submit the following request:
PUT <baseApiURL>/business-entity/public/api/v1/entity/c360.person/MDM0000007DK79?sourceSystem=c360.default.system&_operationType=restore
Include a blank request body in the following format:
{}
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,
}