IBM Match 360 with Watson | IBM Cloud API Docs

Introduction

Last updated: 2022-11-14

IBM Match 360 with Watson on IBM Cloud Pak for Data provides APIs that enable you to connect the IBM Match 360 with Watson service's powerful master data matching capabilities to your systems and processes. IBM Match 360 with Watson (IBM Match 360) enables you to establish a single, trusted, 360-degree view of your customers. IBM Match 360 includes machine learning-assisted, self-service analytics and matching tools that deliver better business insights.

Business users and systems can access IBM Match 360 data to search, view, and analyze master data entities. With IBM Match 360 on Cloud Pak for Data, you can ensure that your users and systems have a total view of your data. With a seamlessly integrated, cross-solution experience, your users can discover master data directly in the space where they expect to consume it.

The IBM Match 360 with Watson APIs support:

Loading and mapping data
Customizing the data model
Configuring the matching algorithm
Running matching
Retrieving master data entity and record details
MDM job management

Important: This reference documentation is for the v1 API, which applies to IBM Match 360 with Watson for Cloud Pak for Data 4.0.1 and above.

For more information about IBM Match 360 with Watson on Cloud Pak for Data, see the service's documentation in the IBM Cloud Pak for Data documentation.

Service endpoint

The IBM Match 360 with Watson service endpoint is based on your Cloud Pak for Data deployment URL.

https://<CPD_CLUSTER_HOST>:<PORT>/mdm/model/

For example, if your instance is deployed at https://www.example.com:31843, you can access the IBM Match 360 APIs at https://www.example.com:31843/mdm/model/.

Additionally, you can access, discover, and run API commands with the Swagger UI API Explorer at the URL https://<CPD_CLUSTER_HOST>/<MDM_INSTANCE_ID>/api-model/explorer/#. For example, using the same instance host as in the previous example and an instance ID of 1664447707275339, you can access the Swagger UI API Explorer IBM Match 360 APIs at https://www.example.com/1664447707275339/api-model/explorer/#.

Example

curl -H "Authorization: Bearer {token}" -X {request_method} "https://<CPD_CLUSTER_HOST>:<PORT>/mdm/model/<METHOD>"

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`202`	Accepted	The request was understood and accepted. Processing will continue in the background.
`202`	No Content	The request was successful. No content will be returned.
`400`	Bad Request	The input parameters in the request are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access the resource. Contact the account owner to check your permissions.
`404`	Not Found	The requested resource could not be found.
`405`	Method Not Allowed	The request is not allowed for the requested resource.
`408`	Request Timeout	The connection to the server timed out. Wait a few minutes, then try again.
`409`	Conflict	The entity is already in the requested state.
`410`	Gone	The requested resource is no longer available and will not become available in the future.
`500`	Internal Server Error	Your request could not be processed due to an internal error. Check server logs for more details.
`503`	Service Unavailable	The requested service is currently unavailable. Wait a few minutes and try again.

ErrorResponse

Name	Description
code `integer`	HTTP error code.
error `string`	Human-readable error string, like 'Invalid image file'.

ErrorAuthentication

Name	Description
status `string`	The status of error.
statusInfo `string`	Information about the error.

ErrorHTML

Name	Description
Error `string`	HTML description of the error.
statusInfo `string`	Information about the error.

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Name	Description
code `integer`	HTTP status code.
description `string`	Human-readable error description. For example, `File size limit exceeded`.
error_id `string`	Codified error string. For example, `limit_exceeded`.

The Java SDK generates an exception for any unsuccessful method invocation. All methods that accept an argument can also throw an IllegalArgumentException.

Exception	Description
IllegalArgumentException	An invalid argument was passed to the method.

When the Java SDK receives an error response from the IBM Match 360 service, it generates an exception containing the following fields:

Field	Description
statusCode	The HTTP status code returned
message	A message describing the error

The Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the IBM Match 360 service, it generates an exception containing the following fields:

Field	Description
code	The HTTP status code returned
message	A message describing the error
info	A dictionary of additional information about the error

Example error handling

try {
    // Invoke a IBM Match 360 method
} catch (NotFoundException e) {
    // Handle Not Found (404) exception
} catch (RequestTooLargeException e) {
    // Handle Request Too Large (413) exception
} catch (ServiceResponseException e) {
    // Base class for all exceptions caused by error responses from the service
    System.out.println("Service returned status code " + e.getStatusCode() + ": " + e.getMessage());
}

Authentication

To authenticate to the API, you must pass an IBM Cloud Pak for Data service instance token in an Authorization header. You can retrieve the instance token by viewing the service instance details in the Cloud Pak for Data web interface or using the the /zen-data/v2/serviceInstance/users API.

Service instance tokens expire 20 minutes after creation.

To obtain a service instance token and authorize your IBM Match 360 with Watson API calls, complete the following steps:

Grant users access to IBM Match 360.
Retrieve the platform token.
Retrieve the service instances associated with the platform token.
Obtain a service instance token by providing your service instance ID.
Use the service instance token to authorize your IBM Match 360 API calls.

Granting users access to IBM Match 360

You can grant users access to IBM Match 360 in two ways:

With the Cloud Pak for Data web interface.
With the the /zen-data/v2/serviceInstance/users API.

Users must be assigned one of the following roles:

Data Engineer - Data Engineer users have full rights to configure a IBM Match 360 service instance, onboard data sources, customize the data model, customize the matching algorithm, run matching, view or create jobs, complete pair analysis tasks, and view or edit entities and records in the master data explorer.
Data Steward - Data Steward users can onboard data sources, run matching, view the data model, view ongoing jobs, complete pair analysis tasks, and view or edit entities and records in the master data explorer.
Publisher User - The Publisher User role is used primarily to publish data from an IBM InfoSphere® Master Data Management instance, through the MDM Publisher tool, into IBM Match 360. Publisher Users can onboard data sources, customize the data model, and view or create jobs.
Entity Viewer - Entity Viewer users have read-only permission in an IBM Match 360 instance. They can view the master data, the model, the results of matching, and ongoing jobs. They can also complete pair analysis tasks.

Granting access to users with the Cloud Pak for Data web interface

To grant access to users by using the Cloud Pak for Data web interface:

Log into the Cloud Pak for Data web interface.
Navigate to My Instances, then select the specified instance.
Click the Manage access option.
If the user is not listed on the manage access page:
- Select the Add users option.
- Select the specified users and select the role of Data Engineer, Data Steward, Publisher User, or Entity Viewer.
- Click Add to complete the role assignment.
If the user is already listed on the manage access page:
- Hover over the specified user and select the Edit option.
- Select the role of Data Engineer, Data Steward, Publisher User, or Entity Viewer.
- Click Save to complete the role assignment.

Granting access to users with the Cloud Pak for Data API

To grant access to users by using the /zen-data/v2/serviceInstance/users API, first run the following curl command to get all users present in Cloud Pak for Data:

curl -k -X GET https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/users -H 'authorization: Bearer <PLATFORM_TOKEN>'

Then use the /zen-data/v2/serviceInstance/users API to assign the users roles while granting them access by running the following curl command:

curl -k -X POST \
  https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/users/ \
  -H 'Authorization: Bearer <PLATFORM_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
   "serviceInstanceID":"<PROVISIONED_INSTANCE_ID>",
   "users":[
      {
         "display_name":"<DISPLAY_NAME>",
         "role":"<MATCH360_ROLE>",
         "uid":"<USER_ID>",
         "username":"<USER_NAME>"
      }
   ]
}'

Replace the following values in the above curl command:

<CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
<PLATFORM_TOKEN> - the user platform token.
<PROVISIONED_INSTANCE_ID> - the instance ID of your provisioned instance.
<DISPLAY_NAME>, <USER_ID>, and <USER_NAME> - the user display name, user ID, and user name obtained from the /zen-data/v2/serviceInstance/users API.
<MATCH360_ROLE> - the desired IBM Match 360 role: DataEngineer, DataSteward, PublisherUser, or EntityViewer.

curl -k -X POST   https://ibm-nginx-svc-lite.apps.cpd-lb.ibm.com/zen-data/v2/serviceInstance/users/   -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwic3ViIjoiYWRtaW4iLCJpc3MiOiJLTk9YU1NPIiwiYXVkIjoiRFNYIiwicm9sZSI6IkFkbWluIiwicGVybWlzc2lvbnMiOlsiYWRtaW5pc3RyYXRvciIsImNhbl9wcm92aXNpb24iXSwidWlkIjoiMTAwMDMzMDk5OSIsImF1dGhlbnRpY2F0b3IiOiJkZWZhdWx0IiwiZGlzcGxheV9uYW1lIjoiYWRtaW4iLCJpYXQiOjE1NzQzNjI2MDksImV4cCI6MTU3NDQwNTgwOX0.olm53bABcdVE6J9vi-VbRU13cr3B0MKRMVq6D4H-W7tXPZOLDvdsIKhCpW0aBi_iryE1sSgIdIb663RmW_nws2wxlpYWHtvigPwY5OVsr8dIA_wRlsCC96JnVa0GB0adM7U-qSfEruTTWZTLxL-gr4EucUXSZ84aii9ukMtN4VUDTvKsa9xJtnQY4W3owdezRzbG_6UkcvjtWzTLTUGIQisCBTkKZsoroGQuDkiiBTtJdNT8T_rZ6nqNQ6y-wsgZ6LMSCKJA_TC65jTJvu8903UoNzW2wnK7Z_Dt_oob9TYOOzNlkaa1YSQewmBhixV08wr8tmLOOzwtOxwCf5Ya-A'   -H 'Content-Type: application/json'   -d '{
   "serviceInstanceID":"1582510653894",
   "users":[
      {
         "display_name":"user1",
         "role":"DataSteward",
         "uid":"1000331001",
         "username":"user1"
      }
   ]
}'

In this example, the user user1 is granted DataSteward access to the sample-0 (1582510653894) instance.

After access has been granted to users, service instance tokens will be accepted by IBM Match 360.

Retrieving the platform token with the Cloud Pak for Data API

To retrieve the platform token by using the /icp4d-api/v1/authorize API, run the following curl command:

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/authorize' -H 'Content-type: application/json' -d '{ "username": "<USER_NAME>", "password": "<PASSWORD" }'

Replace the following values in the curl command:

<CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
<USER_NAME> - your Cloud Pak for Data user name.
<PASSWORD> - your Cloud Pak for Data password.

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/authorize' -H 'Content-type: application/json' -d '{ "username": "<USER_NAME>", "password": "<PASSWORD" }'

Retrieving the service instance ID with the Cloud Pak for Data API

To retrieve the service instance ID with the /zen-data/v3/service_instances API, run the following curl command:

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v3/service_instances?add_on_type=mdm-app' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

Replace the following values in the curl command:

<CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
<PLATFORM_TOKEN> - the user platform token.

This command produces the following JSON response:

{
   "limit":20,
   "offset":0,
   "service_instances":[
      {
         "addon_type":"mdm-app",
         "addon_version":"1.0.0",
         "created_at":"2020-05-10T22:15:55.557740Z",
         "description":"string",
         "display_name":"MDM1",
         "id":"1583878225057"
         ...
      }
   ],
   "total_count":1
}

The service instance ID will be returned in the id property of the response.

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v3/service_instances?add_on_type=mdm-app' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

The service instance ID will be returned in the id property of the response.

Obtaining the service instance token

After you have your service instance ID, you can obtain a service instance token in one of two ways:

With the Cloud Pak for Data web interface.
With the Cloud Pak for Data API.

Service instance tokens expire 20 minutes after creation.

Retrieving the service instance token with the Cloud Pak for Data web interface

To retrieve the service instance token by using the Cloud Pak for Data web interface:

Log into the Cloud Pak for Data web interface.
Navigate to My Instances, then select the appropriate IBM Match 360 instance.
Click View details.

The service instance token is displayed in the Access Information section.

Retrieving the service instance token with the Cloud Pak for Data API

To retrieve the service instance token by using the /zen-data/v2/serviceInstance/token API, run the following curl command:

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/token' -H 'Authorization: Bearer <PLATFORM_TOKEN> \
-d '{ 
   "serviceInstanceID": "<PROVISIONED_INSTANCE_ID>",
   "expiryTime:" <EXPIRY_TIME>
}'

Replace the following values in the curl command:

<CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
<PLATFORM_TOKEN> - the user platform token.
<PROVISIONED_INSTANCE_ID> - the instance ID of your provisioned instance.
<EXPIRY_TIME> - the token expiry time in minutes.

The expiryTime field is optional. If it is not provided, the default expiry time is 20 minutes.

This command produces the following the following JSON response:

{
   "AccessToken":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b20iOnsiTW9kdWxlTmFtZSI6ImV6LWhlbG0tYXBwIiwiUm9sZSI6IkFkbWluIiwiU2VydmljZUluc3RhbmNlRGlzcGxheU5hbWUiOiJzYW1wbGUtMCIsIlNlcnZpY2VJbnN0YW5jZUlEIjoiMTU4MjUxMDY1Mzg5NCIsIlNlcnZpY2VJbnN0YW5jZVVzZXJOYW1lIjoiYWRtaW4iLCJaZW5EaXNwbGF5TmFtZSI6ImFkbWluIiwiWmVuVUlEIjoiMTAwMDMzMDk5OSIsIlplblVzZXJuYW1lIjoiYWRtaW4ifSwiZXhwIjoxNTgyNTE0NDQxLCJpYXQiOjE1ODI1MTMyNDEsImlzcyI6IklDUEQiLCJzdWIiOiJhZG1pbiIsInVpZCI6IjEwMDAzMzA5OTkifQ.FvtYQKkmIP5vguYGd7TVd-iD7Y4Z-KoTM1p-YlSCDzCzU7rnjogkOfF_0WCblUQQscliTzkV-YcjtfUxgXzObbKpu27oR1F85Z5PcBkMMhtVoxPw41Y9UeEpOy_2uYOr8aK8aJALHuG1W8VuOXoPI4oKh3cJM0M225xn0BK0_dTaVAioDVWiC8o0MDDn6uFDLEymM_U8JzZTFJbqzHUIlbmDphO4GbX28KduZvlrUVDzZ3hQPThUn-YnToLtYcKFWsdULWJHr4CCpPm5ZXGDAvjzTSonk8ktrMhHSgRV3loRhvtftXEZYfKQDGzhvAiKi7Ilv7OX85gJau_LgWv0iA",
   "TokenPayload":{
      "ModuleName":"mdm-app",
      "Role":"DataSteward",
      "ServiceInstanceDisplayName":"mdm-app-1",
      "ServiceInstanceID":"1582510653894",
      "ServiceInstanceUserName":"jsmith",
      "ZenDisplayName":"john smith",
      "ZenUID":"1000330999",
      "ZenUsername":"jsmith"
   }
}

The access token will be returned in the AccessToken property of the JSON response.

Access tokens are only valid for a particular instance of IBM Match 360.

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/token' -H 'Authorization: Bearer <PLATFORM_TOKEN> -d '{ 
   "serviceInstanceID": "<PROVISIONED_INSTANCE_ID>",
   "expiryTime:" <EXPIRY_TIME>
}'

Providing the service instance token to authorize the IBM Match 360 API

You can pass the service instance token to authorize your IBM Match 360 API calls in two ways:

Using the Authorize feature of the API Explorer user interface.
In the Authorization header of an API request.

Providing the service instance token with the Authorize feature of API Explorer

Navigate to the Swagger UI API Explorer by browsing to https://<CPD_CLUSTER_HOST>/<MDM_INSTANCE_ID>/api-model/explorer/#

Replace the <CPD_CLUSTER_HOST> value in the above URL with your Cloud Pak for Data cluster host and replace <MDM_INSTANCE_ID> with your service instance ID number.

In the API Explorer, complete the following steps:

Click Authorize at the top of the page
Enter the instance token obtained from the Obtaining a service instance token section of this page.
Click Authorize and then click Close.

The API Explorer passes your service instance token automatically for every API invoked from the API Explorer page.

Providing the service instance token in an Authorization header of an API request

To provide the service instance token in an Authorization header of an API request, run the following curl command:

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/<API_PATH>' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

Replace the following values in the curl command:

<CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
<API_PATH> - the path of your desired API (Such as /mdm/model/v1/jobs).
<PLATFORM_TOKEN> - the user platform token.

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/<API_PATH>' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

Gets the data model present in configuration space.

GET /mdm/v1/config_data_model

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

ConfigDataModel

Collection of locale, record types, relationship types, system properties definition in configuration space.

Status Code

200
Config data model is returned
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem getting config data model. An internal error occurred while attempting to get config data model.

Example responses

Status 200

{
  "record_types": [
    {
      "name": "person",
      "default_display_name": "person",
      "properties": [
        {
          "name": "record_source",
          "data_type": "String",
          "default_display_name": "Record Source",
          "designation": "source"
        },
        {
          "name": "social_security_number",
          "data_type": "identification",
          "cardinality": "*",
          "default_display_name": "Social Security Number"
        }
      ],
      "source_systems": [
        {
          "name": "MDMSP",
          "default_display_name": "MDMS Person",
          "quality_factors": {
            "completeness": 100,
            "accuracy": 100,
            "correctness": 100,
            "age_relevancy": 100,
            "data_relevancy": 100,
            "consistency": 100
          }
        }
      ]
    }
  ],
  "data_types": [
    {
      "name": "identification",
      "default_display_name": "identification",
      "properties": [
        {
          "name": "identification",
          "data_type": "String",
          "default_display_name": "Identification Value"
        },
        {
          "name": "identification_number",
          "data_type": "String",
          "default_display_name": "Identification Number"
        }
      ]
    }
  ]
}

Replaces the config data model present in configuration space.

PUT /mdm/v1/config_data_model

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Request Body

Required*

ConfigDataModel

Collection of locale, record types, relationship types, system properties definition in configuration space.

Examples:

ConfigDataModelExample

Response

Response Body

ConfigDataModel

Collection of locale, record types, relationship types, system properties definition in configuration space.

Status Code

200
Config data model is replaced.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem replacing config data model. An internal error occurred while attempting to replace the config data model.

Example responses

Status 200

{
  "record_types": [
    {
      "name": "person",
      "default_display_name": "person",
      "properties": [
        {
          "name": "record_source",
          "data_type": "String",
          "default_display_name": "Record Source",
          "designation": "source"
        },
        {
          "name": "social_security_number",
          "data_type": "identification",
          "cardinality": "*",
          "default_display_name": "Social Security Number"
        }
      ],
      "source_systems": [
        {
          "name": "MDMSP",
          "default_display_name": "MDMS Person",
          "quality_factors": {
            "completeness": 100,
            "accuracy": 100,
            "correctness": 100,
            "age_relevancy": 100,
            "data_relevancy": 100,
            "consistency": 100
          }
        }
      ]
    }
  ],
  "data_types": [
    {
      "name": "identification",
      "default_display_name": "identification",
      "properties": [
        {
          "name": "identification",
          "data_type": "String",
          "default_display_name": "Identification Value"
        },
        {
          "name": "identification_number",
          "data_type": "String",
          "default_display_name": "Identification Number"
        }
      ]
    }
  ]
}

Gets the matching statistics (such as number of entities, entity size distributions, and more.) for the specified record type.

GET /mdm/v1/match_statistics

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

record_type
Required*
string
Record type of match statistics

Example: person
entity_type
Required*
string
Entity type of match statistics

Example: person_entity

Response

Response Body

MatchStatistics

The Statistics of the match process results.

Status Code

200
Statistics retrieved
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Error occurred in get resource process. Resource does not exist
500
Error in fetching statistics

Example responses

Status 200

{
  "entity_breakdown": {
    "average": 2,
    "standard_deviation": 0,
    "variance": 0,
    "max": 4,
    "count": 500,
    "min": 1
  },
  "largest_entities": [
    {
      "entity_id": 40976536,
      "entity_size": 4
    }
  ],
  "entity_size_distribution": [
    {
      "entity_count": 5,
      "entity_size": 120
    }
  ],
  "summary": {
    "total_records": 2500,
    "singleton_count": 300,
    "distinct_sources": 4,
    "data_assets": 9,
    "entities_count": 950
  },
  "status": {
    "date_completed": {},
    "comparison_count": 120,
    "bucket_count": 9,
    "run_time": 159000
  }
}

Lists the pair analysis for given tenant.

GET /mdm/v1/pair_analysis

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

PairAnalysisResponse

Status Code

200
Pair analysis is fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
The pair analysis for the given record and entity type not found.
500
Error in getting Pair analysis.

No Sample Response

This method does not specify any sample responses.

Adds a new pair analysis in configuration space. This allows to store result of tuning job with thresholds

POST /mdm/v1/pair_analysis

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Request Body

Required*

PairAnalysisResponse

Examples:

pairAnalysisExample

Response

Response Body

PairAnalysisResponse

Status Code

201
Pair Analysis created successfully.
400
Error in pair Analysis. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in creating asset for the given Pair analysis data.

No Sample Response

This method does not specify any sample responses.

This is a internal REST call.

DELETE /mdm/v1/pair_analysis

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

default
default response

No Sample Response

This method does not specify any sample responses.

Gets the pair analysis for given entity and record type.

GET /mdm/v1/pair_analysis/{record_type}/{entity_type}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Path Parameters

record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair

Response

Response Body

PairAnalysisResponse

Status Code

200
Pair analysis is fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
The pair analysis for the given record and entity type not found.
500
Error in getting Pair analysis.

No Sample Response

This method does not specify any sample responses.

Updates the pair analysis. Unknown attributes will be ignored

PATCH /mdm/v1/pair_analysis/{record_type}/{entity_type}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Path Parameters

record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair

Request Body

Required*

PairAnalysisResponse

Examples:

pairAnalysisExample

Response

Response Body

PairAnalysisResponse

Status Code

200
Pair analysis was updated successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
The pair analysis for the given record and entity type not found.
500
Error updating pair analysis.

No Sample Response

This method does not specify any sample responses.

Delete the comparison record pair decision.

DELETE /mdm/v1/pair_decisions/{record_type}/{entity_type}/{record_number_1}/{record_number_2}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Path Parameters

record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair
record_number_1
Required*
string
Record identier of comparison pair
record_number_2
Required*
string
Record identier of comparison pair

Response

Status Code

204
Comparison record pair decision for given id is fetched successfullly.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Gets the comparison record pair decision statistics.

GET /mdm/v1/pair_decisions/statistics

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair

Response

Response Body

PairStatistics

Response wrapper with the statistics of comparison record pair decisions.

Status Code

200
Comparison record pair decision statistics are fetched successfullly.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Lists the filtered comparison record pair decision.

GET /mdm/v1/pair_decisions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair
record_number_1
string
Record identier of comparison pair
record_number_2
string
Record identier of comparison pair
offset
string
Pair comparison offset
limit
string
no of comparison pairs to be fetched

Response

Response Body

PairDecisionList

Response wrapper with the list of comparison record pairs.

Status Code

200
Comparison record pair decision for given id is fetched successfullly.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Adds a new comparison record pair decision in configuration space. This allows to store user decision taken on comparison of record pairs

POST /mdm/v1/pair_decisions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Request Body

Required*

PairDecisionCreateRequest

Request details for creating comparison record pair decision.

Examples:

pairDecisionExample

Response

Response Body

PairDecision

Pair and corresponding user decision details.

Status Code

201
Pair decision created successfully.
400
Error in pair decision. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in creating asset for the given configuration metadata.

No Sample Response

This method does not specify any sample responses.

Lists the Configurator process details for all processes, optionally filtered by process status.

GET /mdm/v1/configuration_metadata/processes

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Query Parameters

status
string
Unique status param to get the processes based on it. i.e. Not-Initiated, In-progress, Complete and Error

Example: In-progress

Response

Response Body

ProcessList

Response wrapper with the list of Processes.

Status Code

200
Processes retrieved.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting processes.

Example responses

Status 200

{
  "processes": [
    {
      "record_type_label": "Person",
      "record_type": "person",
      "process_name": "match",
      "process_count": "0",
      "message": "Match completed successfully and statistics updated.",
      "status": "Complete"
    }
  ]
}

Create the Configurator process to publish data, publish model, match and delete assets.

POST /mdm/v1/configuration_metadata/processes

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Request Body

Required*

ProcessRequest

Process creation request details.

Examples:

PublishDataExample-all_assets

PublishDataExample-selective_assets

AssetDeletionExample

PublishModelExample

MatchingExample

ImportSnapshotExample-import_with_payload_id

ImportSnapshotExample-import_from_payload

Response

Response Body

ProcessStatus

Process Status.

Status Code

201
Process created successfully.
400
Error in process creation. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting processes.

Example responses

Status 201

{
  "status": "In-Progress",
  "message": "Matching is in progress."
}

Status 201

{
  "status": "In-progress",
  "message": "Publish model is initiated."
}

Status 201

{
  "status": "In-progress",
  "message": "Import Snapshot is initiated."
}

Status 201

{
  "status": "In-progress",
  "message": "Asset Deletion is initiated!",
  "summary": {
    "asset_id_1": "Delete-in-progress"
  }
}

Status 201

{
  "message": "Bulk load of data is initiated.",
  "status": "In-progress"
}

Gets the configuration metadata with all assets, their mappings, loading status, matching status, and more.

GET /mdm/v1/configuration_metadata

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

Status Code

200
configuration metadata for given id is fetched successfullly.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

Example responses

Status 200

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}

Replaces the configuration metadata. It would replace the configuration data including asset information, matching attributes, and more.

PUT /mdm/v1/configuration_metadata

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Request Body

Required*

ConfigurationMetadata

Configuration metadata details.

Examples:

ConfigurationMetadataExample

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

Status Code

200
configuration metadata successfully replaced
400
Error in replacing configuration metadata. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in replacing configuration metadata.

Example responses

Status 200

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}

Updates the configuration metadata with the information provided in the request.

PATCH /mdm/v1/configuration_metadata

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Request Body

Required*

ConfigurationMetadata

Configuration metadata details.

Examples:

ConfigurationMetadataExample

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

Status Code

200
configuration metadata successfully updated
400
Error in updating configuration metadata. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in getting configuration metadata.

Example responses

Status 200

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}

Gets the process details for the specified process name.

GET /mdm/v1/configuration_metadata/processes/{process_name}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Path Parameters

process_name
Required*
string
Unique process name to get the process status. i.e. publish_model, publish_data, match, delete_asset and import_snapshot

Query Parameters

record_type
string
Unique record type associated with the process

Example: person
entity_type
string
Unique entity type associated with the process

Example: person_entity

Response

Response Body

ProcessModelStatus

Details of the Process.

Status Code

200
Process retrieved.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem processing request. Please check if you have provided correct process name.
500
Error in getting process.

Example responses

Status 200

{
  "record_type_label": "Person",
  "record_type": "person",
  "process_name": "match",
  "process_count": "0",
  "message": "Match completed successfully and statistics updated.",
  "status": "Complete"
}

Replaces asset information in the configuration with the information provided in the request.

PUT /mdm/v1/configuration_metadata/assets/{asset_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Path Parameters

asset_id
Required*
string
Unique identifier of project asset

Request Body

Required*

AssetMetadataUpdateRequest

Request object for updating an asset.

Examples:

projectAssetExample

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

200
Asset replaced successfully.
400
Error in replacing asset. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in replacing asset for the given configuration metadata.

Example responses

Status 200

{
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": {},
  "asset_mappings": [
    {
      "key": "COLUMN1",
      "classified_class": "X",
      "data_mapping_name": "record_source",
      "data_mapping_default_display_name": "Record Source",
      "exclude_column": false,
      "auto_mapped": false,
      "completeness_percent": 100
    },
    {
      "key": "COLUMN2",
      "classified_class": "T",
      "data_mapping_name": "",
      "data_mapping_default_display_name": "",
      "exclude_column": true,
      "auto_mapped": false,
      "completeness_percent": 100
    }
  ],
  "asset_id": "asset_id",
  "asset_last_updated_date": "2021-05-17T19:00:34.000Z"
}

Adds a new asset in configuration metadata. This can be called when new asset is getting added into configuration space.

POST /mdm/v1/configuration_metadata/assets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Request Body

Required*

AssetMetadataCreateRequest

Request details for creating new Data Asset.

Examples:

projectAssetExample

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

201
Asset created successfully.
400
Error in created asset. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in creating asset for the given configuration metadata.

Example responses

Status 201

{
  "asset_id": "asset_id",
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": {},
  "asset_mappings": [
    {
      "key": "COLUMN1",
      "classified_class": "X",
      "data_mapping_name": "record_source",
      "data_mapping_default_display_name": "Record Source",
      "exclude_column": false,
      "auto_mapped": false,
      "completeness_percent": 100
    },
    {
      "key": "COLUMN2",
      "classified_class": "T",
      "data_mapping_name": "",
      "data_mapping_default_display_name": "",
      "exclude_column": true,
      "auto_mapped": false,
      "completeness_percent": 100
    }
  ],
  "asset_last_updated_date": "2021-05-17T18:58:59.000Z"
}

Get snapshot by Id

GET /mdm/v1/snapshots/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Path Parameters

id
Required*
string
Id of the snapshot

Response

Response Body

SnapshotDetailedResponse

Response wrapper with the details of the snapshot

Status Code

200
Snapshot with given id is fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

This service updates the name and description of a snapshot.

PUT /mdm/v1/snapshots/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Path Parameters

id
Required*
string
The unique identifier of a snapshot

Request Body

Required*

UpdateSnapshotSummary

Request wrapper object for snapshot summary of model assets

Response

Response Body

UpdateSnapshotSummary

Request wrapper object for snapshot summary of model assets

Status Code

200
The snapshot has been successfully updated.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

delete snapshot by Id

DELETE /mdm/v1/snapshots/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Path Parameters

id
Required*
string
Id of the snapshot

Response

Response Body

SnapshotDetailedResponse

Response wrapper with the details of the snapshot

Status Code

200
Snapshot with given id is deleted successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Get snapshots

GET /mdm/v1/snapshots

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

SnapshotListResponse

Response wrapper with the list of Snapshots.

Status Code

200
Snapshots are fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

This service creates a snapshot of current config assets.

POST /mdm/v1/snapshots

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Request Body

Required*

SnapshotSummary

Contains the summary of a snapshot

Examples:

snapshotExample

Response

Response Body

SnapshotSummary

Contains the summary of a snapshot

Status Code

201
The snapshot of model assets has been successfully created.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

Compare snapshot

PUT /mdm/v1/snapshots/compare

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Request Body

Required*

SnapshotCompareRequest

Request wrapper with the details of the snapshot for comparison with current configuration

Examples:

snapshotCompareExample

Response

Response Body

SnapshotCompareResponse

Response wrapper with the details of the snapshot comparison with current configuration

Status Code

200
Snapshot comparison is generated and fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

Example responses

Status 200

{
  "data_model": {
    "attribute_types": {
      "address": {
        "matching_types": {
          "__current": [
            "ADDRESS"
          ],
          "__incoming": [
            "ADDRESS"
          ],
          "__change": "unchanged"
        },
        "description": {
          "__current": "The address locations associated with a record.",
          "__incoming": "The address locations associated with a record type.",
          "__change": "modified"
        },
        "label": {
          "__current": "Address",
          "__incoming": "Address",
          "__change": "unchanged"
        },
        "classification": {
          "__current": "",
          "__incoming": "",
          "__change": "unchanged"
        },
        "fields": {
          "country": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "The country of this address.",
              "__incoming": "The country of this address.",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Country value",
              "__incoming": "Country value",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 4,
            "__change": "unchanged"
          },
          "address_line1": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "The first line of this address.",
              "__incoming": "The first line of this address.",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Address line 1",
              "__incoming": "Address line 1",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 4,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 2,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 1,
        "__unchanged": 4,
        "__change": "modified"
      },
      "string": {
        "description": {
          "__current": "A single field primitive attribute",
          "__incoming": "A single field primitive attribute",
          "__change": "unchanged"
        },
        "label": {
          "__current": "Simple attribute",
          "__incoming": "Simple attribute",
          "__change": "unchanged"
        },
        "classification": {
          "__current": "",
          "__incoming": "",
          "__change": "unchanged"
        },
        "fields": {
          "value": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Value",
              "__incoming": "Value",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 4,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 4,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 1,
      "__unchanged": 1,
      "__change": "modified"
    },
    "system_properties": {
      "attribute_types": {
        "attribute_last_updated": {
          "settable": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "indexed": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "editable": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "data_type": {
            "__current": "Long",
            "__incoming": "Long",
            "__change": "unchanged"
          },
          "description": {
            "__current": "The time an attribute was last updated",
            "__incoming": "The time an attribute was last updated",
            "__change": "unchanged"
          },
          "label": {
            "__current": "Attribute last updated date",
            "__incoming": "Attribute last updated date",
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 6,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 1,
        "__change": "unchanged"
      },
      "entity_types": {
        "entity_id": {
          "indexed": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "editable": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "data_type": {
            "__current": "String",
            "__incoming": "String",
            "__change": "unchanged"
          },
          "description": {
            "__current": "",
            "__incoming": "",
            "__change": "unchanged"
          },
          "label": {
            "__current": "Entity identifier",
            "__incoming": "Entity identifier",
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 5,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 1,
        "__change": "unchanged"
      },
      "relationship_types": {
        "from_record_id": {
          "settable": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "editable": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "data_type": {
            "__current": "String",
            "__incoming": "String",
            "__change": "unchanged"
          },
          "description": {
            "__current": "The record id this relationship is coming from",
            "__incoming": "The record id this relationship is coming from",
            "__change": "unchanged"
          },
          "label": {
            "__current": "From record id",
            "__incoming": "From record id",
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 5,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 1,
        "__change": "unchanged"
      },
      "version": {
        "__current": "v3",
        "__incoming": "v3",
        "__change": "unchanged"
      },
      "record_types": {
        "collection_id": {
          "settable": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "indexed": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "editable": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "data_type": {
            "__current": "String",
            "__incoming": "String",
            "__change": "unchanged"
          },
          "description": {
            "__current": "Optional identifier for identifying a collection of records",
            "__incoming": "Optional identifier for identifying a collection of records",
            "__change": "unchanged"
          },
          "label": {
            "__current": "Collection ID",
            "__incoming": "Collection ID",
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 6,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 1,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 0,
      "__unchanged": 5,
      "__change": "unchanged"
    },
    "relationship_types": {
      "linkage": {
        "internal": {
          "__current": true,
          "__incoming": true,
          "__change": "unchanged"
        },
        "label_from_source": {
          "__current": "Linked into",
          "__incoming": "Linked into",
          "__change": "unchanged"
        },
        "label_from_target": {
          "__current": "Linked from",
          "__incoming": "Linked from",
          "__change": "unchanged"
        },
        "directional": {
          "__current": true,
          "__incoming": true,
          "__change": "unchanged"
        },
        "description": {
          "__current": "This is the built in linkage relationship type",
          "__incoming": "This is the built in linkage relationship type",
          "__change": "unchanged"
        },
        "label": {
          "__current": "Linkage",
          "__incoming": "Linkage",
          "__change": "unchanged"
        },
        "cardinality": {
          "__current": "ONE2MANY",
          "__incoming": "ONE2MANY",
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 7,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 0,
      "__unchanged": 1,
      "__change": "unchanged"
    },
    "locale": {
      "__current": "en_us",
      "__incoming": "en_us",
      "__change": "unchanged"
    },
    "record_types": {
      "person": {
        "entity_types": {
          "person_entity": {
            "default": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "The entity type for person records.",
              "__incoming": "The entity type for person records.",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Person entity",
              "__incoming": "Person entity",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 3,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "description": {
          "__current": "The record type for person records.",
          "__incoming": "The record type for person records.",
          "__change": "unchanged"
        },
        "attributes": {
          "primary_residence": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "Indicates that this address is a primary residence.",
              "__incoming": "Indicates that this address is a primary residence.",
              "__change": "unchanged"
            },
            "attribute_type": {
              "__current": "address",
              "__incoming": "address",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Primary residence",
              "__incoming": "Primary residence",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "cardinality": {
              "__current": "LIST",
              "__incoming": "LIST",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 6,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "label": {
          "__current": "Person",
          "__incoming": "Person",
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 4,
        "__change": "unchanged"
      },
      "organization": {
        "entity_types": {
          "organization_entity": {
            "default": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "The entity type for org records.",
              "__incoming": "The entity type for org records.",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Organization entity",
              "__incoming": "Organization entity",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 3,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "description": {
          "__current": "The record type for organization records.",
          "__incoming": "The record type for organization records.",
          "__change": "unchanged"
        },
        "attributes": {
          "mailing_address": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "Indicates that this address is a mailing address.",
              "__incoming": "Indicates that this address is a mailing address.",
              "__change": "unchanged"
            },
            "attribute_type": {
              "__current": "address",
              "__incoming": "address",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Mailing address",
              "__incoming": "Mailing address",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "cardinality": {
              "__current": "LIST",
              "__incoming": "LIST",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 6,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "label": {
          "__current": "Organization",
          "__incoming": "Organization",
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 4,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 0,
      "__unchanged": 2,
      "__change": "unchanged"
    },
    "__added": 0,
    "__removed": 0,
    "__modified": 1,
    "__unchanged": 4,
    "__change": "modified"
  },
  "match_settings": {
    "person": {
      "person_entity": {
        "matching_thresholds": {
          "clerical_review_threshold": {
            "__current": 8,
            "__incoming": 8,
            "__change": "unchanged"
          },
          "auto_link_threshold": {
            "__current": 8,
            "__incoming": 8,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 2,
          "__change": "unchanged"
        },
        "matching_attributes": {
          "__current": [
            {
              "name": "mailing_address",
              "data_type": "address"
            }
          ],
          "__incoming": [
            {
              "name": "mailing_address",
              "data_type": "address"
            }
          ],
          "__change": "unchanged"
        },
        "matching_fields": {
          "address": {
            "__current": [
              "address_line1",
              "country"
            ],
            "__incoming": [
              "address_line1",
              "country"
            ],
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 3,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 0,
      "__unchanged": 1,
      "__change": "unchanged"
    },
    "__added": 0,
    "__removed": 0,
    "__modified": 0,
    "__unchanged": 1,
    "__change": "unchanged"
  },
  "__added": 0,
  "__removed": 0,
  "__modified": 1,
  "__unchanged": 1,
  "__change": "modified"
}

Suggest data mappings from MDM data model based on the generic classes of Watson Knowledge Catalog with which the asset is profiled.

POST /mdm/v1/suggest_data_mappings

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

record_type
Required*
string
Record type for data mapping suggestions

Example: person

Request Body

Required*

SuggestedDataMappingRequest

Suggested Data Mapping Request details.

Examples:

DataMappingExample

Response

Response Body

SuggestedDataMapping

Response wrapper with details of Suggested Data Mappings.

Status Code

200
Suggested mappings are fetched
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Unexpected error occured while getting data mappings.

Example responses

Status 200

{
  "suggested_data_mappings": [
    {
      "data_mapping_default_display_name": "Gender",
      "data_mapping_name": "gender",
      "classified_class": "GEN",
      "key": "COLUMN 1"
    }
  ]
}

Gets suggested matching attributes for the record type based on mappings of assets of the specified record type.

GET /mdm/v1/suggested_matching_attributes

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

record_type
Required*
string
Record type for matching attribute suggestions

Response

Response Body

SuggestedMatchAttributes

Response wrapper for attributes suggested for running match process.

Status Code

200
Suggested matching attributes are retrieved
400
Project assets are missing or in invalid state.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error occured while getting suggested matching attributes.

Example responses

Status 200

{
  "suggested_matching_attributes": [
    {
      "matching_attribute_default_display_name": "Gender",
      "matching_attribute_name": "gender"
    }
  ]
}

This service initiates asynchronous processing of the weight tuning job.
Weight tuning is the process to improve the weight for the matching algorithm based on given set of match decisions from data stewards.

POST /mdm/v1/weight_tuning_job

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Query Parameters

record_type
Required*
string
Record type of match statistics

Example: person
entity_type
Required*
string
Entity type of match statistics

Example: person_entity

Response

Response Body

TuningJobResponse

Response object for asynchronous processing of a tuning job

Status Code

201
The weight tuning job has been successfully created.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 201

{
  "created_at": "",
  "image": "mdm-tuning-job",
  "job_name": "weight-tuning",
  "last_updated_at": "",
  "id": "2ba3ed28-00c7-42e4-9cc9-8c74bf5e4ff0",
  "input": {},
  "status": "Running"
}

A delete can target either records or relationships in the graph. If not specified, records are targeted by default. There are four options for a delete:

Delete by search, which removes all elements matching a search criteria. This delete type is only supported for records.
Delete by source, which removes all elements of a specified source.
Delete by asset, which removes all elements loaded from a particular asset or list of assets.
Full delete, which removes all elements from the graph.

POST /mdm/v1/bulk_delete

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.manage

Request

Request Body

Required*

BulkDeleteRequest

Valid object defining the bulk delete job information.

Response

Response Body

BulkDeleteJob

Information about a bulk delete job.

Status Code

202
The bulk delete job was successfully started.
400
Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem performing bulk delete. An internal error occurred while attempting to perform the operation.

Example responses

Status 202

{
  "job_id": "24403560707830722",
  "job_type": "delete",
  "process_ids": [
    "b3ba096d-c625-4d2f-ad12-285966f61cb0"
  ],
  "start_time": "1603483531000",
  "status": "running",
  "delete_type": "source",
  "record_source": "MDM"
}

Once the data load job is queued, track the status of the job to completion using the Job APIs.

To run a sample bulk load, provide the type as 'sample' and the directory_ref identifying which sample data set to load. directory_path is not required when type is set to 'sample', if provided it will be ignored. The available sample data sets are sample_contract_small, sample_consent_small, sample_contract, and sample_consent, and these are the only acceptable values for 'directory_ref'.
To run a bulk load of custom data, provide the type as 'dfs' and the directory_path pointing to the relative location of the data within the storage system. 'directory_ref' is not required when type is set to 'dfs', if provided it will be ignored. Data source directories are expected to adhere to the following format, if not otherwise specified under 'data_structure' in the request body:

record.properties
relationship.properties
record
--[record data files]
relationship
--[relationship data files]

To run a bulk load of data from the Watson Knowledge Catalog, provide the type as 'wkc' and either the 'project_id' or 'catalog_id' of the resource that contains the data. If both are provided, 'catalog_id' will be used by default. 'directory_ref' and 'directory_path' are not required when type is set to 'wkc', if provided they will be ignored. The data asset id and properties must be specified under 'data_structure' in the request body.
For bulk loads of type 'dfs' or 'wkc', required data properties must be supplied either in a properties file or by specifying the properties contents in the request. If both a file and properties contents are provided, the properties contents will take precedence. Properties contents must include 'file_type' to be valid.

POST /mdm/v1/bulk_load

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Request Body

Required*

BulkLoadRequest

Valid object defining the data source and parameters for the bulk load job.

Response

Response Body

BulkLoadJob

Information about a bulk load job.

Status Code

202
The bulk load job was successfully started.
400
Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem performing bulk load. An internal error occurred while attempting to perform the operation.
503
Problem performing bulk load. A bulk load process is already running.

Example responses

Status 202

{
  "job_id": "11734859286522966",
  "job_type": "bulk_load",
  "process_ids": [
    "3d2a5f4a-4784-4562-9252-2aa5afa3547f",
    "cfdf26ea-040e-4ce1-80b4-a7491acd0198"
  ],
  "start_time": "1603479295000",
  "status": "running",
  "load_stage": "vertices"
}

View a list of records that have a relationship to the member records of the specified entity based on the specified relationship type. All records related to the specified entity will be returned regardless of relationship direction. The relationship type is expected to be defined in the data model.

GET /mdm/v1/entities/{id}/related_records

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Path Parameters

id
Required*
string
The unique identifier of the entity.

Query Parameters

record_type
Required*
string
The type of records to return in results.
relationship_type
Required*
string
The type of relationship between related records and entity member records.
limit
integer
The maximum number of records to return in each page of results. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
offset
integer
The number of records to skip before returning a page of results.

Default: 0
include
string[]
Record attributes from the data model to include in the results.

Possible values: contains only unique items
Examples:
View
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
View

Response Body

RelatedRecords

Paged information about a set of other records related to an entity or a record.

Status Code

200
The related records for the entity have been successfully retrieved.
400
Problem getting related records for entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting related records for entity. Entity with id does not exist.
500
Problem getting related records for entity. An internal error occurred while attempting to retrieve the records.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/related_records?crn=${crn}&relationship_type=party_relationship&record_type=person&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/related_records?crn=${crn}&relationship_type=party_relationship&record_type=person&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "related_records": [
    {
      "attributes": {
        "record_id": "535354896573139473",
        "record_last_updated": "1603572360787",
        "record_source": "MDM",
        "usage_type": {
          "attribute_last_updated": "1548936483189",
          "value": "3"
        },
        "usage_value": {
          "attribute_last_updated": "1548936483189",
          "value": "Retail Banking"
        }
      },
      "id": "192616",
      "type": "record",
      "record_number": 192616,
      "type_name": "preference"
    }
  ]
}

View a list of relationships that exist between the given entity and other nodes on the graph. This endpoint does not include internal relationships in the resulting list of relationships.

GET /mdm/v1/entities/{id}/relationships

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Path Parameters

id
Required*
string
The ID of the entity.

Query Parameters

relationship_types
string[]
The relationship types to return.
include_record_relationships
string
Whether to include entity record relationships to other nodes.

Default: false
offset
integer
The number of relationships to skip over.

Default: 0
limit
integer
The number of relationships to be returned. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
source_include
string[]
Attributes from the data model to include in the results for the source vertex.

Possible values: contains only unique items
Examples:
View
target_include
string[]
Attributes from the data model to include in the results for the target vertex.

Possible values: contains only unique items
Examples:
View

Response

Response Body

DataRelationshipsResponse

Paged information about a collection of relationships.

Status Code

200
The relationships have been successfully retrieved.
400
Problem getting relationships for entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting relationships for entity. Entity not found.
500
Problem getting relationships for entity. An internal error occurred while attempting to retrieve the relationships.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/entities/456/relationships?crn=${crn}&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/456/relationships?crn=${crn}&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "relationships": [
    {
      "attributes": {
        "relationship_id": "997554896611881692",
        "relationship_last_updated": "1548937318815",
        "relationship_source": "MDM",
        "from_record_id": "358354896586841797",
        "from_record_source": "MDM",
        "from_record_type": "preference",
        "to_record_id": "998254896587316451",
        "to_record_source": "MDM",
        "to_record_type": "organization"
      },
      "id": "215tzl-5cw8-q7f9-oi7u8",
      "source": {
        "id": "4344",
        "type": "record",
        "type_name": "person"
      },
      "target": {
        "id": "456",
        "type": "entity",
        "type_name": "person_entity"
      },
      "type": "relationship",
      "type_name": "preference_association"
    }
  ]
}

View a list of member records that form the entity.

GET /mdm/v1/entities/{id}/records

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Path Parameters

id
Required*
string
The unique identifier of the entity.

Query Parameters

limit
integer
The maximum number of records to return in each page of results. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
offset
integer
The number of records to skip before returning a page of results.

Default: 0
include
string[]
Record attributes from the data model to include in the results.

Possible values: contains only unique items
Examples:
View
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
View

Response

Response Body

DataRecordsResponse

Paged information about a collection of records.

Status Code

200
The entity records have been successfully retrieved.
400
Problem getting records for entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting records for entity: Entity with id <entity_id> does not exist.
500
Problem getting records for entity. An internal error occurred while attempting to retrieve the records.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/records?crn=${crn}&return_type=results_as_entities&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/records?crn=${crn}&return_type=results_as_entities&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "records": [
    {
      "attributes": {
        "birth_date": {
          "attribute_last_updated": "1548936483016",
          "value": "1934-05-11T00:00:00.000Z"
        },
        "gender": {
          "attribute_last_updated": "1548936483016",
          "value": "F"
        },
        "legal_name": {
          "attribute_last_updated": "1548936483016",
          "last_name": "LEES",
          "given_name": "KAROLYN"
        },
        "primary_residence": {
          "attribute_last_updated": "1548936483189",
          "address_province_state_value": "KY",
          "address_city": "ELLIOTTVILLE",
          "address_zip_postal_code": "40317",
          "address_province_state_type": "21",
          "address_line_1": "106 EAST SYCAMORE ST.",
          "address_record_id": "215054896528318812",
          "address_line_2": "Unit-701"
        },
        "record_id": "216754896528315937",
        "record_last_updated": "1603572360787",
        "record_source": "MDM"
      },
      "id": "53496",
      "type": "record",
      "record_number": 53496,
      "type_name": "person"
    }
  ]
}

View attributes for an entity in a consolidated view based on defined composite view rules from the Model APIs.

GET /mdm/v1/entities/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Path Parameters

id
Required*
string
The unique identifier of the entity.

Query Parameters

include
string[]
Record attributes from the data model to include in the results.

Possible values: contains only unique items
Examples:
View
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
View

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

200
The composite view has been successfully retrieved.
400
Problem getting composite view of entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting composite view of entity. Entity with id <entity_id> does not exist.
500
Problem getting composite view of entity. An internal error occurred while attempting to retrieve the composite view.

Example responses

Status 200

{
  "entity": {
    "attributes": {
      "birth_date": {
        "attribute_last_updated": "1548936483016",
        "value": "1934-05-11T00:00:00.000Z"
      },
      "entity_last_updated": "1603572360787",
      "gender": {
        "attribute_last_updated": "1548936483016",
        "value": "F"
      },
      "legal_name": {
        "attribute_last_updated": "1548936483016",
        "last_name": "LEES",
        "given_name": "KAROLYN"
      },
      "primary_residence": {
        "attribute_last_updated": "1548936483189",
        "address_province_state_value": "KY",
        "address_city": "ELLIOTTVILLE",
        "address_zip_postal_code": "40317",
        "address_line_1": "106 EAST SYCAMORE ST.",
        "address_record_id": "215054896528318812",
        "address_line_2": "Unit-701"
      },
      "record_id": "216754896528315937",
      "record_source": "MDM"
    },
    "id": "person_entity-53496",
    "type": "entity",
    "record_count": 1,
    "type_name": "person_entity"
  },
  "metadata": {
    "href": "${host}/mdm/v1/entities/person_entity-53496?crn=${crn}",
    "id": "person_entity-53496",
    "updated_at": "2020-10-24T20:46:00.787Z"
  }
}

View detailed information about the specified export job. The process ids can be used to track the job status through the Job APIs.

GET /mdm/v1/data_exports/{export_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Path Parameters

export_id
Required*
string
The ID of the export.

Response

Response Body

DataExport

Information about an export.

Status Code

200
The export information was retrieved successfully.
400
Problem getting export information. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting export information. The export does not exist.
500
Problem getting export information. An internal error occurred while attempting to retrieve the export information.

Example responses

Status 200

{
  "end_time": "1603483621000",
  "job_id": "24403560707830722",
  "job_type": "export",
  "process_ids": [
    "b3ba096d-c625-4d2f-ad12-285966f61cb0"
  ],
  "start_time": "1603483531000",
  "status": "succeeded",
  "file_expired": false,
  "file_name": "records",
  "search_criteria": {
    "filters": [],
    "query": {
      "expressions": [
        {
          "condition": "equal",
          "expressions": [],
          "value": "JOHN"
        }
      ],
      "operation": "and"
    },
    "search_type": "record"
  }
}

Download the resulting file from a completed export job if the file exists. The export files may expire after some time.

GET /mdm/v1/data_exports/{export_id}/download

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Path Parameters

export_id
Required*
string
The ID of the export. This ID is equivalent to the job ID of the export job.

Response

Response Body

binary

Status Code

200
The export file has been successfully retrieved.
400
Problem downloading export file. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem downloading export file. The export does not exist.
410
Problem downloading export file. The export file no longer exists.
500
Problem downloading export file. An internal error occurred while attempting to retrieve the export file.
503
Problem downloading export file. The export job is not in a successful state.

No Sample Response

This method does not specify any sample responses.

View a summary list of export jobs that have been requested.

GET /mdm/v1/data_exports

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Query Parameters

offset
integer
The number of exports to skip before returning a page of results.

Default: 0
limit
integer
The maximum number of exports to return in each page of results. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
include_expired
boolean
Whether to include exports with expired files.

Default: true

Response

Response Body

DataExports

Paged information about a collection of exports.

Status Code

200
The list of exports was retrieved successfully.
400
Problem getting list of exports. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem getting list of exports. An internal error occurred while attempting to retrieve the list of exports.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/data_exports?crn=${crn}&record_type=person&local=true&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/data_exports?crn=${crn}&record_type=person&local=true&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "exports": [
    {
      "end_time": "1603483621000",
      "job_id": "24403560707830722",
      "job_type": "export",
      "process_ids": [
        "b3ba096d-c625-4d2f-ad12-285966f61cb0"
      ],
      "start_time": "1603483531000",
      "status": "succeeded",
      "file_expired": false,
      "file_name": "records",
      "search_criteria": {
        "filters": [],
        "query": {
          "expressions": [
            {
              "condition": "equal",
              "expressions": [],
              "value": "JOHN"
            }
          ],
          "operation": "and"
        },
        "search_type": "record"
      }
    }
  ],
  "total_count": 1
}

Run a data export job to export the results of a search. Export format, search criteria, and file name are configurable in the message body. The file name must only contain alphanumeric characters, and be 64 characters or less.

The operation runs as follows:

A compression type must be provided when a partition type of 'executor_count' is specified.

POST /mdm/v1/data_exports

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Query Parameters

compression_type
string
The type of file compression used when exporting the output file. Required when a partition type of 'executor_count' is specified.

Allowable values: [tar,tgz,zip]
partition_type
string
The type of partitioning used when exporting the results.

Allowable values: [none,executor_count]
Default: none
max_count
integer
The maximum number of results to be returned. The maximum limit is 10000.

Possible values: value ≤ 10000

Request Body

Required*

ExportRequest

Valid object defining the export format and search criteria for the export job.

Response

Response Body

DataExport

Information about an export.

Status Code

202
The export job was started successfully.
400
Problem starting export job. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem starting export job. An internal error occurred.

Example responses

Status 202

{
  "job_id": "24403560707830722",
  "job_type": "export",
  "process_ids": [
    "b3ba096d-c625-4d2f-ad12-285966f61cb0"
  ],
  "start_time": "1603483531000",
  "status": "running",
  "file_expired": false,
  "file_name": "records",
  "search_criteria": {
    "filters": [],
    "query": {
      "expressions": [
        {
          "condition": "equal",
          "expressions": [],
          "value": "JOHN"
        }
      ],
      "operation": "and"
    },
    "search_type": "record"
  }
}

Attempt to stop a running job. This operation does not rollback changes made by the job process prior to stopping the job. Full deletion of job resources may take up to a few minutes.

POST /mdm/v1/data_jobs/{job_id}/stop

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Path Parameters

job_id
Required*
string
The ID of the job.

Response

Response Body

DataJob

Information about a job.

Status Code

200
The job was stopped successfully.
400
Problem stopping job process. The process with job id <job_id> is not running.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem stopping job process. A process with job id <job_id> could not be found.
405
Problem stopping job process. Jobs of this type are not supported.
500
Problem stopping job process. An internal error occurred while attempting to perform the operation.

Example responses

Status 200

{
  "end_time": "1620660046000",
  "job_id": "8785798185259674",
  "job_type": "bulk_load",
  "process_ids": [
    "7155aff7-7d42-487b-85a7-8474b5efff2f",
    "8647d779-b13e-4f77-bda7-3ab2ca85c881"
  ],
  "start_time": "1620660025000",
  "status": "canceled",
  "load_stage": "vertices"
}

View a list of jobs that have been run. Filter on job type or job status to get a more precise list of jobs.

GET /mdm/v1/data_jobs

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Query Parameters

offset
integer
The number of jobs to skip before returning a page of results.

Default: 0
limit
integer
The maximum number of jobs to return in each page of results. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
status
string
Filter by job status.

Allowable values: [not_started,prep,queued,running,succeeded,failed,canceled,unknown]
type
string
Filter by job type.

Allowable values: [bulk_load,delete,export,reindex]

Response

Response Body

DataJobs

Paged information about a collection of jobs.

Status Code

200
The list of jobs was retrieved successfully.
400
Problem getting list of jobs. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem getting list of jobs. An internal error occurred while attempting to retrieve the list of jobs.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/data_jobs?crn=${CRN}&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/data_jobs?crn=${CRN}&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "jobs": [
    {
      "end_time": "1620155648000",
      "job_id": "4839655889405511",
      "job_type": "bulk_load",
      "process_ids": [
        "e7df6747-6668-4b5b-a642-70b05eadf20f",
        "658fde68-384c-427e-90a0-bdfd8aa02b6d"
      ],
      "start_time": "1620155442000",
      "status": "succeeded",
      "load_stage": "edges"
    }
  ],
  "total_count": 1
}

View information about the specified job.

GET /mdm/v1/data_jobs/{job_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Path Parameters

job_id
Required*
string
The ID of the job.

Response

Response Body

DataJob

Information about a job.

Status Code

200
The job status was retrieved successfully.
400
Problem getting job information. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting job information. Job not found.
500
Problem getting job information. An internal error occurred while attempting to retrieve the job information.

Example responses

Status 200

{
  "end_time": "1620155648000",
  "job_id": "4839655889405511",
  "job_type": "bulk_load",
  "process_ids": [
    "e7df6747-6668-4b5b-a642-70b05eadf20f",
    "658fde68-384c-427e-90a0-bdfd8aa02b6d"
  ],
  "start_time": "1620155442000",
  "status": "succeeded",
  "load_stage": "edges"
}

Delete any uploaded artifacts from the system after the job completes.

POST /mdm/v1/data_jobs/{job_id}/clean_up

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Path Parameters

job_id
Required*
string
The ID of the job.

Response

Status Code

204
The job clean up was successful.
400
Problem cleaing up job. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem cleaning up job. Job not found.
405
Problem cleaning up job. Jobs of this type are not supported.
410
Problem cleaning up job. The job data could not be found.
500
Problem cleaning up job. An internal error occurred while cleaning up the job.
503
Problem cleaning up job. Operation cannot be performed while job is still running.

No Sample Response

This method does not specify any sample responses.

View information about the specified record on the graph.

GET /mdm/v1/records/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Path Parameters

id
Required*
int64
The ID of the record.

Query Parameters

include
string[]
Record attributes from the data model to include in the results.

Possible values: contains only unique items
Examples:
View
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
View

Response

Response Body

DataRecordResponse

Information about a record.

Status Code

200
The record has been successfully retrieved.
400
Problem getting record. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting record: Record does not exist.
500
Problem getting record. An internal error occurred while attempting to retrieve the record.

Example responses

Status 200

{
  "metadata": {
    "href": "${host}/mdm/v1/records/40964176?crn=${crn}",
    "id": "40964176",
    "updated_at": "2020-10-23T19:49:51.442Z"
  },
  "record": {
    "attributes": {
      "legal_name": {
        "attribute_last_updated": "1548936483189",
        "last_name": "Smith",
        "given_name": "Jane"
      },
      "record_id": "12345",
      "record_last_updated": "1603482591442",
      "record_source": "MDM"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "40964176",
    "type": "record",
    "record_number": 40964176,
    "type_name": "person"
  }
}

Replace the existing record with the new set of attributes. Any existing editable record attributes not specified in the request will be removed from the record.

PUT /mdm/v1/records/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Path Parameters

id
Required*
int64
The ID of the record.

Request Body

Required*

DataRecord

Valid object defining the record information to replace the existing record.

Response

Response Body

DataRecordResponse

Information about a record.

Status Code

200
The record has been successfully updated.
400
Problem updating record. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem updating record. Record does not exist.
409
Problem updating record. Record has a future timestamp.
500
Problem updating record. An internal error occurred while attempting to update the record.

Example responses

Status 200

{
  "metadata": {
    "href": "${host}/mdm/v1/records/40964176?crn=${crn}",
    "id": "40964176",
    "updated_at": "2020-10-23T19:49:51.442Z"
  },
  "record": {
    "attributes": {
      "legal_name": {
        "attribute_last_updated": "1548936483189",
        "last_name": "Smith",
        "given_name": "Jane"
      },
      "record_id": "12345",
      "record_last_updated": "1603482591442",
      "record_source": "MDM"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "40964176",
    "type": "record",
    "record_number": 40964176,
    "type_name": "person"
  }
}

Delete an existing record from the graph. Deleting a record automatically triggers a removal of the record from any formed entities.

DELETE /mdm/v1/records/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Path Parameters

id
Required*
int64
The ID of the record.

Response

Status Code

204
The record was successfully deleted.
400
Problem deleting record. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem deleting record. Record does not exist.
500
Problem deleting record. An internal error occurred while attempting to delete the record.

No Sample Response

This method does not specify any sample responses.

View a list of records that have been added to the graph.

GET /mdm/v1/records

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Query Parameters

offset
integer
The number of records to skip over.

Default: 0
limit
integer
The number of records to be returned. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10

Response

Response Body

DataRecordsResponse

Paged information about a collection of records.

Status Code

200
The records have been successfully retrieved.
400
Problem getting records. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem getting records. An internal error occurred while attempting to retrieve the records.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/records?crn=${crn}&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/records?crn=${crn}&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "records": [
    {
      "attributes": {
        "record_id": "1000007",
        "record_last_updated": "1603209081559",
        "record_source": "MDM",
        "regulation": {
          "regulation_value": "Safety Regulations",
          "attribute_last_updated": "1549006675422",
          "description": "The Safety Regulations provided by Company ABC",
          "regulation_type": "1",
          "url": "https://www.ibm.com"
        }
      },
      "system_attributes": {
        "created_date": "1547836463189",
        "last_updated_user": "user",
        "created_user": "user",
        "last_updated_date": "1548936493189"
      },
      "id": "151592",
      "type": "record",
      "record_number": 151592,
      "type_name": "process_purpose"
    }
  ]
}

Add a new record to the graph. An incremental matching operation is automatically triggered after the record is created, to enable the record to join or form an entity.

POST /mdm/v1/records

Introduction

Service endpoint

Error handling

Authentication

Granting users access to IBM Match 360

Granting access to users with the Cloud Pak for Data web interface

Granting access to users with the Cloud Pak for Data API

Retrieving the platform token with the Cloud Pak for Data API

Retrieving the service instance ID with the Cloud Pak for Data API

Obtaining the service instance token

Retrieving the service instance token with the Cloud Pak for Data web interface

Retrieving the service instance token with the Cloud Pak for Data API

Providing the service instance token to authorize the IBM Match 360 API

Providing the service instance token with the Authorize feature of API Explorer

Providing the service instance token in an Authorization header of an API request

Methods

Get config data model

Authorization

Request

No Request Parameters

Response

Response Body

record_types

any property

relationship_types

any property

attribute_types

any property

system_properties

any property

locale

Status Code

200

401

403

500

Replace Config Data Model

Authorization

Request

Request Body

record_types

any property

relationship_types

any property

attribute_types

any property

system_properties

any property

locale

Response

Response Body

record_types

any property

relationship_types

any property

attribute_types

any property

system_properties

any property

locale

Status Code

200

401

403

500

Get matching statistics

Authorization

Request

Query Parameters

record_type

entity_type

Response

Response Body

entity_breakdown

standard_deviation

average

variance

max

min

count