Introduction

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

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>:<PORT>/api-model/explorer. For example, using the same instance host as in the previous example, you can access the Swagger UI API Explorer IBM Match 360 APIs at https://www.example.com:31843/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:

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:

  1. Log into the Cloud Pak for Data web interface.
  2. Navigate to My Instances, then select the specified instance.
  3. Click the Manage access option.
  4. 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.
  5. 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:

  1. Log into the Cloud Pak for Data web interface.
  2. Navigate to My Instances, then select the appropriate IBM Match 360 instance.
  3. 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>:<PORT>/api-model/explorer

Replace the <CPD_CLUSTER_HOST>:<PORT> value in the above URL with your Cloud Pak for Data cluster host and port.

In the API Explorer, complete the following steps:

  1. Click Authorize at the top of the page
  2. Enter the instance token obtained from the Obtaining a service instance token section of this page.
  3. 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'

Methods

Get config data model

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 > name > Access policies.

  • mdm-oc.configurator.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

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

Status Code

  • Config data model is returned

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting config data model. An internal error occurred while attempting to get config data model.

Example responses
  • {
      "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"
            }
          ]
        }
      ]
    }

Replace Config Data Model

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

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

Examples:
ConfigDataModelExample

Response

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

Status Code

  • Config data model is replaced.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem replacing config data model. An internal error occurred while attempting to replace the config data model.

Example responses
  • {
      "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"
            }
          ]
        }
      ]
    }

Get Config Data Model Record Type Attributes

Gets all the attributes of a specific record type for the data model present in configuration space.

GET /mdm/v1/config_data_model/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 > name > Access policies.

  • mdm-oc.configurator.read

Request

Query Parameters

  • Unique record type to identify data model attributes

Response

The Config Data Model attributes for a record type.

Status Code

  • Config Data Model Record Type attributes retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Error in fetching Config Data Model Record Type attributes.

Example responses
  • {
      "attributes": [
        {
          "name": "record_id",
          "default_display_name": "Record identifier"
        },
        {
          "name": "record_source",
          "default_display_name": "Record source"
        }
      ]
    }

Get matching statistics

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 > name > Access policies.

  • mdm-oc.configurator.read

Request

Query Parameters

  • Record type of match statistics

Response

The Statistics of the match process results.

Status Code

  • Statistics retrieved

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Error occurred in get resource process. Resource does not exist

  • Error in fetching statistics

Example responses
  • {
      "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
      }
    }

List comparison record pair decision

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 > name > Access policies.

  • mdm-oc.configurator.read

Request

Query Parameters

  • Record type of comparison pair

  • Record identier of comparison pair

  • Record identier of comparison pair

Response

Configuration metadata details.

Status Code

  • Comparison record pair decision for given id is fetched successfullly.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Add comparison record pair decision

Adds a new comparison record pair decision in the configuration space to store the user decision for this comparison.

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

Request details for creating comparison record pair decision.

Examples:
projectAssetExample

Response

Response wrapper with details of Data Asset Metadata.

Status Code

  • Pair decision created successfully.

  • Error in pair decision. The request you used is invalid. Please revalidate and try again.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Internal error occured in creating asset for the given configuration metadata.

No Sample Response

This method does not specify any sample responses.

Add configuration metadata asset

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

Request details for creating new Data Asset.

Examples:
projectAssetExample

Response

Response wrapper with details of Data Asset Metadata.

Status Code

  • Asset created successfully.

  • Error in created asset. The request you used is invalid. Please revalidate and try again.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Internal error occured in creating asset for the given configuration metadata.

Example responses
  • {
      "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 configurator process

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

Path Parameters

  • Unique process name to get the process status. i.e. publish_model, publish_data, match, delete_asset

Query Parameters

  • Unique record type to identify data model attributes

    Example: person

Response

Details of the Process.

Status Code

  • Process retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem processing request. Please check if you have provided correct process name.

  • Error in getting process.

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

List the process details

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

Query Parameters

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

    Example: In-progress

Response

Response wrapper with the list of Processes.

Status Code

  • Processes retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Error in getting processes.

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

Create process

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

Process creation request details.

Examples:
AssetDeletionExample
PublishDataExample
PublishModelExample
MatchingExample

Response

Process Status.

Status Code

  • Process creation request accepted.

  • Error in process creation. The request you used is invalid. Please revalidate and try again.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Error in getting processes.

Example responses
  • {
      "status": "In-Progress",
      "message": "Matching is in progress."
    }
  • {
      "status": "In-progress",
      "message": "Publish model is initiated."
    }
  • {
      "status": "In-progress",
      "message": "Asset Deletion is initiated!",
      "summary": {
        "asset_id_1": "Delete-in-progress"
      }
    }
  • {
      "message": "Bulk load of data is initiated.",
      "status": "In-progress"
    }

Get configuration metadata

Gets the configuration metadata with all assets, their mappings, loading status, matching status, an other information.

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 > name > Access policies.

  • mdm-oc.configurator.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Configuration metadata details.

Status Code

  • configuration metadata for given id is fetched successfullly.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Error in getting configuration metadata.

Example responses
  • {
      "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"
        }
      ]
    }

Replace configuration metadata

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

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

Configuration metadata details.

Examples:
ConfigurationMetadataExample

Response

Configuration metadata details.

Status Code

  • Configuration metadata successfully replaced.

  • Error in replacing configuration metadata. The request you used is invalid. Please revalidate and try again.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Internal error occured in replacing configuration metadata.

Example responses
  • {
      "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"
        }
      ]
    }

Update configuration metadata

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

Configuration metadata details.

Examples:
ConfigurationMetadataExample

Response

Configuration metadata details.

Status Code

  • Configuration metadata successfully updated.

  • Error in updating configuration metadata. The request you used is invalid. Please revalidate and try again.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Internal error occured in getting configuration metadata.

Example responses
  • {
      "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"
        }
      ]
    }

Replace configuration metadata asset

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

Path Parameters

  • Unique identifier of project asset

Request object for updating an asset.

Examples:
projectAssetExample

Response

Response wrapper with details of Data Asset Metadata.

Status Code

  • Asset replaced successfully.

  • Error in replacing asset. The request you used is invalid. Please revalidate and try again.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Internal error occured in replacing asset for the given configuration metadata.

Example responses
  • {
      "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"
    }

Resets the system to its default

Resets configuration to original state.

POST /mdm/v1/reset_configuration

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 > name > Access policies.

  • mdm-oc.configurator.manage

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • The reset was successfully performed and the metadata store is cleared.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem resetting metadata. An internal error occurred while attempting to reset.

No Sample Response

This method does not specify any sample responses.

Suggest data mappings

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 > name > Access policies.

  • mdm-oc.configurator.read

Request

Query Parameters

  • Record type for data mapping suggestions

    Example: person

Suggested Data Mapping Request details.

Examples:
DataMappingExample

Response

Response wrapper with details of Suggested Data Mappings.

Status Code

  • Suggested mappings are fetched

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Unexpected error occured while getting data mappings.

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

Get suggested matching attributes

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 > name > Access policies.

  • mdm-oc.configurator.read

Request

Query Parameters

  • Record type for matching attribute suggestions

Response

Response wrapper for attributes suggested for running match process.

Status Code

  • Suggested matching attributes are retrieved

  • Project assets are missing or in invalid state.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Error occured while getting suggested matching attributes.

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

Start an operation to bulk delete data from the graph

There are four options for a delete:

  • Delete by search, which removes all records matching a search criteria.
  • Delete by source, which removes all records of a specified record source.
  • Delete by asset, which removes all records loaded from a particular asset or list of assets.
  • Full delete, which removes all records 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 > name > Access policies.

  • mdm-oc.data.manage

Request

Valid object defining the bulk delete job information.

Response

Information about a bulk delete job.

Status Code

  • The bulk delete job was successfully started.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem performing bulk delete. An internal error occurred while attempting to perform the operation.

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

Start a bulk load of data into the graph

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 > name > Access policies.

  • mdm-oc.data.write

Request

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

Response

Information about a bulk load job.

Status Code

  • The bulk load job was successfully started.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem performing bulk load. An internal error occurred while attempting to perform the operation.

  • Problem performing bulk load. A bulk load process is already running.

Example responses
  • {
      "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"
    }

List the records linked into an entity

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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The unique identifier of the entity.

Query Parameters

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

    Possible values: value ≤ 50

    Default: 10

  • The number of records to skip before returning a page of results.

    Default: 0

  • Record attributes from the data model to include in the results.

    Possible values: contains only unique items

    Examples:
    View
  • Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples:
    View

Response

Paged information about a collection of records.

Status Code

  • The entity records have been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting records for entity: Entity with id <entity_id> does not exist.

  • Problem getting records for entity. An internal error occurred while attempting to retrieve the records.

Example responses
  • {
      "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 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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The unique identifier of the entity.

Query Parameters

  • The type of records to return in results.

  • The type of relationship between related records and entity member records.

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

    Possible values: value ≤ 50

    Default: 10

  • The number of records to skip before returning a page of results.

    Default: 0

  • Record attributes from the data model to include in the results.

    Possible values: contains only unique items

    Examples:
    View
  • Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples:
    View

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

Status Code

  • The related records for the entity have been successfully retrieved.

  • Problem getting related records for entity. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting related records for entity. Entity with id does not exist.

  • Problem getting related records for entity. An internal error occurred while attempting to retrieve the records.

Example responses
  • {
      "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"
        }
      ]
    }

Get the composite view of an entity

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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The unique identifier of the entity.

Query Parameters

  • Record attributes from the data model to include in the results.

    Possible values: contains only unique items

    Examples:
    View
  • Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples:
    View

Response

Information and metadata about the composite view of an entity.

Status Code

  • The composite view has been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting composite view for entity: Entity with id <entity_id> does not exist.

  • Problem getting composite view for entity. An internal error occurred while attempting to retrieve the composite view.

Example responses
  • {
      "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"
      }
    }

List the export jobs

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 > name > Access policies.

  • mdm-oc.data.read

Request

Query Parameters

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

    Default: 0

  • The maximum number of exports to return in each page of results. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

  • Whether to include exports with expired files.

    Default: true

Response

Paged information about a collection of exports.

Status Code

  • The list of exports was retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting list of exports. An internal error occurred while attempting to retrieve the list of exports.

Example responses
  • {
      "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
    }

Start an export of search results

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.

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 > name > Access policies.

  • mdm-oc.data.read

Request

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

Response

Information about an export.

Status Code

  • The export job was started successfully.

  • Problem starting export job. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem starting export job. An internal error occurred.

Example responses
  • {
      "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"
      }
    }

Get information for an export

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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The ID of the export.

Response

Information about an export.

Status Code

  • The export information was retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting export information. The export does not exist.

  • Problem getting export information. An internal error occurred while attempting to retrieve the export information.

Example responses
  • {
      "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 an export file

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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The ID of the export. This ID is equivalent to the job ID of the export job.

Response

Status Code

  • The export file has been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem downloading export file. The export does not exist.

  • Problem downloading export file. The export file no longer exists.

  • Problem downloading export file. An internal error occurred while attempting to retrieve the export file.

  • Problem downloading export file. The export job is not in a successful state.

No Sample Response

This method does not specify any sample responses.

Stop a given job

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 > name > Access policies.

  • mdm-oc.data.write

Request

Path Parameters

  • The ID of the job.

Response

Information about a job.

Status Code

  • The job was stopped successfully.

  • Problem stopping job process. The process with job id <job_id> is not running.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem stopping job process. A process with job id <job_id> could not be found.

  • Problem stopping job process. Jobs of this type are not supported.

  • Problem stopping job process. An internal error occurred while attempting to perform the operation.

Example responses
  • {
      "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"
    }

List the jobs

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 > name > Access policies.

  • mdm-oc.data.read

Request

Query Parameters

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

    Default: 0

  • The maximum number of jobs to return in each page of results. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

  • Filter by job status.

    Allowable values: [not_started,prep,queued,running,succeeded,failed,canceled]

  • Filter by job type.

    Allowable values: [bulk_load,delete,export]

Response

Paged information about a collection of jobs.

Status Code

  • The list of jobs was retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting list of jobs. An internal error occurred while attempting to retrieve the list of jobs.

Example responses
  • {
      "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
    }

Get information for a job

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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The ID of the job.

Response

Information about a job.

Status Code

  • The job status was retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting job information. Job not found.

  • Problem getting job information. An internal error occurred while attempting to retrieve the job information.

Example responses
  • {
      "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"
    }

Clean up job data

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 > name > Access policies.

  • mdm-oc.data.write

Request

Path Parameters

  • The ID of the job.

Response

Status Code

  • The job clean up was successful.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem cleaning up job. Job not found.

  • Problem cleaning up job. Jobs of this type are not supported.

  • Problem cleaning up job. The job data could not be found.

  • Problem cleaning up job. An internal error occurred while cleaning up the job.

  • Problem cleaning up job. Operation cannot be performed while job is still running.

No Sample Response

This method does not specify any sample responses.

Get a record

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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The ID of the record.

Query Parameters

  • Record attributes from the data model to include in the results.

    Possible values: contains only unique items

    Examples:
    View
  • Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples:
    View

Response

Information about a record.

Status Code

  • The record has been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting record: Record does not exist.

  • Problem getting record. An internal error occurred while attempting to retrieve the record.

Example responses
  • {
      "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"
        },
        "id": "40964176",
        "type": "record",
        "record_number": 40964176,
        "type_name": "person"
      }
    }

Replace attributes for a record

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 > name > Access policies.

  • mdm-oc.data.write

Request

Path Parameters

  • The ID of the record.

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

Response

Information about a record.

Status Code

  • The record has been successfully updated.

  • Problem updating record. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem updating record. Record does not exist.

  • Problem updating record. Record has a future timestamp.

  • Problem updating record. An internal error occurred while attempting to update the record.

Example responses
  • {
      "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"
        },
        "id": "40964176",
        "type": "record",
        "record_number": 40964176,
        "type_name": "person"
      }
    }

Delete a record

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 > name > Access policies.

  • mdm-oc.data.write

Request

Path Parameters

  • The ID of the record.

Response

Status Code

  • The record was successfully deleted.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem deleting record. Record does not exist.

  • Problem deleting record. An internal error occurred while attempting to delete the record.

No Sample Response

This method does not specify any sample responses.

List the records

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 > name > Access policies.

  • mdm-oc.data.read

Request

Query Parameters

  • The number of records to skip over.

    Default: 0

  • The number of records to be returned. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

Response

Paged information about a collection of records.

Status Code

  • The records have been successfully retrieved.

  • Problem getting records. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting records. An internal error occurred while attempting to retrieve the records.

Example responses
  • {
      "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,
      "total_count": 1,
      "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"
            }
          },
          "id": "151592",
          "type": "record",
          "record_number": 151592,
          "type_name": "process_purpose"
        }
      ]
    }

Create a new record

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

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 > name > Access policies.

  • mdm-oc.data.write

Request

Valid object defining the record to be added to the graph.

Response

Information about a record.

Status Code

  • The record has been successfully created.

  • Problem creating record. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem creating record. An internal error occurred while attempting to create the record.

Example responses
  • {
      "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"
        },
        "id": "40964176",
        "type": "record",
        "record_number": 40964176,
        "type_name": "person"
      }
    }

List the relationships for a record

View a list of relationships that exist between the given record and other records in the graph.

GET /mdm/v1/records/{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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The ID of the record.

Response

Information about a collection of relationships.

Status Code

  • The relationships have been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem retrieving relationships. Record not found

  • Problem retrieving relationships. An internal error occurred.

Example responses
  • {
      "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",
          "type": "relationship",
          "type_name": "preference_association"
        }
      ]
    }

Get a relationship for a record

Retrieve a single relationship from the set of relationships for the record.

GET /mdm/v1/records/{id}/relationships/{relationship_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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The ID of the record.

  • The ID of the linked relationship to return.

Response

Information about a relationship.

Status Code

  • The relationship has been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting relationship. Relationship does not exist.

  • Problem getting relationship. An internal error occurred while attempting to retrieve the relationship.

Example responses
  • {
      "metadata": {
        "href": "${host}/mdm/v1/records/41160752/relationships/215tzl-5cw8-q7f9-oi7u8?crn={crn}",
        "id": "215tzl-5cw8-q7f9-oi7u8",
        "updated_at": "2019-01-31T12:21:58.815Z"
      },
      "relationship": {
        "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",
        "type": "relationship",
        "type_name": "preference_association"
      }
    }

Retrieve a set of records which are directly connected to the specified record by a relationship. All records related to the specified record will be returned regardless of relationship direction.

GET /mdm/v1/records/{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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The ID of the record.

Query Parameters

  • The type of record to filter in results

  • The type of relationship between related records and the specified record.

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

    Possible values: value ≤ 50

    Default: 10

  • The number of records to skip before returning a page of results.

    Default: 0

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

Status Code

  • The related records for the record have been successfully retrieved.

  • Problem getting related records. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem retrieving neighbors. Record does not exist.

  • Problem retrieving related records. An internal error occurred while attempting to retrieve the related records.

Example responses
  • {
      "first": {
        "href": "${host}/mdm/v1/records/249992/related_records?crn=${crn}&offset=0&limit=10"
      },
      "last": {
        "href": "${host}/mdm/v1/records/249992/related_records?crn=${crn}&offset=0&limit=10"
      },
      "limit": 10,
      "offset": 0,
      "total_count": 1,
      "related_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"
            }
          },
          "id": "151592",
          "type": "record",
          "record_number": 151592,
          "type_name": "process_purpose"
        }
      ]
    }

List the entities for a record

View a list of entities which the record contributes to.

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

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 > name > Access policies.

  • mdm-oc.data.read

Request

Path Parameters

  • The id of the record.

Query Parameters

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

    Possible values: value ≤ 50

    Default: 10

  • The number of records to skip before returning a page of results.

    Default: 0

  • Record attributes from the data model to include in the results.

    Possible values: contains only unique items

    Examples:
    View
  • Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples:
    View

Response

Paged information about a collection of entities.

Status Code

  • The list of entities have been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting entities. Record with id <record_id> does not exist.

  • Problem getting entities. An internal error occurred while attempting to retrieve entities for the specified record.

Example responses
  • {
      "first": {
        "href": "${host}/mdm/v1/records/53496/entities?crn=${crn}&offset=0&limit=10"
      },
      "last": {
        "href": "${host}/mdm/v1/records/53496/entities?crn=${crn}&offset=0&limit=10"
      },
      "limit": 10,
      "offset": 0,
      "entities": [
        {
          "attributes": {
            "birth_date": {
              "attribute_last_updated": "1548936483189",
              "value": "1934-05-11T00:00:00.000Z"
            },
            "entity_last_updated": "1603572360787",
            "gender": {
              "attribute_last_updated": "1548936483189",
              "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_line_2": "Unit-701"
            },
            "record_id": "216754896528315937",
            "record_source": "MDM"
          },
          "id": "person_entity-53496",
          "type": "entity",
          "record_count": 1,
          "type_name": "person_entity"
        }
      ]
    }

Update the graph schema

Update the existing graph schema to support the latest draft version of the data model. A draft version of the data model is required to exist in the Model APIs when running a schema update operation.

POST /mdm/v1/schema_update

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 > name > Access policies.

  • mdm-oc.data.manage

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • The schema is up to date with the latest data model.

  • Problem updating schema. The user is not authenticated.

  • Problem updating schema. The user is not authorized to perform the request.

  • Problem updating schema.

  • Problem updating schema. An internal error occurred while attempting to perform the operation.

No Sample Response

This method does not specify any sample responses.

Search the data on the graph

Run a full text search, or search on attribute fields. Searching on fields is achievable by using dot-notation for the property keys (e.g. legal_name.given_name). Omit the property key for a full text search. Pagination is supported.

POST /mdm/v1/search

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 > name > Access policies.

  • mdm-oc.data.read

Request

Query Parameters

  • The type of results to return from the search.

    Allowable values: [results,results_as_entities]

    Default: results

  • The maximum number of elements to return in each page of results. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

  • The number of elements to skip before returning a page of results.

    Default: 0

  • Record attributes from the data model to include in the results.

    Possible values: contains only unique items

    Examples:
    View
  • Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples:
    View

Valid input defining the search criteria.

Response

Results of a search operation.

Status Code

  • The search was performed successfully.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Request timed out.

  • Problem searching. An internal error occurred while attempting to perform the search.

Example responses
  • {
      "first": {
        "href": "${host}/mdm/v1/search?return_type=results&crn=${crn}&offset=0&limit=10"
      },
      "last": {
        "href": "${host}/mdm/v1/search?return_type=results&crn=${crn}&offset=0&limit=10"
      },
      "limit": 10,
      "offset": 0,
      "is_exact_count": true,
      "results": [
        {
          "attributes": {
            "birth_date": {
              "attribute_last_updated": "1548936432644",
              "value": "1981-11-27T00:00:00.000Z"
            },
            "gender": {
              "attribute_last_updated": "1548936432644",
              "value": "M"
            },
            "legal_name": {
              "attribute_last_updated": "1548936432644",
              "last_name": "MYERS",
              "given_name": "JOHN"
            },
            "primary_residence": {
              "attribute_last_updated": "1548936432653",
              "address_province_state_value": "CA",
              "address_city": "COLOMA",
              "address_zip_postal_code": "95613",
              "address_province_state_type": "6",
              "address_line_1": "5955 EAST ST ANNE STREET",
              "address_line_2": "Unit-89"
            },
            "record_id": "103954896523264298",
            "record_last_updated": "1603479339402",
            "record_source": "MDM"
          },
          "id": "180336",
          "type": "record",
          "record_number": 180336,
          "type_name": "person"
        }
      ],
      "total_count": 1
    }

Get graph statistics

View statistics derived from the data on the graph, including total count, counts by source, and counts by type.

GET /mdm/v1/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 > name > Access policies.

  • mdm-oc.data.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

A collection of statistics for the graph.

Status Code

  • The graph statistics have been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting graph statistics. An internal error occurred while attempting to retrieve the graph statistics.

Example responses
  • {
      "aggregate_counts": {
        "record_types": [
          {
            "key": "macro_role",
            "size": 273
          },
          {
            "key": "person",
            "size": 406
          },
          {
            "key": "organization",
            "size": 516
          },
          {
            "key": "contract",
            "size": 315
          },
          {
            "key": "preference",
            "size": 161
          },
          {
            "key": "interaction",
            "size": 279
          },
          {
            "key": "contract_component",
            "size": 203
          },
          {
            "key": "process_purpose",
            "size": 9
          }
        ],
        "sources": [
          {
            "key": "MDM",
            "size": 2062
          },
          {
            "key": "Other",
            "size": 100
          }
        ]
      },
      "record_count": 2162,
      "total_count": 2162
    }

Get the storage metadata

View information about the storage component where data can be uploaded before being loaded to the graph. This operation is used by Publisher.

GET /mdm/v1/storage_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 > name > Access policies.

  • mdm-oc.data.manage

Request

No Request Parameters

This method does not accept any request parameters.

Response

Information about the storage component for the instance.

Status Code

  • The storage metadata has been successfully fetched.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem fetching storage metadata. An internal error occurred while attempting to perform the operation.

Example responses
  • {
      "transfer_type": "cloud"
    }

Get the surrounding vertices and edges for a set of vertices

Fetch a subgraph view of a subset of data on the graph as specified in the request.

The operation runs with the following features:

  • Includes initial vertices in the result.
  • Returns a summary of graph elements. Does not include detailed information such as model attribute keys and values.
  • Ignores a vertex identifier if the vertex cannot be found. Returns an empty subgraph if no vertices are found.
  • Returns an edge in the resulting subgraph if its source vertex, target vertex and the edge itself can be reached within the specified number of hops from at least one initial vertex.
  • Includes edges between record and entity vertices.
  • No more than 3 hops and 50 input vertices are permitted. The number of edges per vertex is capped at 50. Note that the number of edges per vertex may be less than this limit due to shared edges.
POST /mdm/v1/subgraph

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 > name > Access policies.

  • mdm-oc.data.read

Request

Valid object defining scope parameters for the subgraph.

Response

A graph view representing a scoped subset of the graph.

Status Code

  • The subgraph has been successfully retrieved.

  • Problem retrieving subgraph. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem retrieving subgraph. An internal error occurred while attempting to retrieve the subgraph.

Example responses
  • {
      "edges": [
        {
          "display_name": "consent_process_purpose_link",
          "id": "2pjo60-18e8-r28l-38yw",
          "source_id": "57536",
          "target_id": "151592",
          "type": "relationship",
          "type_name": "consent_process_purpose_link"
        },
        {
          "display_name": "consent_process_purpose_link",
          "id": "odzpo-2734-r28l-38yw",
          "source_id": "102496",
          "target_id": "151592",
          "type": "relationship",
          "type_name": "consent_process_purpose_link"
        }
      ],
      "vertices": [
        {
          "attributes": {},
          "display_name": "person-57536",
          "id": "57536",
          "is_global": true,
          "type": "record",
          "type_name": "person"
        },
        {
          "attributes": {},
          "display_name": "person-102496",
          "id": "102496",
          "is_global": true,
          "type": "record",
          "type_name": "person"
        },
        {
          "attributes": {},
          "display_name": "process_purpose-151592",
          "id": "151592",
          "is_global": true,
          "type": "record",
          "type_name": "process_purpose"
        }
      ]
    }

Perform a bulk update of data on the graph

Run an update of records and relationships in the graph by creating, modifying and deleting data in a single transaction. This operation is intended for incremental updates of data. Please use the bulk load feature when loading large volumes of data.

The operation runs as follows:

  • Performs all relationship deletions first, then record deletions.
  • After the deletions are completed, all record upserts (i.e. insertions and updates) are performed next, followed by relationship upserts.
  • Any element found in both deletions and upserts is treated as a deletion, and is removed from the upserts list before processing.
  • Any other case of a duplicated element will cause the update to fail.
  • If the 'ignore_redundant_updates' parameter is set to 'true', any update with a timestamp that is not newer than the existing timestamp for that element will not be applied, but it will not cause the entire transaction to fail. If the flag is set to 'false', invalid timestamps will cause a transaction failure.
  • A failed update will cause all changes performed by the transaction to be reverted back to the original graph state.
POST /mdm/v1/ongoing_sync

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 > name > Access policies.

  • mdm-oc.data.manage

Request

Query Parameters

  • Whether to ignore updates that fail due to missing or invalid 'record_last_updated' timestamps.

    Default: false

Valid object defining the elements to be inserted, updated or deleted on the graph.

Response

Status Code

  • The updates have been successfully processed.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem performing bulk update. An internal error occurred while attempting to update the graph.

No Sample Response

This method does not specify any sample responses.

Initiate data derivation job

  • This service initiates asynchronous processing of the derive job.
  • Data derivation is the process to standardize and generate buckets for the input records.
POST /mdm/v1/bulk_derive

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 > name > Access policies.

  • mdm-oc.matching.manage

Request

Query Parameters

  • The data type identifier of source records, ie. person, organization, contract

    Example: person

  • Force to re-derive all records, default is false

    Default: false

  • The delimited text file name, ending with .csv/.tsv for comma/tab separated format.

    Example: /usr/mdm-matching/sample/person-100.tsv

  • comma separated column names in the data file

    Example: record_source,,record_id,legal_name.given_name,legal_name.last_name,primary_residence.address_line1,primary_residence.city,primary_residence.province_state,primary_residence.zip_postal_code,,home_telephone.phone_number,business_address.address_line1,business_address.city,business_address.province_state,business_address.zip_postal_code,,home_telephone.phone_number.1,social_security_number.identification_number,health_card.identification_number,birth_date.value,gender.value

  • IBM COS end point (i.e. https://s3.us-east.cloud-object-storage.appdomain.cloud)

    Example: http://s3.us-south.cloud-object-storage.appdomain.cloud

  • IBM COS bucket (i.e. bucket-27200-lwx4cfvcue)

    Example: mdmdata

  • IBM COS access key (i.e. cf4965cebe074720a4929759f57e1214)

    Example: b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret

  • The unique secret code to access IBM COS

    Example: <hex string>

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • IBM COS end point for job log storage.

    Example: http://s3.us-south.cloud-object-storage.appdomain.cloud

  • IBM COS bucket for job log storage.

    Example: mdmdata

  • IBM COS access key for spark log storage

    Example: b33037e4e8954207a434cc032c1139d1

  • IBM COS secret key for spark log storage

    Example: <hex string>

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully created.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

  • The request cannot be processed due to insufficient permission error.

  • The request cannot be processed due to an unexpected system error.

Example responses
  • {
      "created_at": "",
      "image": "mdm-spark-job",
      "job_name": "match-bulkderiver",
      "last_updated_at": "",
      "id": "2ba3ed28-00c7-42e4-9cc9-8c74bf5e4ff0",
      "input": {},
      "spark_configuration": {},
      "status": "Running"
    }

Initiate report job

  • This service initiates asynchronous processing of a report job.
  • Report job creates a report of the existing derived data that includes information like matching summary, largest entities, and more.
POST /mdm/v1/bulk_report

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 > name > Access policies.

  • mdm-oc.matching.manage

Request

Query Parameters

  • The data type identifier of source records, ie. person, organization, contract

    Example: person

  • The data type identifier of entity, ie. person_entity, organization_entity, household_entity

    Example: person_entity

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • collect analysis report, default is false

    Default: false

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully created.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

  • The request cannot be processed due to insufficient permission error.

  • The request cannot be processed due to an unexpected system error.

Example responses
  • {
      "created_at": "",
      "image": "mdm-spark-job",
      "job_name": "match-bulkreporter",
      "last_updated_at": "",
      "id": "854ed8ca-dddf-4862-b069-58cb15eba138",
      "input": {},
      "spark_configuration": {},
      "status": "Queued"
    }

Initiate match job

  • This service initiates asynchronous processing of the match job.
  • Matching is the process to compare two or more records and create linkages between the matched records.
POST /mdm/v1/bulk_match

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 > name > Access policies.

  • mdm-oc.matching.manage

Request

Query Parameters

  • The data type identifier of source records, ie. person, organization, contract

    Example: person

  • The data type identifier of entity, ie. person_entity, organization_entity, household_entity

    Example: person_entity

  • Force to re-match all records, default is false

    Default: false

  • collect analysis report, default is false

    Default: false

  • Replicate entity id, default is false

    Default: false

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • IBM COS end point for job log storage.

    Example: http://s3.us-south.cloud-object-storage.appdomain.cloud

  • IBM COS bucket for job log storage.

    Example: mdmdata

  • IBM COS access key for spark log storage

    Example: b33037e4e8954207a434cc032c1139d1

  • IBM COS secret key for spark log storage

    Example: <hex string>

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully created.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

  • The request cannot be processed due to insufficient permission error.

  • The request cannot be processed due to an unexpected system error.

Example responses
  • {
      "created_at": "",
      "image": "mdm-spark-job",
      "job_name": "match-bulkmatcher",
      "last_updated_at": "",
      "id": "b10502a6-b336-4452-b15d-bbda67b95299",
      "input": {},
      "spark_configuration": {},
      "status": "Queued"
    }

Retrieve record ids

  • This service retrieves all record_ids that are assigned with the same entity_id.
GET /mdm/v1/entity_ids/{entity_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 > name > Access policies.

  • mdm-oc.matching.read

Request

Path Parameters

  • The entity identifier of an entity as assigned by the system

    Example: entity_type-123456789

Response

Response wrapper object for getting the record keys of a given entity_id

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to authentication error.

  • The request cannot be processed due to insufficient permission error.

  • The request cannot be processed due to resource not found.

  • The request cannot be processed due to an unexpected system error.

Example responses
  • {
      "records": []
    }

Preview entity composition

  • This service provides a preview of the impacted entities by hypothesizing one or more manual link/unlink rules.
POST /mdm/v1/linkage_rules_preview