Use the business entity record APIs to read, create, update, delete, or restore business entity master records. These APIs use the entity resource.
Note: Effective in the July 2023 release, the response of the read master record by business ID and read master record by SourcePKey APIs include the validation statuses that are available for preview.
Preview functionality is supported for evaluation purposes but is unwarranted and is not supported in production environments or any environment that you plan to push to production. Informatica intends to include the preview functionality in an upcoming release for production use, but might choose not to in accordance with changing market or technical circumstances. For more information, contact Informatica Global Customer Support.
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.
_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.
You can use one of the following formats for business IDs:
- Alphanumeric. Use 14 characters that include the prefix MDM, such as MDM4AB78YU2WE2.
- Numeric. Use 15 to 24 characters that include a three-digit prefix. For example, 999 is the prefix in the ID 999456789222123. You can select any three digits for the prefix.
Ensure that you don't use a prefix that's the same as the prefix specified in the business ID format property of any business entity. For example, if a business entity uses 111 as the prefix, don't use 111560008 as the custom business ID.
For more information about business entity properties, see Defining the Data Model.
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
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.
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
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.
Use the Update Master Record API to update an existing active business entity record based on the business ID that you specify.
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 master record that you want to update.
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
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
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:
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:
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:
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: