IBM Cloud API Docs

Introduction

Last updated: 2025-04-30

IBM Match 360 on IBM Software Hub provides APIs that enable you to connect the IBM Match 360 service's powerful master data matching capabilities to your systems and processes. 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 IBM Software Hub, 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 APIs support:

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

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

For more information about IBM Match 360 on IBM Software Hub, see the service's documentation in the IBM Software Hub documentation. For more information about IBM Match 360 on IBM Cloud Pak for Data 4.x, see the service's documentation in the IBM Cloud Pak for Data documentation.

Service endpoint

The IBM Match 360 service endpoint is based on your IBM Software Hub deployment URL: https://{cpd_cluster_host}/mdm/{match360-microservice}/. The valid microservice values are:

  • model
  • matching
  • configuration
  • data
  • job

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

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

  • Model: https://www.example.com/1664447707275339/api-model/explorer/#
  • Matching: https://www.example.com/1664447707275339/api-matching/explorer/#
  • Configuration: https://www.example.com/1664447707275339/api-configuration/explorer/#
  • Data: https://www.example.com/1664447707275339/api-data/explorer/#
  • Job: https://www.example.com/1664447707275339/api-job/explorer/#

Example

curl -H "Authorization: Bearer {token}" -X {request_method} "https://{cpd_cluster_host}/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());
}

Granting users access to IBM Match 360

After you install IBM Match 360 on IBM Software Hub, you must give users access to the service by creating user groups and adding users to them.

Only the IBM Software Hub administrator who installs IBM Match 360 is granted access to the service by default. To provide other users with access to the service, the administrator user must add them to the appropriate user groups. For example, to create and set up a master data configuration asset, users must belong to the DataEngineer group.

To access IBM Match 360, an IBM Software Hub user must belong to one of the following specialized groups:

  • DataEngineer: DataEngineer group members have full rights to configure a IBM Match 360 service instance, onboard data sources, customize the data model, tune and customize the matching algorithm, run matching, view or create jobs, create pair review requests, and view or edit entities and records in the master data explorer. DataEngineer users can create and set up a master data configuration asset. DataEngineer users can also view and manage governed data.
  • DataSteward: Data Steward group members can onboard data sources, run matching, view the data model, view ongoing jobs, complete pair review tasks, and view or edit entities and records in the master data explorer.
  • PublisherUser: PublisherUser group members can publish data from an IBM InfoSphere® Master Data Management instance, through the MDM Publisher tool, into IBM Match 360. PublisherUser members can onboard data sources, customize the data model, and view or create jobs. PublisherUser users can also view and manage governed data.
  • EntityViewer: EntityViewer group members 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.

For information about creating the necessary IBM Match 360 user groups and granting users access to IBM Match 360, see Giving users access to IBM Match 360 in the IBM Software Hub documentation.

After access has been granted to users, IBM Match 360 can accept authenticated API calls from those users.

Authentication

To authenticate to the IBM Match 360 API, you can use either a ZenAPIKey token or a service instance token. You must first generate the token from the IBM Software Hub platform, and then you can include it in the Authorization header of calls to the IBM Match 360 API.

Authenticating by using a ZenApiKey token

In IBM Software Hub (and Cloud Pak for Data 4.8.4 and later), you can authenticate to the IBM Match 360 API by using a ZenAPIKey token.

The ZenApiKey token is built from the platform API key. To generate an API key through the IBM Software Hub user interface:

  1. Log in to the IBM Software Hub web client.
  2. From the toolbar, click your avatar.
  3. Click Profile and settings.
  4. Click API key > Generate new key.
  5. Click Generate.
  6. Click Copy and save your key somewhere safe. You cannot recover this key if you lose it.

Alternatively, you can call the IBM Software Hub Generate API key method. Note: this method must be called with Bearer access token authorization.

When you get the API Key from the user experience or from the "generate API Key" method, you must Base64 encode <username>:<api_key> to get the ZenAPIKey token.

Using a ZenAPIKey token to authorize your IBM Match 360 API calls

Pass the ZenApiKey token in the Authorization header of an API request to authorize your IBM Match 360 API calls. To provide the ZenApiKey token in an API Authorization header, run the following curl command:

curl -X GET 'https://{cpd_cluster_host}/<API_PATH>' -H 'Authorization: ZenApiKey {token}' -H 'Content-type: application/json'

Replace the following values in the curl command:

  • <API_PATH> - the path of your desired API (Such as /mdm/model/v1/jobs).
  • {token} - the platform ZenApiKey authentication token.
echo "<username>:<api_key>" | base64

curl -H "Authorization: ZenApiKey {token}" "https://{cpd_cluster_host}/v1/{method}"

Authenticating by using a service instance token (Bearer token)

After authenticating to the IBM Software Hub platform, obtain a service instance token to authenticate to your IBM Match 360 instance.

Service instance tokens expire 20 minutes after creation.

To retrieve a service instance token, view the service instance details in the IBM Software Hub web interface:

  1. Log into the IBM Software Hub web interface.
  2. Navigate to My Instances and select the appropriate IBM Match 360 instance.
  3. Click View details.

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

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

Using a service instance token to authorize your IBM Match 360 API calls

Pass the service instance token as Bearer token in the Authorization header of an API request to authorize your IBM Match 360 API calls.

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

curl -X GET 'https://{cpd_cluster_host}/<API_PATH>' -H 'Authorization: ZenApiKey {token}' -H 'Content-type: application/json'

Replace the following values in the curl command:

  • <API_PATH> - the path of your desired API (Such as /mdm/model/v1/jobs).
  • {token} - the service instance authentication token.
curl -H "Authorization: Bearer {token}" "https://{cpd_cluster_host}/v1/{method}"

To get the service instance ID by using the API, run the following curl command:

curl -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances?add_on_type=mdm-app' -H 'Authorization: ZenApiKey {token}' -H 'Content-type: application/json'

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

To get a service instance token by using the API, run the following curl command:

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

Replace the following values in the command:

  • <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.

curl -X GET 'https://{cpd_cluster_host}//mdm/model/v1/jobs' -H 'Authorization: ZenAPIKey {token}' -H 'Content-type: application/json'

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/configuration/v1/config_data_model/publish_model?project_id=config_42d00915_1497_4d65_90af_cfd09d015769%3A31925406598685396&crn=CRN"

Using API Explorer to access the IBM Match 360 API

To use the Swagger UI API Explorer with the IBM Match 360 API, you must first obtain a service instance ID. Then, you can navigate to the Swagger UI API Explorer and use it with the IBM Match 360 API. Get your service instance ID by using the /zen-data/v3/service_instances API.

Run the following curl command:

curl -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances?add_on_type=mdm-app' -H 'Authorization: ZenApiKey {token}' -H 'Content-type: application/json'

The curl command produces the following response in JSON format:

{
   "limit":20,
   "offset":0,
   "service_instances":[
      {
         "addon_type":"mdm-app",
         "addon_version":"1.0.0",
         "created_at":"<TIMESTAMP>",
         "description":"string",
         "display_name":"<SERVICE-DISPLAY-NAME>",
         "id":"<SERVICE-INSTANCE-ID>"
         ...
      }
   ],
   "total_count":1
}

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

After you have the service instance ID, you can authorize the API explorer:

  1. Navigate to the Swagger API Explorer by browsing to https://{cpd_cluster_host}/<MDM_INSTANCE_ID>/api-model/explorer/# (replace <MDM_INSTANCE_ID> with your service instance ID number).
  2. Click Authorize at the top of the page.
  3. Enter the service instance token.
  4. Click Authorize and then click Close.

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

To get the service instance ID by using the API, run the following curl command:

curl -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances?add_on_type=mdm-app' -H 'Authorization: ZenApiKey {token}' -H 'Content-type: application/json'

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

Methods

Get Config Data Model Type Attributes

Gets all the attributes of a specific 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 > User > Access.

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • type_category
    Required*
    string

    The type category of the data model attributes

  • type_name
    Required*
    string

    The type name of the type category to identify data model attributes

Response

Response Body

ConfigDataModelAttributes

The Config Data Model attributes for a record type.

Status Code

  • 200

    Config Data Model Type attributes retrieved.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in 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 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 > User > Access.

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

ConfigDataModel

Collection of record and relationship types and system properties definition

Status Code

  • 200

    Config data model is returned

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
ConfigDataModel

Collection of record and relationship types and system properties definition

Examples: 
{
  "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"
        }
      ]
    }
  ]
}

Response

Response Body

ConfigDataModel

Collection of record and relationship types and system properties definition

Status Code

  • 200

    Config data model is replaced.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

Example responses
  • {
  "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 configuration ms health status

Gets the configuration health status.

GET /mdm/v1/configuration_health

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • target
    string

    a target of the health check, ie. fdb, rabbitmq

    Default: all

Response

Response Body

ConfigurationHealth

Response object for get configuration api health

Status Code

  • 200

    Configuration ms health status is returned

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting configuration ms health status. An internal error occurred while attempting to get configuration ms health status

Example responses
  • {
  "status": "healthy/unhealthy.",
  "severity": "info/critical.",
  "message": "Additional details of the configuration health status.",
}

Export configuration data to shared volume

Export all configuration metadata to the folder path in shared volume

POST /mdm/v1/configuration_export

Authorization

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • 204

    Successfully exported configuration metadata.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Fetch the current value of job status polling metadata

Fetch the current value of job status polling metadata. This is useful to debug the issues with auto resumption of matching job after pod restart

GET /mdm/v1/job_status_polling_metadata

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

MatchingJobStatusPollingMetadata

Status Code

  • 200

    Fetched job status polling metadata successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Job status poling metadata do not exist in the system.

  • 500

    Unexpected error occured while fetching job status poling metadata.

No Sample Response

This method does not specify any sample responses.

Replace job status polling metadata

Replace job status polling metadata

PUT /mdm/v1/job_status_polling_metadata

Authorization

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
PairDecisionCreateRequest

Request details for creating comparison record pair decision.

Examples: 
{
  "polling_job_invocation_last_updated_time": "2024-01-01T10:10:10.122Z",
  "polling_job_owner_instance_name": "nmdm-config-12344"
}

Response

Response Body

PairDecision

Pair and corresponding user decision details.

Status Code

  • 201

    Job status polling metadata replaced successfully.

  • 400

    The request you used is invalid. Please revalidate and try again.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Internal error occurred in replacing Job status polling metadata.

No Sample Response

This method does not specify any sample responses.

Fetch existing mapping pattern

Fetch existing mapping pattern.

GET /mdm/v1/mapping_pattern

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

MappingPattern

Response wrapper with details of Asset Mapping patterns.

Status Code

  • 200

    Fetched existing mapping pattern successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Mapping patterns do not exist in the system.

  • 500

    Unexpected error occured while fetching mapping patterns.

Example responses
  • {
  "id": "config_1:4186180239988952",
  "last_update_date": "2024-04-12T06:11:09.000Z",
  "created_date": "2024-04-12T00:00:00.000Z",
  "mapping_patterns": [
    {
      "mapping_pattern_hash": "307e7a7d9757fb186ad8f106d4d92279e366b6c1f723b4de068f65a63d2303f3",
      "mapping_pattern_id": "436cbd13-fd5b-380d-bb2a-870cb64983e5",
      "mapping_pattern_name": "",
      "source_of_mapping": "config_metadata",
      "mapping_pattern_last_updated_date": "2024-01-05T15:28:12.000Z",
      "assets": [
        {
          "project_id": "",
          "asset_id": "",
          "asset_name": ""
        }
      ],
      "asset_record_type": "person",
      "asset_type": "person",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "data_mapping_name": "record_id",
          "exclude_column": false
        },
        {
          "key": "COLUMN2",
          "data_mapping_attribute_type": "person_name",
          "data_mapping_name": "legal_name.middle_name",
          "exclude_column": false
        }
      ]
    }
  ]
}

Store/Replace mapping patterns.

Store/Replace mapping patterns.

PUT /mdm/v1/mapping_pattern

Authorization

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
MappingPattern

Response wrapper with details of Asset Mapping patterns.

Examples: 
{
  "id": "config_1:4186180239988952",
  "last_update_date": "2024-04-12T06:11:09.000Z",
  "created_date": "2024-04-12T00:00:00.000Z",
  "mapping_patterns": [
    {
      "mapping_pattern_hash": "307e7a7d9757fb186ad8f106d4d92279e366b6c1f723b4de068f65a63d2303f3",
      "mapping_pattern_id": "436cbd13-fd5b-380d-bb2a-870cb64983e5",
      "mapping_pattern_name": "",
      "source_of_mapping": "config_metadata",
      "mapping_pattern_last_updated_date": "2024-01-05T15:28:12.000Z",
      "assets": [
        {
          "project_id": "",
          "asset_id": "",
          "asset_name": ""
        }
      ],
      "asset_record_type": "person",
      "asset_type": "person",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "data_mapping_name": "record_id",
          "exclude_column": false
        },
        {
          "key": "COLUMN2",
          "data_mapping_attribute_type": "person_name",
          "data_mapping_name": "legal_name.middle_name",
          "exclude_column": false
        }
      ]
    }
  ]
}

Response

Response Body

MappingPattern

Response wrapper with details of Asset Mapping patterns.

Status Code

  • 200

    Stored/Replaced mapping pattern successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Unexpected error occured while storing/updating mapping patterns.

Example responses
  • {
  "mapping_patterns": [
    {
      "mapping_pattern_hash": "307e7a7d9757fb186ad8f106d4d92279e366b6c1f723b4de068f65a63d2303f3",
      "mapping_pattern_id": "436cbd13-fd5b-380d-bb2a-870cb64983e5",
      "mapping_pattern_name": "",
      "source_of_mapping": "config_metadata",
      "mapping_pattern_last_updated_date": "2024-01-05T15:28:12.000Z",
      "assets": [
        {
          "project_id": "",
          "asset_id": "",
          "asset_name": ""
        }
      ],
      "asset_record_type": "person",
      "asset_type": "person",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "data_mapping_name": "record_id",
          "exclude_column": false
        },
        {
          "key": "COLUMN2",
          "data_mapping_attribute_type": "person_name",
          "data_mapping_name": "legal_name.middle_name",
          "exclude_column": false
        }
      ]
    }
  ]
}

Get matching statistics

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

GET /mdm/v1/match_statistics

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type of match statistics

    Example: person

  • entity_type
    Required*
    string

    Entity type of match statistics

    Example: person_entity

Response

Response Body

MatchStatistics

The Statistics of the match process results.

Status Code

  • 200

    Statistics retrieved

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Error occurred in get resource process. Resource does not exist

  • 500

    Error in fetching statistics

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

Lists the pair analysis for given tenant.

GET /mdm/v1/pair_analysis

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

PairAnalysisResponse

Status Code

  • 200

    Pair analysis is fetched successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    The pair analysis for the given record and entity type not found.

  • 500

    Error in getting Pair analysis.

No Sample Response

This method does not specify any sample responses.

Add pair analysis results

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

POST /mdm/v1/pair_analysis

Authorization

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
PairAnalysisResponse
Examples: 
{
  "entity_type": "person_entity",
  "record_type": "person",
  "tuned_config": "{'threshold': 0.156,}",
  "base_config": "{'threshold': 0.156,}",
  "pair_offset": 1,
  "pair_gen_job_id": "121",
  "tuning_job_id": "121",
  "status": "Completed"
}

Response

Response Body

PairAnalysisResponse

Status Code

  • 201

    Pair Analysis created successfully.

  • 400

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

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Internal error occured in creating asset for the given Pair analysis data.

No Sample Response

This method does not specify any sample responses.

Delete all pair analysis for a tenent from database.

This is a internal REST call.

DELETE /mdm/v1/pair_analysis

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • default

    default response

No Sample Response

This method does not specify any sample responses.

Patch pair analysis

Updates the pair analysis. Unknown attributes will be ignored

PATCH /mdm/v1/pair_analysis

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type of comparison pair

  • entity_type
    Required*
    string

    Entity type of comparison pair

Request Body

Required*
UpdatePairAnalysis
Examples: 
{
  "tuned_config": "{'threshold'': 0.156,}",
  "base_config": "{'threshold'': 0.156,}",
  "pair_offset": 1,
  "pair_gen_job_id": "121",
  "tuning_job_id": "121",
  "status": "Completed"
}

Response

Response Body

UpdatePairAnalysis

Status Code

  • 200

    Pair analysis was updated successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    The pair analysis for the given record and entity type not found.

  • 500

    Error updating pair analysis.

No Sample Response

This method does not specify any sample responses.

Get pair analysis

Gets the pair analysis for given entity and record type.

GET /mdm/v1/pair_analysis/data

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type of comparison pair

  • entity_type
    Required*
    string

    Entity type of comparison pair

Response

Response Body

PairAnalysisResponse

Status Code

  • 200

    Pair analysis is fetched successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    The pair analysis for the given record and entity type not found.

  • 500

    Error in getting Pair analysis.

No Sample Response

This method does not specify any sample responses.

Delete comparison record pair decision

Delete the comparison record pair decision.

DELETE /mdm/v1/pair_decisions

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type of comparison pair

  • entity_type
    Required*
    string

    Entity type of comparison pair

  • record_number_1
    string

    Record identifier of comparison pair

  • record_number_2
    string

    Record identifier of comparison pair

Response

Status Code

  • 204

    Comparison record pair decision for given id is fetched successfullly.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Get configuration metadata

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

GET /mdm/v1/configuration_metadata

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

Status Code

  • 200

    configuration metadata for given id is fetched successfullly.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting configuration metadata.

Example responses
  • {
  "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, etc.

PUT /mdm/v1/configuration_metadata

Authorization

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
ConfigurationMetadata

Configuration metadata details.

Examples: 
{
  "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"
    }
  ]
}

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

Status Code

  • 200

    configuration metadata successfully replaced

  • 400

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

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Internal error occured in replacing configuration metadata.

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
ConfigurationMetadata

Configuration metadata details.

Examples: 
{
  "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"
    }
  ]
}

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

Status Code

  • 200

    configuration metadata successfully updated

  • 400

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

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Internal error occured in getting configuration metadata.

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

Regenerate the mapping pattern ID in project metadata using the current logic

The previous algorithm for generating the mapping pattern has been replaced with new algorithm.The existing mapping pattern id in the project metadata should be regenerated by using the current mapping pattern id generation logic.

POST /mdm/v1/configuration_metadata/regenerate_mapping_pattern_id

Authorization

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

Status Code

  • 200

    The regeneration of the mapping pattern id has been completed successfully

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Unexpected error occurred during the regeneration of mapping pattern id.

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"
    }
  ]
}

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 > User > Access.

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • status
    string

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

    Example: In-progress

Response

Response Body

ProcessList

Response wrapper with the list of Processes.

Status Code

  • 200

    Processes retrieved.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting processes.

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
ProcessRequest

Process creation request details.

Examples: 
{
  "process_name": "publish_data",
  "asset_source_details": {
    "project": {
      "cos_endpoint": "https://s3.us-south.cloud-object-storage.appdomain.cloud",
      "cos_bucket_name": "bucket-name",
      "cos_api_key": "project_api_key"
    }
  },
  "initiator": "IAM ID"
}
{
  "process_name": "publish_data",
  "asset_source_details": {
    "project": {
      "cos_endpoint": "https://s3.us-south.cloud-object-storage.appdomain.cloud",
      "cos_bucket_name": "bucket-name",
      "cos_api_key": "project_api_key"
    }
  },
  "asset_ids": "asset-1,asset-2",
  "initiator": "IAM ID"
}
{
  "process_name": "delete_asset",
  "asset_ids": "asset-id-1,asset-id-2",
  "initiator": "IAM ID"
}
{
  "process_name": "publish_model",
  "initiator": "IAM ID"
}
{
  "process_name": "match",
  "record_type": "person",
  "entity_type": "person_entity",
  "do_derive": true,
  "do_match": true,
  "do_sync": true,
  "do_report": true,
  "do_force_derive": true,
  "do_force_matching": true,
  "do_force_entity_sync": true,
  "report_job_list": entity_summary,
  "initiator":"IAM ID"
}
{
  "process_name": "import_snapshot",
  "initiator": "IAM ID",
  "snapshot_summary": {
    "id": "Snapshot_1651495290688"
  }
}
{
  "process_name": "import_snapshot",
  "initiator": "IAM ID",
  "snapshot_summary": {
    "created_time": "1651495290689",
    "description": "",
    "user": "user",
    "name": "test_snapshot"
  },
  "map_resources": {},
  "compare_spec_resources": {},
  "composite_rules": {},
  "match_settings": {},
  "set_resources": {},
  "data_model": {},
  "algorithms": {},
  "mapping_patterns": [
    {}
  ]
}

Response

Response Body

ProcessStatus

Process Status.

Status Code

  • 201

    Process created successfully.

  • 400

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

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting processes.

Example responses
  • {
  "status": "In-Progress_bulkderive",
  "message": "Matching is in progress."
}
  • {
  "status": "In-progress",
  "message": "Publish model is initiated."
}
  • {
  "status": "In-progress",
  "message": "Import Snapshot 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"
}

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 > User > Access.

  • mdm-oc.configurator.manage

Request

Path Parameters

  • asset_id
    Required*
    string

    Unique identifier of project asset

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
AssetMetadataUpdateRequest

Request object for updating an asset.

Examples: 
{
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": "2020-05-12T13:21:21.727Z",
  "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
    }
  ]
}

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

  • 200

    Asset replaced successfully.

  • 400

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

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

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

Patch configuration metadata asset

Update the asset fields in the configuration metadata with the information provided in the request. Only the fields given in the request will be updated.

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

Authorization

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

  • mdm-oc.configurator.manage

Request

Path Parameters

  • asset_id
    Required*
    string

    Unique identifier of project asset

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
AssetMetadataPatchRequest

Request object for updating an asset.

Examples: 
{
  "asset_record_type": "Person",
  "asset_status": "Mapped"
}

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

  • 200

    Asset fields updated successfully.

  • 400

    Error in updating the asset. The request is invalid. Please revalidate the input and try again.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Internal error occurred in updating the asset for the given asset id.

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

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 > User > Access.

  • mdm-oc.configurator.manage

Request

Path Parameters

  • process_name
    Required*
    string

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

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    string

    Unique record type associated with the process

    Example: person

  • entity_type
    string

    Unique entity type associated with the process

    Example: person_entity

Response

Response Body

ProcessModelStatus

Details of the Process.

Status Code

  • 200

    Process retrieved.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

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

  • 500

    Error in getting process.

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

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 > User > Access.

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
AssetMetadataCreateRequest

Request details for creating new Data Asset.

Examples: 
{
  "asset_id": "asset_id",
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": "2020-05-12T13:21:21.727Z",
  "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
    }
  ]
}

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

  • 201

    Asset created successfully.

  • 400

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

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

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

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 > User > Access.

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • 201

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

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Get version properties from config map.

Get version properties from config map. It will contain the running version of the service

GET /mdm/v1/data/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

SystemLiveness

Whether the system is live or not.

Status Code

  • 200

    The version properties has been retrieved successfully

  • 500

    An internal error occurred while retrieving the version properties.

  • 503

    Service is not available and can not perform the operation now

No Sample Response

This method does not specify any sample responses.

Get the liveness status of the system

GET /mdm/v1/matching_alive_status

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

object

Status Code

  • 200

    The liveness check was successfully performed and the api is considered live and healthy.

  • 500

    Problem getting liveness status. An internal error occurred while attempting to determine the liveness status.

  • 503

    Liveness status is NOT LIVE.

No Sample Response

This method does not specify any sample responses.

Get the readiness status of the system

GET /mdm/v1/matching_ready_status

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

object

Status Code

  • 200

    The readiness check was successfully performed and the api is considered ready to receive requests.

  • 500

    Problem getting readiness status. An internal error occurred while attempting to determine the readiness status.

  • 503

    Readiness status is NOT READY. The metadata store is not available.

No Sample Response

This method does not specify any sample responses.

Get the version of the matching microservice

GET /mdm/v1/matching/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

object

Status Code

  • 200

    The version check was successfully performed.

  • 500

    Problem getting version. An internal error occurred while attempting to determine the version.

No Sample Response

This method does not specify any sample responses.

Get the version of the model microservice

GET /mdm/v1/model/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

object

Status Code

  • 200

    The version check was successfully performed.

  • 500

    Problem getting version. An internal error occurred while attempting to determine the version.

No Sample Response

This method does not specify any sample responses.

Get snapshot by Id

Get snapshot by Id

GET /mdm/v1/snapshots/{id}

Authorization

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

  • mdm-oc.configurator.read

Request

Path Parameters

  • id
    Required*
    string

    Id of the snapshot

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

SnapshotDetailedResponse

Response wrapper with the details of the snapshot

Status Code

  • 200

    Snapshot with given id is fetched successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Update a snapshot of model assets

  • This service updates the name and description of a snapshot.
PUT /mdm/v1/snapshots/{id}

Authorization

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

  • mdm-oc.configurator.manage

Request

Path Parameters

  • id
    Required*
    string

    The unique identifier of a snapshot

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
UpdateSnapshotSummary

Request wrapper object for snapshot summary of model assets

Response

Response Body

UpdateSnapshotSummary

Request wrapper object for snapshot summary of model assets

Status Code

  • 200

    The snapshot has been successfully updated.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

No Sample Response

This method does not specify any sample responses.

delete snapshot by Id

delete snapshot by Id

DELETE /mdm/v1/snapshots/{id}

Authorization

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

  • mdm-oc.configurator.read

Request

Path Parameters

  • id
    Required*
    string

    Id of the snapshot

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

SnapshotDetailedResponse

Response wrapper with the details of the snapshot

Status Code

  • 200

    Snapshot with given id is deleted successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Get snapshots

Get snapshots

GET /mdm/v1/snapshots

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

SnapshotListResponse

Response wrapper with the list of Snapshots.

Status Code

  • 200

    Snapshots are fetched successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Create a snapshot of config assets

  • This service creates a snapshot of current config assets.
POST /mdm/v1/snapshots

Authorization

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

  • mdm-oc.configurator.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
SnapshotSummaryRequest

Request wrapper object for post a snapshot of model assets

Examples: 
{
  "name": "Snapshot Name",
  "description": "Description of the Snapshot"
}

Response

Response Body

SnapshotSummaryRequest

Request wrapper object for post a snapshot of model assets

Status Code

  • 201

    The snapshot of model assets has been successfully created.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Compare snapshot with current configuration

Compare snapshot

PUT /mdm/v1/snapshots/compare

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
SnapshotCompareRequest

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

Examples: 
{
  "data_model": {},
  "match_settings": {},
  "composite_rules": {},
  "snapshot_summary": {},
  "algorithms": {},
  "map_resources": {},
  "compare_spec_resources": {},
  "set_resources": {},
  "mapping_patterns": [
    {}
  ]
}

Response

Response Body

SnapshotCompareResponse

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

Status Code

  • 200

    Snapshot comparison is generated and fetched successfully.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error in getting configuration metadata.

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

Suggest data mappings

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

POST /mdm/v1/suggest_data_mappings

Authorization

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type for data mapping suggestions

    Example: person

Request Body

Required*
SuggestedDataMappingRequest

Suggested Data Mapping Request details.

Examples: 
{
  "columns": [
    {
      "key": "COLUMN1",
      "classified_class": "X"
    }
  ]
}

Response

Response Body

SuggestedDataMapping

Response wrapper with details of Suggested Data Mappings.

Status Code

  • 200

    Suggested mappings are fetched

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Unexpected error occured while getting data mappings.

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

  • mdm-oc.configurator.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type for matching attribute suggestions

Response

Response Body

SuggestedMatchAttributes

Response wrapper for attributes suggested for running match process.

Status Code

  • 200

    Suggested matching attributes are retrieved

  • 400

    Project assets are missing or in invalid state.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Error occured while getting suggested matching attributes.

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

Initiate weight tuning job

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

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type of match statistics

    Example: person

  • entity_type
    Required*
    string

    Entity type of match statistics

    Example: person_entity

Response

Response Body

TuningJobResponse

Response object for asynchronous processing of a tuning job

Status Code

  • 201

    The weight tuning job has been successfully created.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

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

Get version properties from config map.

Get version properties from config map. It will contain the running version of the service

GET /mdm/v1/configuration/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • 200

    The version properties has been retrieved successfully

  • 500

    An internal error occurred while retrieving the version properties.

  • 503

    Service is not available and can not perform the operation now

No Sample Response

This method does not specify any sample responses.

Start an operation to bulk delete data from the graph

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

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

Authorization

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

  • mdm-oc.data.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

  • batch_size
    integer

    batch size of the query parameter

    Default: 1000

    Example: 1000

Request Body

Required*
BulkDeleteRequest

Valid object defining the bulk delete job information.

Response

Response Body

BulkDeleteJob

Information about a bulk delete job.

Status Code

  • 202

    The bulk delete job was successfully started.

  • 400

    Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

Example responses
  • {
  "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
group.properties
group_association.properties
record
--[record data files]
relationship
--[relationship data files]
group
--[group data files]
group_association
--[group_association 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.
  • To enable efficient deletion of a data asset in the future after bulk loading completes, please ensure that the optional 'collection_id' attribute is specified in the set of properties defined in the request. Alternatively, the value can be configured using the 'json.collection.id' or 'csv.collection.id' property in the data load properties file, depending on your data structure.
  • For CSV import option if includes_header_row is set as true then header must be present in all partitions.

To specify a COS directory, directory_path should be in the format <bucket_name>/<directory_path>. If the COS bucket is not the provided tenant bucket, the origin field must be set to external and an IAM API key with access to the bucket must be provided in the api_key field. If the data directories do not follow the above format, the data structure field must be provided.

POST /mdm/v1/bulk_load

Authorization

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

  • mdm-oc.data.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • batch_size
    integer

    Batch Size

    Example: 100

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

  • is_initial_load
    boolean

    Is initial load of data

    Default: false

    Example: true

Request Body

Required*
BulkLoadRequest

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

Response

Response Body

BulkLoadJob

Information about a bulk load job.

Status Code

  • 202

    The bulk load job was successfully started.

  • 400

    Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

  • 503

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

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

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.
  • If 'operation_strategy' is set to 'patch', any attributes not specified will be unchanged on the existing record or relationship. Attributes and fields can be removed by setting the attribute or field value to null. If 'operation_strategy' is not set to 'patch', existing attributes on the record or relationship will be overwritten.
  • 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 > User > Access.

  • mdm-oc.data.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • ignore_redundant_updates
    boolean

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

    Default: false

Request Body

Required*
SyncUpdateRequest

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

Response

Status Code

  • 204

    The updates have been successfully processed.

  • 400

    Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

No Sample Response

This method does not specify any sample responses.

Get data health status

GET /mdm/v1/data_health

Authorization

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

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • target
    string

    a target of the health check for fdb (fdb, es, rabbitmq, all) and neo4j (neo4j, rabbitmq, all)

    Default: all

Response

Response Body

DataHealthStatusResponse

Response object for get data health

Status Code

  • 200

    The data service is healthy on the specified target.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Preview the composite view of an entity given set of records

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

POST /mdm/v1/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 > User > Access.

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    Required*
    string

    Entity Type

Request Body

Required*
RecordIdList

List of recordIds for which composite view is to be found

Examples: 
{
  "record_ids": [
    216754896528315940,
    216754343254354370,
    254315143644376540,
    216754896528312320,
    216234532528315940,
    216734341123434560,
    216798213768311230,
    232131232123565950,
    216754893465787900,
    216432654765876580
  ]
}

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

  • 200

    The composite view has been successfully retrieved.

  • 400

    Problem getting composite view of entity. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting composite view of entity. Entity with id <entity_id> does not exist.

  • 500

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

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    string

    The unique identifier of the entity.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • offset
    integer

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

    Default: 0

  • include
    string[]

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

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]
  • exclude
    string[]

    Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]
  • include_total_count
    boolean

    Flag to include the total record count on pages other than the first.

    Default: true

Response

Response Body

DataRecordsResponse

Paged information about a collection of records.

Status Code

  • 200

    The entity records have been successfully retrieved.

  • 400

    Problem getting records for entity. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

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

  • 500

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

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

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 > User > Access.

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    string

    The unique identifier of the entity.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • include
    string[]

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

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]
  • exclude
    string[]

    Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

  • 200

    The composite view has been successfully retrieved.

  • 400

    Problem getting composite view of entity. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting composite view of entity. Entity with id <entity_id> does not exist.

  • 500

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

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

Replace entity-level attributes of a persisted entity

Replace the existing persisted entity with the new set of attributes. Any existing editable entity-level attributes not specified in the request will be removed from the entity.

PUT /mdm/v1/entities/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The unique identifier of the entity.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataEntity

Valid object defining the attributes of an entity to replace the existing entity-level attributes. All non-entity attributes will be ignored.

Examples: 
{
  "attributes": {
    "entity_last_updated": "1603572360787",
    "family_name": {
      "value": "Doe"
    }
  },
  "type": "entity",
  "type_name": "person_entity"
}

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

  • 200

    The entity attributes have been successfully updated.

  • 400

    Problem updating attributes of entity. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem updating attributes of entity. Entity is not persisted on the graph.

  • 500

    Problem updating attributes of entity. An internal error occurred while attempting to update the entity attributes.

Example responses
  • {
  "entity": {
    "attributes": {
      "birth_date": {
        "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"
      },
      "family_name": {
        "attribute_last_updated": "1548936483016",
        "value": "Doe"
      },
      "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 relationships for an entity

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

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

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    string

    The ID of the entity.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • relationship_types
    string[]

    The relationship types to return.

  • include_record_relationships
    string

    Whether to include entity record relationships to other nodes.

    Default: false

  • offset
    integer

    The number of relationships to skip over.

    Default: 0

  • limit
    integer

    The number of relationships to be returned. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

  • source_include
    string[]

    Attributes from the data model to include in the results for the source vertex.

    Possible values: contains only unique items

    Examples: 
    [
  "all"
]
  • target_include
    string[]

    Attributes from the data model to include in the results for the target vertex.

    Possible values: contains only unique items

    Examples: 
    [
  "all"
]

Response

Response Body

DataRelationshipsResponse

Paged information about a collection of relationships.

Status Code

  • 200

    The relationships have been successfully retrieved.

  • 400

    Problem getting relationships for entity. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting relationships for entity. Entity not found.

  • 500

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

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

List the records associated with entity records

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

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

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    string

    The unique identifier of the entity.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    The type of records to return in results.

  • relationship_type
    Required*
    string

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

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • offset
    integer

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

    Default: 0

  • include
    string[]

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

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]
  • exclude
    string[]

    Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]
  • include_total_count
    boolean

    Flag to include the total record count on pages other than the first.

    Default: true

Response

Response Body

RelatedRecords

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

Status Code

  • 200

    The related records for the entity have been successfully retrieved.

  • 400

    Problem getting related records for entity. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

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

  • 500

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

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

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 > User > Access.

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • offset
    integer

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

    Default: 0

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • include_expired
    boolean

    Whether to include exports with expired files.

    Default: true

Response

Response Body

DataExports

Paged information about a collection of exports.

Status Code

  • 200

    The list of exports was retrieved successfully.

  • 400

    Problem getting list of exports. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

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

The operation runs as follows:

  • On public cloud, instance metadata must be configured and include valid bucket credentials before an export job is started.
  • A compression type must be provided when a partition type of 'executor_count' is specified.
POST /mdm/v1/data_exports

Authorization

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

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • compression_type
    string

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

    Allowable values: [tar,tgz,zip]

  • partition_type
    string

    The type of partitioning used when exporting the results.

    Allowable values: [none,executor_count]

    Default: none

  • max_count
    integer

    The maximum number of results to be returned. The maximum limit is 10000.

    Possible values: value ≤ 10000

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

  • group_multi_values
    string

    Group multi value field values in single column

    Default: true

    Example: true

Request Body

Required*
ExportRequest

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

Response

Response Body

DataExport

Information about an export.

Status Code

  • 202

    The export job was started successfully.

  • 400

    Problem starting export job. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem starting export job. An internal error occurred.

Example responses
  • {
  "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"
  },
  "include_attributes": {
    "record_attributes": [
      {
        "record_type": "person",
        "attribute_names": [
          "legal_name.given_name"
        ]
      }
    ]
  },
  "exclude_attributes": {
    "record_attributes": [
      {
        "record_type": "person",
        "attribute_names": [
          "legal_name.last_name"
        ]
      }
    ]
  }
}

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 > User > Access.

  • mdm-oc.data.read

Request

Path Parameters

  • export_id
    Required*
    string

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

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

binary

Status Code

  • 200

    The export file has been successfully retrieved.

  • 400

    Problem downloading export file. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem downloading export file. The export does not exist.

  • 410

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

  • 500

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

  • 503

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

No Sample Response

This method does not specify any sample responses.

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 > User > Access.

  • mdm-oc.data.read

Request

Path Parameters

  • export_id
    Required*
    string

    The ID of the export.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

DataExport

Information about an export.

Status Code

  • 200

    The export information was retrieved successfully.

  • 400

    Problem getting export information. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting export information. The export does not exist.

  • 500

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

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

Get export jobs for all users

Get export job details from EM-UI for all users

GET /mdm/v1/ui_exports

Authorization

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

  • mdm-oc.data.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • offset
    integer

    The number of records to skip over.

    Default: 0

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

Response

Response Body

JsonUIAllExportsResponse

Information about a Json UI Exports Response for all users.

Status Code

  • 200

    The export jobs details for all users has been successfully retrieved.

  • 400

    Problem getting export jobs. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting exports. An internal error occurred while attempting to get the exports.

Example responses
  • [
{ "export_jobs": {
 "33884041791950441": "abc.csv",
 "3434155992631831": "exportdatasample.csv",
 "26265886994529861": "asdsaa.csv",
 "4527694741782481": "test.csv",
 "34569389088179072": "testss.csv",
 "9825814994662883": "testss00.csv"
} 
}, "exports_id": "test-user-exports"
]

Get export jobs

Get export job details from EM-UI

GET /mdm/v1/ui_exports/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the export doc.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

JsonUIExportsResponse

Information about a Json UI Exports Response.

Status Code

  • 200

    The export jobs details has been successfully retrieved.

  • 400

    Problem getting export jobs. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting exports. An internal error occurred while attempting to get the exports.

Example responses
  • {
  "export_jobs": {
    "33884041791950440": "abc.csv",
    "3434155992631832": "exportdatasample.csv",
    "26265886994529867": "asdsaa.csv",
    "4527694741782488": "test.csv",
    "34569389088179071": "testss.csv",
    "9825814994662888": "testss00.csv"
  }
}

Add export job to set of jobs

Add export job to set of jobs from EM-UI

PUT /mdm/v1/ui_exports/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the exports doc.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
UIExports

Valid object defining the exportJob to be added.

Examples: 
{
  "export_jobs": {
    "33884041791950440": "abc.csv",
    "3434155992631832": "exportdatasample.csv",
    "26265886994529867": "asdsaa.csv",
    "4527694741782488": "test.csv",
    "34569389088179071": "testss.csv",
    "9825814994662888": "testss00.csv"
  }
}

Response

Response Body

JsonUIExportsResponse

Information about a Json UI Exports Response.

Status Code

  • 200

    The export job has been successfully added.

  • 400

    Problem adding export job. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem adding export job. An internal error occurred while attempting to add the export job.

Example responses
  • {
  "export_jobs": {
    "33884041791950440": "abc.csv",
    "3434155992631832": "exportdatasample.csv",
    "26265886994529867": "asdsaa.csv",
    "4527694741782488": "test.csv",
    "34569389088179071": "testss.csv",
    "9825814994662888": "testss00.csv"
  }
}

Delete export job from a set of jobs

Delete export job from a set of jobs from EM-UI

DELETE /mdm/v1/ui_exports/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the exports doc.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • export_job_id
    string

    Export Job Id to be deleted

Response

Response Body

JsonUIExportsResponse

Information about a Json UI Exports Response.

Status Code

  • 200

    The export job has been successfully deleted.

  • 400

    Problem deleting export job. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem deleting export job. An internal error occurred while attempting to delete the export job.

Example responses
  • {
  "export_jobs": {
    "33884041791950440": "abc.csv",
    "3434155992631832": "exportdatasample.csv",
    "26265886994529867": "asdsaa.csv",
    "4527694741782488": "test.csv",
    "34569389088179071": "testss.csv",
    "9825814994662888": "testss00.csv"
  }
}

Get all the groups for a given id

This function retrieves all the groups to which the given object is part of.

GET /mdm/v1/groups/by_associated_object/{id}

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    string

    id of respective entity

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • type
    Required*
    string

    type of the given id

  • type_name
    Required*
    string

    type name of the given id

  • offset
    integer

    The number of groups to skip over.

    Default: 0

  • limit
    integer

    The number of groups to be returned. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

  • include_total_count
    boolean

    Flag to include the total group count.

    Default: false

Response

Response Body

DataGroupResponse

Information about a group.

Status Code

  • 200

    The groups has been retrieved successfully.

  • 400

    Problem fetching groups. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem fetching groups. An internal error occurred while attempting to retrieve groups.

Example responses
  • {
  "first": {
    "href": ""
  },
  "last": {
    "href": ""
  },
  "limit": 10,
  "offset": 0,
  "total_count": 2,
  "groups": [
    {
      "type": "group",
      "type_name": "branch_bank_customer",
      "id": "12324",
      "attributes": {
        "group_id": "999",
        "group_source": "MDM",
        "group_number": 1002,
        "group_name": "toronto_branch_bank_customers",
        "description": "test 2",
        "group_value": [
          {
            "value": "x",
            "priority": "1",
            "category": "cat1"
          },
          {
            "value": "y",
            "priority": "4",
            "category": "cat2"
          }
        ],
        "status": "draft",
        "start_date": "456456",
        "created_date": "456456",
        "group_last_updated": "123456",
        "last_updated_user": "user2",
        "group_associations": [
          {
            "relationship_id": "source_id",
            "relationship_source": "MDM",
            "member_role": [
              {
                "role": "manager",
                "start_date": "457867234"
              }
            ],
            "source": {
              "group_id": "source_id",
              "group_source": "MDM"
            },
            "target": {
              "record_id": "342432",
              "record_source": "MDM"
            }
          }
        ]
      }
    },
    {
      "type": "group",
      "type_name": "generic_group",
      "id": "988",
      "attributes": {
        "group_id": "988",
        "group_source": "MDM",
        "group_number": 1008,
        "group_name": "generic_group",
        "description": "test 1",
        "group_value": [
          {
            "value": "x",
            "priority": "1",
            "category": "cat1"
          },
          {
            "value": "y",
            "priority": "4",
            "category": "cat2"
          }
        ],
        "status": "draft",
        "start_date": "456456",
        "created_date": "456456",
        "group_last_updated": "123456",
        "last_updated_user": "user2",
        "group_associations": [
          {
            "relationship_id": "source_id",
            "relationship_source": "MDM",
            "member_role": [
              {
                "role": "manager",
                "start_date": "457867234"
              }
            ],
            "source": {
              "group_id": "source_id",
              "group_source": "MDM"
            },
            "target": {
              "record_id": "342432",
              "record_source": "MDM"
            }
          }
        ]
      }
    }
  ]
}

Get group for a given id

Retrieves the group, for a given id and typeName

GET /mdm/v1/groups/{id}

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    Id of the group

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • group_type
    Required*
    string

    type of the group

  • included_associations
    string

    The associated objects.

    Default: none

  • offset
    integer

    The number of group nodes to skip over.

    Default: 0

  • limit
    integer

    The number of group nodes to be returned. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

  • compute_member_count
    boolean

    Flag to include the member group count.

    Default: true

Response

Response Body

DataGroupResponse

Information about a group.

Status Code

  • 200

    The group has been retrieved successfully.

  • 400

    Problem fetching group. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem processing request. Group not found for given id and type

  • 500

    Problem fetching group. An internal error occurred while attempting retrieve group.

Example responses
  • {
  "group": {
    "attributes": {
      "entity_name": {
        "attribute1_value": [
          "CONTACT"
        ]
      },
      "group_description": {
        "attribute1_value": [
          "Squad for Group Feature"
        ]
      },
      "group_display_name": {
        "attribute1_value": [
          "Group Feature Squad"
        ]
      },
      "group_id": "200",
      "group_name": {
        "attribute1_value": [
          "Group Feature Squad"
        ]
      },
      "group_number": 200,
      "group_source": "MDM",
      "party_group_value": {
        "attribute1_value": [
          "Status"
        ],
        "misc_value_priority_value": [
          "High"
        ],
        "misc_value_description": [
          "test 2 description"
        ],
        "attribute0_type": [
          "9"
        ],
        "attribute0_value": [
          "Customer Relationship Status"
        ],
        "misc_value_type": [
          "2"
        ],
        "misc_value_priority_type": [
          "2"
        ],
        "misc_value_value": [
          "Office Locations"
        ],
        "category_type": [
          "1"
        ],
        "attribute1_string": [
          "Attribute 1"
        ],
        "category_value": [
          "Demographic Info"
        ],
        "attribute1_type": [
          "1"
        ]
      },
      "start_date": "2024-01-01T00:00:00.000Z"
    },
    "id": "200",
    "system_attributes": {
      "created_date": "1548935657855",
      "created_user": "testusr",
      "last_updated_date": "1548935657855",
      "last_updated_user": "testusr"
    },
    "group_associations": [
      {
        "attributes": {
          "description": "groupassociation",
          "group_association_role": {
            "role_type": [
              "3"
            ],
            "role_value": [
              "QA"
            ],
            "context_entity_name": [
              "PartyGroupingAssociation"
            ],
            "description": [
              "Developer"
            ],
            "category_type": [
              "1"
            ],
            "category_value": [
              "Implementing Frontend"
            ],
            "start_date": [
              "32423424"
            ]
          },
          "group_source_type": "2",
          "group_source_value": "User marked",
          "relationship_id": "1231562",
          "relationship_number": 42234232,
          "relationship_source": "MDM"
        },
        "id": "1231562",
        "system_attributes": {
          "created_date": "1548935657855",
          "created_user": "testusr",
          "last_updated_date": "1548935657855",
          "last_updated_user": "testusr"
        },
        "source": {
          "attributes": {
            "group_number": "200",
            "group_source": "MDM"
          },
          "id": "200",
          "system_attributes": {},
          "group_associations": [],
          "type": "group",
          "type_name": "feature_squad"
        },
        "target": {
          "attributes": {
            "collection_id": "data-create-op",
            "record_id": "fd5baf1c-caef-4300-9cb2-12d2805ec743",
            "record_last_updated": "1741784342749",
            "record_number": 6225011741784343000,
            "record_source": "MDM"
          },
          "id": "6225011741784342832",
          "system_attributes": {
            "created_date": 1741784342749,
            "created_user": "cpadmin",
            "last_updated_date": 1741784342749,
            "last_updated_user": "cpadmin"
          },
          "record_number": 6225011741784343000,
          "type": "record",
          "type_name": "person"
        },
        "type": "relationship",
        "type_name": "feature_squad_association"
      }
    ],
    "type": "group",
    "type_name": "feature_squad"
  },
  "metadata": {
    "href": "https://cpd-mdm.apps.mdm.cp.fyre.ibm.com/17/mdm/v1",
    "id": "200",
    "updated_at": "2019-01-31T11:54:17.855Z"
  }
}

Get all the hierarchy for a given id

This function retrieves all the hierarchies to which the given object is part of.

GET /mdm/v1/hierarchies/by_associated_object/{id}

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    string

    id of respective entity

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • type
    Required*
    string

    type of the given id

  • type_name
    Required*
    string

    type name of the given id

  • offset
    integer

    The number of hierarchies to skip over.

    Default: 0

  • limit
    integer

    The number of hierarchies to be returned. The maximum limit is 200.

    Possible values: value ≤ 200

    Default: 10

  • include_total_count
    boolean

    Flag to include the total hierarchy count.

    Default: false

Response

Response Body

DataHierarchyResponse

Information about a hierarchy.

Status Code

  • 200

    The hierarchy has been retrived successfully.

  • 400

    Problem fetching hierarchies. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem fetching hierarchies. An internal error occurred while attempting to retrieve hierarchies.

Example responses
  • {
  "first": {
    "href": "${host}/mdm/v1/hierarchies/40964176?crn=${crn}"
  },
  "limit": 10,
  "offset": 0,
  "hierarchies": [
    {
      "attributes": {
        "description.value": "ABC generic hierarchy description",
        "hierarchy_name.value": "ABC legal and report hierarchy",
        "hierarchy_type": "generic_hierarchy"
      },
      "id": "169442046788183040",
      "system_attributes": {
        "created_date": 1732746528141,
        "created_user": "admin",
        "hierarchy_id": "7e6f9001-a291-481c-8fcb-c6d7a550501c",
        "hierarchy_number": 169442046788183040,
        "hierarchy_source": "MDM",
        "last_updated_date": 1732746589604,
        "last_updated_user": "admin"
      },
      "type": "hierarchy",
      "type_name": "generic_hierarchy"
    },
    {
      "attributes": {
        "description.value": "ABC generic hierarchy description",
        "hierarchy_name.value": "ABC generic hierarchy",
        "hierarchy_type": "generic_hierarchy"
      },
      "id": "169442294398919680",
      "system_attributes": {
        "created_date": 1732746764281,
        "created_user": "admin",
        "hierarchy_id": "987",
        "hierarchy_number": 169442294398919680,
        "hierarchy_source": "MDM",
        "last_updated_date": 1732746764281,
        "last_updated_user": "admin1"
      },
      "type": "hierarchy",
      "type_name": "generic_hierarchy"
    }
  ]
}

Get hierarchy for a given id

Retrieves the hierarchy, for a given id and typeName

GET /mdm/v1/hierarchies/{id}

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    Id of the hierarchy

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • hierarchy_type
    Required*
    string

    type of the hierarchy

  • from_level
    integer

    Specify the starting level from which you want to retrieve the hierarchy.

    Default: 0

  • to_level
    integer

    Specify the level up to which you want to retrieve the hierarchy.

    Default: 0

  • included_associations
    string

    The associated objects.

  • orphan_nodes_only
    string

    return hierarchy orphan nodes only

    Default: false

  • offset
    integer

    The number of hierarchy nodes to skip over.

    Default: 0

  • limit
    integer

    The number of hierarchy nodes to be returned. The maximum limit is 200.

    Possible values: value ≤ 200

    Default: 10

Response

Response Body

DataHierarchyResponse

Information about a hierarchy.

Status Code

  • 200

    The hierarchy has been retrieved successfully.

  • 400

    Problem fetching hierarchy. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem fetching hierarchy. An internal error occurred while attempting retrieve hierarchy.

Example responses
  • {
  "hierarchy_type": "generic_hierarchy",
  "nodes": [
    {
      "node_type": "hierarchy_node",
      "id": "1000",
      "type": "node",
      "attributes": {
        "node_number": 1000,
        "context_id": 1,
        "node_last_updated": 1555605105822
      },
      "system_attributes": {
        "created_date": "1731525595757",
        "last_updated_date": "1555605105822"
      }
    }
  ],
  "relationships": [
    {
      "sourceNode": {
        "node_type": "generic_hierarchy",
        "id": "168161806391443456",
        "type": "node"
      },
      "targetNode": {
        "node_type": "hierarchy_node",
        "id": "1000",
        "type": "node"
      },
      "relationship_type": "hierarchy_node_relationship",
      "type": "relationship"
    },
    {
      "sourceNode": {
        "node_type": "hierarchy_node",
        "id": "1000",
        "type": "node"
      },
      "targetNode": {
        "record_type": "person",
        "id": "1000",
        "type": "record"
      },
      "relationship_type": "hierarchy_node_association_relationship",
      "type": "relationship"
    }
  ],
  "associated_objects": [
    {
      "record_type": "person",
      "id": "1000",
      "type": "record",
      "attributes": {
        "vertex_id": "MDM-person-5521608536332042",
        "record_number": 1000,
        "record_source": "MDM",
        "record_type": "person"
      },
      "system_attributes": {
        "created_date": "1731525595697",
        "last_updated_date": "1731525595697"
      }
    }
  ],
  "id": "168161806391443456",
  "type": "hierarchy",
  "attributes": {
    "hierarchy_id": "988",
    "hierarchy_last_updated": 1555605105822,
    "hierarchy_name.value": "test hierarchy name",
    "hierarchy_type": "generic_hierarchy",
    "hierarchy_number": 168161806391443460
  },
  "system_attributes": {
    "hierarchy_last_updated_user": "cusadmin",
    "created_date": "1731525595757",
    "hierarchy_created_date": "2023-08-02T00:00:00.000Z",
    "last_updated_date": "1555605105822"
  }
}

Delete a Hierarchy Instance

Deletes the hierarchy anchor node, the hierarchy nodes and all of its relationships for the given hierarchy_type and context_id.The context_id in the hierarchy nodes and the hierarchy_number in the hierarchy anchor node will be the same.

DELETE /mdm/v1/hierarchies/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    int64

    The id for the hierarchy

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • hierarchy_type
    Required*
    string

    The type of the hierarchy

Response

Status Code

  • 204

    The deletes have been successfully processed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Hierarchy instance does not exist.

  • 500

    Problem performing hierarchy delete. An internal error occurred while attempting to update the graph.

No Sample Response

This method does not specify any sample responses.

Replace attributes for a hierarchy

Run an update of hierarchy and relationships in the graph by creating, modifying and deleting data in a single transaction. The operation runs as follows:

  • Performs all node deletions first, then relationship deletions.
  • After the deletions are completed, all hierarchy upserts (i.e. insertions and updates) are performed next.
  • Any element found in both deletions and upserts is treated as a deletion, and removed from the upserts list before processing. Attributes and fields can be removed by setting the attribute or field value to empty string "".
  • A failed update will cause all changes performed by the transaction to be reverted back to the original graph state.
PATCH /mdm/v1/hierarchies/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    int64

    The id for the hierarchy

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • hierarchy_type
    Required*
    string

    The type of the hierarchy

Request Body

Required*
PatchHierarchy

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

Examples: 
{
  "upserts": {
    "type": "hierarchy",
    "type_name": "generic_hierarchy",
    "id": "id",
    "attributes": {
      "hierarchy_name": {
        "value": "ABC legal and report hierarchy"
      },
      "last_updated_date": "last_updated_date"
    },
    "nodes": [
      {
        "type": "node",
        "type_name": "hierarchy_node",
        "reference_id": "11",
        "attributes": {
          "role": {
            "value": "CEO, A Co"
          },
          "designation": {
            "value": "LOCAL PARENT"
          }
        }
      },
      {
        "type": "node",
        "type_name": "hierarchy_node",
        "reference_id": "12",
        "attributes": {
          "role": {
            "value": "CEO, B Co"
          },
          "designation": {
            "value": "LOCAL PARENT"
          }
        }
      },
      {
        "type": "node",
        "type_name": "hierarchy_node",
        "reference_id": "13",
        "attributes": {
          "role": {
            "value": "CEO, C Co"
          },
          "designation": {
            "value": "LOCAL PARENT"
          }
        }
      }
    ],
    "relationships": [
      {
        "type": "relationship",
        "type_name": "hierarchy_node_relationship",
        "source": {
          "id": "node_id2",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "11",
          "type": "node",
          "type_name": "hierarchy_node"
        }
      },
      {
        "type": "relationship",
        "type_name": "hierarchy_node_relationship",
        "source": {
          "id": "node_id3",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "12",
          "type": "node",
          "type_name": "hierarchy_node"
        }
      },
      {
        "type": "relationship",
        "type_name": "hierarchy_node_association_relationship",
        "source": {
          "id": "11",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "person_id1",
          "type": "record",
          "type_name": "person"
        }
      },
      {
        "type": "relationship",
        "type_name": "hierarchy_node_association_relationship",
        "source": {
          "id": "12",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "person_id2",
          "type": "record",
          "type_name": "person"
        }
      },
      {
        "type": "relationship",
        "type_name": "hierarchy_node_association_relationship",
        "source": {
          "id": "13",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "person_id3",
          "type": "record",
          "type_name": "person"
        }
      }
    ]
  },
  "deletions": {
    "relationships": [
      {
        "type": "relationship",
        "type_name": "hierarchy_node_association_relationship",
        "source": {
          "id": "node_id3",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "org_id3",
          "type": "record",
          "type_name": "organization"
        }
      }
    ]
  }
}

Response

Response Body

PatchHierarchyResponse

Information about a patchhierarchy.

Status Code

  • 200

    The hierarchy has been successfully updated.

  • 400

    Problem updating hierarchy. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem updating hierarchy. Hierarchy/Node does not exist.

  • 500

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

Example responses
  • {
  "metadata": {
    "href": "https://data:9443/mdm/v1/hierarchies/177205142370693120?crn=crn&hierarchy_type=generic_hierarchy/177205142370693120",
    "id": "177205142370693120",
    "updated_at": "2025-02-21T14:59:58.264Z"
  },
  "patch_hierarchy": {
    "deletions": {
      "nodes": [],
      "relationships": [
        {
          "source": {
            "id": "177205142370693123",
            "type": "node",
            "type_name": "hierarchy_node"
          },
          "target": {
            "id": "6591521740149764680",
            "is_blocked_for_update": false,
            "is_quarantined": false,
            "record_number": 6591521740149765000,
            "type": "record",
            "type_name": "organization"
          },
          "type": "relationship",
          "type_name": "hierarchy_node_association_relationship"
        }
      ]
    },
    "upserts": {
      "attributes": {
        "hierarchy_name": {
          "value": "ABC legal and report hierarchy"
        }
      },
      "id": "177205142370693120",
      "system_attributes": {
        "hierarchy_number": 177205142370693120,
        "last_updated_date": 1740149993014,
        "last_updated_user": "admin"
      },
      "nodes": [
        {
          "attributes": {
            "designation": {
              "value": "LOCAL PARENT"
            },
            "role": {
              "value": "CEO, A Co"
            }
          },
          "id": "177205147592601600",
          "system_attributes": {
            "context_id": 177205142370693120,
            "created_date": 1740149993014,
            "created_user": "admin",
            "last_updated_date": 1740149998268,
            "last_updated_user": "admin",
            "node_number": 177205147592601600
          },
          "reference_id": "11",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        {
          "attributes": {
            "designation": {
              "value": "LOCAL PARENT"
            },
            "role": {
              "value": "CEO, B Co"
            }
          },
          "id": "177205147592601601",
          "system_attributes": {
            "context_id": 177205142370693120,
            "created_date": 1740149993014,
            "created_user": "admin",
            "last_updated_date": 1740149998270,
            "last_updated_user": "admin",
            "node_number": 177205147592601600
          },
          "reference_id": "12",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        {
          "attributes": {
            "designation": {
              "value": "LOCAL PARENT"
            },
            "role": {
              "value": "CEO, C Co"
            }
          },
          "id": "177205147592601602",
          "system_attributes": {
            "context_id": 177205142370693120,
            "created_date": 1740149993014,
            "created_user": "admin",
            "last_updated_date": 1740149998271,
            "last_updated_user": "admin",
            "node_number": 177205147592601600
          },
          "reference_id": "13",
          "type": "node",
          "type_name": "hierarchy_node"
        }
      ],
      "relationships": [
        {
          "id": "177205147592601603",
          "source": {
            "id": "177205142370693122",
            "type": "node",
            "type_name": "hierarchy_node"
          },
          "target": {
            "id": "177205147592601600",
            "type": "node",
            "type_name": "hierarchy_node"
          },
          "type": "relationship",
          "type_name": "hierarchy_node_relationship"
        },
        {
          "id": "177205147592601604",
          "source": {
            "id": "177205142370693123",
            "type": "node",
            "type_name": "hierarchy_node"
          },
          "target": {
            "id": "177205147592601601",
            "type": "node",
            "type_name": "hierarchy_node"
          },
          "type": "relationship",
          "type_name": "hierarchy_node_relationship"
        },
        {
          "id": "177205147592601605",
          "source": {
            "id": "177205147592601600",
            "type": "node",
            "type_name": "hierarchy_node"
          },
          "target": {
            "id": "3718531740149773251",
            "is_blocked_for_update": false,
            "is_quarantined": false,
            "record_number": 3718531740149773300,
            "type": "record",
            "type_name": "person"
          },
          "type": "relationship",
          "type_name": "hierarchy_node_association_relationship"
        },
        {
          "id": "177205147592601606",
          "source": {
            "id": "177205147592601601",
            "type": "node",
            "type_name": "hierarchy_node"
          },
          "target": {
            "id": "6195501740149775423",
            "is_blocked_for_update": false,
            "is_quarantined": false,
            "record_number": 6195501740149775000,
            "type": "record",
            "type_name": "person"
          },
          "type": "relationship",
          "type_name": "hierarchy_node_association_relationship"
        },
        {
          "id": "177205147592601607",
          "source": {
            "id": "177205147592601602",
            "type": "node",
            "type_name": "hierarchy_node"
          },
          "target": {
            "id": "4498531740149778283",
            "is_blocked_for_update": false,
            "is_quarantined": false,
            "record_number": 4498531740149778400,
            "type": "record",
            "type_name": "person"
          },
          "type": "relationship",
          "type_name": "hierarchy_node_association_relationship"
        }
      ],
      "type": "hierarchy",
      "type_name": "generic_hierarchy"
    }
  }
}

Retrieve the hierarchy configuration for a given id

Retrieve the data in the configuration node associated with the hierarchy instance

GET /mdm/v1/hierarchies/{id}/configuration

Request

Path Parameters

  • id
    Required*
    int64

    The id for the hierarchy

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

DataHierarchyStatistics

Detailed statistics for hierarchies.

Status Code

  • 200

    The hierarchies statistics data is returned successfully.

  • 400

    Problem getting hierarchy statistics. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    No hierarchy configuration was found.

  • 500

    Problem getting statistics. An internal error occurred.

Example responses
  • {
  "cyclic_relationship_validation_enabled": "true",
  "unique_association_validation_enabled": "false",
  "node_existence_validation_enabled": "true",
  "maximum_return_nodes": "50",
  "batch_size": "1000",
  "deletion_batch_size": "2000"
}

Get the broken branches of a hierarchy

This function retrieve the broken branches of a hierarchy

GET /mdm/v1/hierarchies/{id}/broken_branches

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    The id for the hierarchy

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • hierarchy_type
    Required*
    string

    The type of the hierarchy

  • levels
    integer

    The levels of broken branches nodes to be included

    Default: 1

  • included_associations
    string

    The associated objects.

  • offset
    integer

    The number of hierarchy nodes to skip over.

    Default: 0

  • limit
    integer

    The number of hierarchy nodes to be returned. The maximum limit is 200.

    Possible values: value ≤ 200

    Default: 10

Response

Response Body

DataHierarchyResponse

Information about a hierarchy.

Status Code

  • 200

    The broken branches has been retrived successfully.

  • 400

    Problem getting hierarchy broken branches. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting hierarchy broken branches. An internal error occurred while attempting to get hierarchy broken branches.

Example responses
  • {    "branches": [       {        "nodes": [            {                "attributes": {                    "designation": {                        "value": "ULTIMATE PARENT"                    },                    "role": {                        "value": "Global Headquarter"                    }                },                "id": "170049929143693313",                "system_attributes": {                    "context_id": 170049929143693312,                    "created_date": 1733326249931,                    "created_user": "admin",                    "last_updated_date": 1733326249931,                    "last_updated_user": "admin",                    "node_number": 170049929143693313                },                "type": "node",                "type_name": "hierarchy_node"            }        ],        "relationships": [            {                "id": "170049929144741889",                "source": {                    "id": "170049929143693313",                    "type": "node",                    "type_name": "hierarchy_node"                },                "target": {                    "id": "170049929143693314",                    "type": "node",                    "type_name": "hierarchy_node"                },                "type": "relationship",                "type_name": "hierarchy_node_relationship"            }        ],      }        "total_count": "1",        "offset": "0",        "limit": "10"    }

Get the centric view of a given hierarchy node

This function retrieve the centric view of the specific hierarchy node

GET /mdm/v1/hierarchies/{id}/centric_view

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    The id for the hierarchy

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • hierarchy_type
    Required*
    string

    The type of the hierarchy

  • type
    Required*
    string

    type of the given node

  • type_name
    Required*
    string

    type name of the given node

  • centric_id
    Required*
    string

    centric id of the given node

  • parent_levels
    integer

    The parent level of the given node

    Default: 0

  • children_levels
    integer

    The children level of the given node

    Default: 0

  • included_associations
    string

    The associated objects.

  • offset
    integer

    The number of hierarchy nodes to skip over.

    Default: 0

  • limit
    integer

    The number of hierarchy nodes to be returned. The maximum limit is 200.

    Possible values: value ≤ 200

    Default: 10

  • include_total_count
    boolean

    Flag to include the total direct parents/children nodes count.

    Default: false

Response

Response Body

DataHierarchyResponse

Information about a hierarchy.

Status Code

  • 200

    The hierarchy node centric view has been retrived successfully.

  • 400

    Problem getting hierarchy node centric view. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting hierarchy node centric view. An internal error occurred while attempting to get hierarchy node centric view.

Example responses
  • {
  "hierarchy": {
    "id": "170049929143693312",
    "nodes": [
      {
        "attributes": {
          "designation": {
            "value": "ULTIMATE PARENT"
          },
          "role": {
            "value": "Global Headquarter"
          }
        },
        "id": "170049929143693313",
        "system_attributes": {
          "context_id": 170049929143693300,
          "created_date": 1733326249931,
          "created_user": "admin",
          "last_updated_date": 1733326249931,
          "last_updated_user": "admin",
          "node_number": 170049929143693300
        },
        "type": "node",
        "type_name": "hierarchy_node"
      }
    ],
    "relationships": [
      {
        "id": "170049929144741889",
        "source": {
          "id": "170049929143693313",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "170049929143693314",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "type": "relationship",
        "type_name": "hierarchy_node_relationship"
      }
    ],
    "type": "hierarchy",
    "type_name": "generic_hierarchy"
  },
  "metadata": {
    "href": "https://${HOST}/mdm/v1/hierarchies/${hierarchy_type}/instances/11/centric_view",
    "id": "11"
  }
}

Create a new hierarchy

Add a new hierarchy to the graph.

POST /mdm/v1/hierarchies

Authorization

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

  • mdm-oc.data.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataHierarchy

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

Examples: 
{
  "type": "hierarchy",
  "type_name": "generic_hierarchy",
  "id": "",
  "reference_id": "100",
  "attributes": {
    "hierarchy_id": "987",
    "hierarchy_source": "MDM",
    "hierarchy_name": {
      "value": "ABC generic hierarchy"
    },
    "description": {
      "value": "ABC generic hierarchy description"
    }
  },
  "nodes": [
    {
      "type": "node",
      "type_name": "hierarchy_node",
      "id": "",
      "reference_id": "1",
      "attributes": {
        "role": {
          "value": "Global Headquarter"
        },
        "designation": {
          "value": "ULTIMATE PARENT"
        }
      }
    },
    {
      "type": "node",
      "type_name": "hierarchy_node",
      "id": "",
      "reference_id": "2",
      "attributes": {
        "role": {
          "value": "Asia headquarter"
        },
        "designation": {
          "value": "LOCAL PARENT"
        }
      }
    },
    {
      "type": "node",
      "type_name": "hierarchy_node",
      "id": "",
      "reference_id": "3",
      "attributes": {
        "role": {
          "value": "Europe headquarter"
        },
        "designation": {
          "value": "LOCAL PARENT"
        }
      }
    }
  ],
  "relationships": [
    {
      "type": "relationship",
      "type_name": "hierarchy_node_relationship",
      "source": {
        "id": "100",
        "type": "hierarchy",
        "type_name": "generic_hierarchy"
      },
      "target": {
        "id": "1",
        "type": "node",
        "type_name": "hierarchy_node"
      }
    },
    {
      "type": "relationship",
      "type_name": "hierarchy_node_relationship",
      "source": {
        "id": "1",
        "type": "node",
        "type_name": "hierarchy_node"
      },
      "target": {
        "id": "2",
        "type": "node",
        "type_name": "hierarchy_node"
      }
    },
    {
      "type": "relationship",
      "type_name": "hierarchy_node_relationship",
      "source": {
        "id": "1",
        "type": "node",
        "type_name": "hierarchy_node"
      },
      "target": {
        "id": "3",
        "type": "node",
        "type_name": "hierarchy_node"
      }
    },
    {
      "type": "relationship",
      "type_name": "hierarchy_node_association_relationship",
      "source": {
        "id": "1",
        "type": "node",
        "type_name": "hierarchy_node"
      },
      "target": {
        "id": "org_id1",
        "type": "record",
        "type_name": "organization"
      }
    },
    {
      "type": "relationship",
      "type_name": "hierarchy_node_association_relationship",
      "source": {
        "id": "2",
        "type": "node",
        "type_name": "hierarchy_node"
      },
      "target": {
        "id": "org_id2",
        "type": "record",
        "type_name": "organization"
      }
    },
    {
      "type": "relationship",
      "type_name": "hierarchy_node_association_relationship",
      "source": {
        "id": "3",
        "type": "node",
        "type_name": "hierarchy_node"
      },
      "target": {
        "id": "org_id3",
        "type": "record",
        "type_name": "organization"
      }
    }
  ]
}

Response

Response Body

DataHierarchyResponse

Information about a hierarchy.

Status Code

  • 201

    The hierarchy has been successfully created.

  • 400

    Problem creating hierarchy. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

Example responses
  • {
  "enabled": false,
  "hierarchy": {
    "attributes": {
      "description": {
        "value": "ABC generic hierarchy description"
      },
      "hierarchy_name": {
        "value": "ABC generic hierarchy"
      }
    },
    "id": "177205142370693120",
    "system_attributes": {
      "created_date": 1740149993014,
      "created_user": "admin",
      "hierarchy_id": "987",
      "hierarchy_number": 177205142370693120,
      "hierarchy_source": "MDM",
      "last_updated_date": 1740149993014,
      "last_updated_user": "admin"
    },
    "nodes": [
      {
        "attributes": {
          "designation": {
            "value": "ULTIMATE PARENT"
          },
          "role": {
            "value": "Global Headquarter"
          }
        },
        "id": "177205142370693121",
        "system_attributes": {
          "context_id": 177205142370693120,
          "created_date": 1740149993014,
          "created_user": "admin",
          "last_updated_date": 1740149993014,
          "last_updated_user": "admin",
          "node_number": 177205142370693120
        },
        "reference_id": "1",
        "type": "node",
        "type_name": "hierarchy_node"
      },
      {
        "attributes": {
          "designation": {
            "value": "LOCAL PARENT"
          },
          "role": {
            "value": "Asia headquarter"
          }
        },
        "id": "177205142370693122",
        "system_attributes": {
          "context_id": 177205142370693120,
          "created_date": 1740149993014,
          "created_user": "admin",
          "last_updated_date": 1740149993014,
          "last_updated_user": "admin",
          "node_number": 177205142370693120
        },
        "reference_id": "2",
        "type": "node",
        "type_name": "hierarchy_node"
      },
      {
        "attributes": {
          "designation": {
            "value": "LOCAL PARENT"
          },
          "role": {
            "value": "Europe headquarter"
          }
        },
        "id": "177205142370693123",
        "system_attributes": {
          "context_id": 177205142370693120,
          "created_date": 1740149993014,
          "created_user": "admin",
          "last_updated_date": 1740149993014,
          "last_updated_user": "admin",
          "node_number": 177205142370693120
        },
        "reference_id": "3",
        "type": "node",
        "type_name": "hierarchy_node"
      }
    ],
    "reference_id": "100",
    "relationships": [
      {
        "id": "177205142370693124",
        "source": {
          "id": "177205142370693120",
          "type": "hierarchy",
          "type_name": "generic_hierarchy"
        },
        "target": {
          "id": "177205142370693121",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "type": "relationship",
        "type_name": "hierarchy_node_relationship"
      },
      {
        "id": "177205142370693125",
        "source": {
          "id": "177205142370693121",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "177205142370693122",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "type": "relationship",
        "type_name": "hierarchy_node_relationship"
      },
      {
        "id": "177205142370693126",
        "source": {
          "id": "177205142370693121",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "177205142370693123",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "type": "relationship",
        "type_name": "hierarchy_node_relationship"
      },
      {
        "id": "177205142370693127",
        "source": {
          "id": "177205142370693121",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "6607131740149756494",
          "is_blocked_for_update": false,
          "is_quarantined": false,
          "record_number": 6607131740149757000,
          "type": "record",
          "type_name": "organization"
        },
        "type": "relationship",
        "type_name": "hierarchy_node_association_relationship"
      },
      {
        "id": "177205142370693128",
        "source": {
          "id": "177205142370693122",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "4045211740149760671",
          "is_blocked_for_update": false,
          "is_quarantined": false,
          "record_number": 4045211740149760500,
          "type": "record",
          "type_name": "organization"
        },
        "type": "relationship",
        "type_name": "hierarchy_node_association_relationship"
      },
      {
        "id": "177205142371741696",
        "source": {
          "id": "177205142370693123",
          "type": "node",
          "type_name": "hierarchy_node"
        },
        "target": {
          "id": "6591521740149764680",
          "is_blocked_for_update": false,
          "is_quarantined": false,
          "record_number": 6591521740149765000,
          "type": "record",
          "type_name": "organization"
        },
        "type": "relationship",
        "type_name": "hierarchy_node_association_relationship"
      }
    ],
    "type": "hierarchy",
    "type_name": "generic_hierarchy"
  },
  "metadata": {
    "href": "https://data:9443/mdm/v1/hierarchies?crn=crn/177205142370693120",
    "id": "177205142370693120",
    "updated_at": "2025-02-21T14:59:53.014Z"
  }
}

Delete a Hierarchy Branch

Deletes the hierarchy branch within the given hierarchy, including the specified branch node id and all its descendants.

DELETE /mdm/v1/hierarchies/{id}/branches/{branch_node_id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    int64

    The id for the hierarchy

  • branch_node_id
    Required*
    int64

    The branch node id for the hierarchy

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • hierarchy_type
    Required*
    string

    The type of the hierarchy

Response

Status Code

  • 204

    The deletes have been successfully processed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Hierarchy branch does not exist.

  • 500

    Problem performing hierarchy branch delete. An internal error occurred while attempting to update the graph.

No Sample Response

This method does not specify any sample responses.

Get hierarchy statistics

This function returns hierarchies statistics data

GET /mdm/v1/hierarchies/statistics

Authorization

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

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • hierarchy_type
    Required*
    string

    The type name of the hierarchy

  • metrics
    Required*
    string

    Comma-separated metrics of established_hierarchies, instance_member_count,instance_statistics_all.

  • id
    int64

    The instance id of the hierarchy

  • offset
    integer

    The number of hierarchies to skip over.

    Default: 0

  • limit
    integer

    The number of hierarchies to be returned. The maximum limit is 200.

    Possible values: value ≤ 200

    Default: 10

Response

Response Body

DataHierarchyStatistics

Detailed statistics for hierarchies.

Status Code

  • 200

    The hierarchies statistics data is returned successfully.

  • 400

    Problem getting hierarchy statistics. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting statistics. An internal error occurred.

Example responses
  • {
  "hierarchy_statistics": {
    "generic_hierarchy": {
      "established_hierarchies": 2,
      "instance_statistics": [
        {
          "attributes": {
            "hierarchy_name": {
              "value": "ABC generic hierarchy"
            },
            "description": {
              "value": "ABC generic hierarchy description"
            },
            "hierarchy_type": "generic_hierarchy"
          },
          "id": "173417040822907904",
          "member_count": 5,
          "member_relationship_count": 4,
          "orphan_node_count": 0,
          "system_attributes": {
            "hierarchy_id": "987",
            "created_user": "admin",
            "hierarchy_source": "MDM",
            "last_updated_user": "admin",
            "created_date": 1736537377859,
            "last_updated_date": 1736537377859,
            "hierarchy_number": 173417040822907900
          }
        }
      ]
    }
  }
}

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 > User > Access.

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • offset
    integer

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

    Default: 0

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • status
    string

    Filter by job status.

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

  • type
    string

    Filter by job type.

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

Response

Response Body

DataJobs

Paged information about a collection of jobs.

Status Code

  • 200

    The list of jobs was retrieved successfully.

  • 400

    Problem getting list of jobs. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

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

  • mdm-oc.data.read

Request

Path Parameters

  • job_id
    Required*
    string

    The ID of the job.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

DataJob

Information about a job.

Status Code

  • 200

    The job status was retrieved successfully.

  • 400

    Problem getting job information. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting job information. Job not found.

  • 500

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

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

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 > User > Access.

  • mdm-oc.data.write

Request

Path Parameters

  • job_id
    Required*
    string

    The ID of the job.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

DataJob

Information about a job.

Status Code

  • 200

    The job was stopped successfully.

  • 400

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

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

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

  • 405

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

  • 500

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

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

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 > User > Access.

  • mdm-oc.data.write

Request

Path Parameters

  • job_id
    Required*
    string

    The ID of the job.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • 204

    The job clean up was successful.

  • 400

    Problem cleaing up job. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem cleaning up job. Job not found.

  • 405

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

  • 410

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

  • 500

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

  • 503

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

No Sample Response

This method does not specify any sample responses.

Get all data quality issues for a given issue type

This function retrieves all the quality issues that are persisted for the given issue_type in a paginated manner

POST /mdm/v1/quality_issues

Authorization

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

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • issue_type
    Required*
    string

    issue_type to be searched for

  • offset
    integer

    The number of quality issues to skip over.

    Default: 0

  • limit
    integer

    The number of quality issues to be returned. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

  • include_total_count
    boolean

    Flag to include the total issue count on pages other than the first.

    Default: true

Request Body

Required*
QualityIssueSearchRequest

Valid input defining the search criteria

Examples: 
{
  "type": "record",
  "type_name": "person"
}

Response

Response Body

JsonQualityIssueResponse

Paged information about a collection of quality issues.

Status Code

  • 200

    The quality issues have been successfully retrieved.

  • 400

    Problem getting quality issues. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting quality issues: issue type does not exist.

  • 500

    Problem getting quality issues. An internal error occurred while attempting to retrieve the quality issues.

Example responses
  • {
  "first": {
    "href": "https://matching:9443/mdm/v1/data_quality/issues?crn=:::::::msk::&offset=0&limit=1"
  },
  "last": {
    "href": "https://matching:9443/mdm/v1/data_quality/issues?crn=:::::::msk::&offset=4&limit=1"
  },
  "next": {
    "href": "https://matching:9443/mdm/v1/data_quality/issues?crn=:::::::msk::&offset=1&limit=1"
  },
  "quality_issues": [
    {
      "issue_type": "potential_overlay",
      "type": "record",
      "type_name": "person",
      "id": "123",
      "number": "123",
      "created_at": "Jan15, 2023"
    }
  ],
  "total_count": 25,
  "offset": 0,
  "limit": 8
}

List the related records for a record

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 > User > Access.

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    The ID of the record.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    string

    The type of record to filter in results

    Example: person

  • relationship_type
    string

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

    Example: process_purpose

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • offset
    integer

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

    Default: 0

  • include_total_count
    boolean

    Flag to include the total record count on pages other than the first.

    Default: true

Response

Response Body

RelatedRecords

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

Status Code

  • 200

    The related records for the record have been successfully retrieved.

  • 400

    Problem getting related records. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem retrieving neighbors. Record does not exist.

  • 500

    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"
        }
      },
      "system_attributes": {
        "created_date": "1547836463189",
        "last_updated_user": "user",
        "created_user": "user",
        "last_updated_date": "1548936493189"
      },
      "id": "151592",
      "type": "record",
      "record_number": 151592,
      "type_name": "process_purpose"
    }
  ]
}

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 > User > Access.

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    The id of the record.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • offset
    integer

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

    Default: 0

  • include
    string[]

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

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]
  • exclude
    string[]

    Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]

Response

Response Body

DataEntitiesResponse

Paged information about a collection of entities.

Status Code

  • 200

    The list of entities have been successfully retrieved.

  • 400

    Problem getting entities for record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

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

  • 500

    Problem getting entities for record. 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"
      },
      "system_attributes": {
        "created_date": "1547836463189",
        "last_updated_user": "user",
        "created_user": "user",
        "last_updated_date": "1548936493189"
      },
      "id": "person_entity-53496",
      "type": "entity",
      "record_count": 1,
      "type_name": "person_entity"
    }
  ]
}

List the Potenital Overlay records for a record

Retrieve a set of potental overlay records which are accumulated to the specified record.

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

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    The ID of the record.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • offset
    integer

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

    Default: 0

  • sort_descend
    boolean

    Odrder of sorting of result.

    Default: true

Response

Response Body

PotentialOverlayRecords

Paged information about a set of acculumulated record updates on a record.

Status Code

  • 200

    The potential overlay records for the record have been successfully retrieved.

  • 400

    Problem getting PO overlay records. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem retrieving PO records. Record does not exist.

  • 500

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

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

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 > User > Access.

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    The ID of the record.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • relationship_types
    string[]

    The relationship types to return.

    Examples: 
    [
  "preference_association"
]
  • offset
    integer

    The number of relationships to skip over.

    Default: 0

  • limit
    integer

    The number of relationships to be returned. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

  • source_include
    string[]

    Attributes from the data model to include in the results for the source vertex.

    Possible values: contains only unique items

    Examples: 
    [
  "all"
]
  • target_include
    string[]

    Attributes from the data model to include in the results for the target vertex.

    Possible values: contains only unique items

    Examples: 
    [
  "all"
]

Response

Response Body

DataRelationshipsResponse

Paged information about a collection of relationships.

Status Code

  • 200

    The relationships have been successfully retrieved.

  • 400

    Problem retrieving relationships for record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem retrieving relationships for record. Record not found.

  • 500

    Problem retrieving relationships for record. An internal error occurred.

Example responses
  • {
  "first": {
    "href": "${host}/mdm/v1/records/123/relationships?crn=${crn}&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/records/123/relationships?crn=${crn}&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "relationships": [
    {
      "attributes": {
        "relationship_id": "997554896611881692",
        "relationship_last_updated": "1548937318815",
        "relationship_source": "MDM",
        "from_record_id": "358354896586841797",
        "from_record_source": "MDM",
        "from_record_type": "preference",
        "to_record_id": "998254896587316451",
        "to_record_source": "MDM",
        "to_record_type": "organization"
      },
      "system_attributes": {
        "created_date": "1547836463189",
        "last_updated_user": "user",
        "created_user": "user",
        "last_updated_date": "1548936493189"
      },
      "id": "215tzl-5cw8-q7f9-oi7u8",
      "source": {
        "id": "123",
        "type": "record",
        "type_name": "person"
      },
      "target": {
        "id": "40964344",
        "type": "record",
        "type_name": "person"
      },
      "type": "relationship",
      "type_name": "preference_association"
    }
  ]
}

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 > User > Access.

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    The ID of the record.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • include
    string[]

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

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]
  • exclude
    string[]

    Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]

Response

Response Body

DataRecordResponse

Information about a record.

Status Code

  • 200

    The record has been successfully retrieved.

  • 400

    Problem getting record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting record: Record does not exist.

  • 500

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

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

Replace 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 > User > Access.

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    int64

    The ID of the record.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataRecord

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

Examples: 
{
  "attributes": {
    "legal_name": {
      "last_name": "Smith",
      "given_name": "Jane"
    },
    "mailing_address": {
      "province_state": "CA",
      "city": "COLOMA",
      "zip_postal_code": "95613",
      "address_line1": "5955 EAST ST ANNE STREET",
      "address_line2": "Unit-89"
    },
    "record_id": "12345",
    "record_source": "MDM"
  },
  "type": "record",
  "type_name": "person"
}

Response

Response Body

DataRecordResponse

Information about a record.

Status Code

  • 200

    The record has been successfully updated.

  • 202

    Update request accepted but not processed. Quarantined record.

  • 400

    Problem updating record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem updating record. The record could not be found.

  • 409

    Update request rejected for quarantined record due to max allowed limit.

  • 500

    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"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "40964176",
    "type": "record",
    "record_number": 40964176,
    "type_name": "person"
  }
}

Delete 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 > User > Access.

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    int64

    The ID of the record.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • 204

    The record was successfully deleted.

  • 400

    Problem deleting record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem deleting record. Record does not exist.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Patches attributes for a record

Patches the existing record with the new set of attributes. Any existing editable record attributes not specified in the request will be retained in the record. Any attributes that are explicitly set as null will be removed.

PATCH /mdm/v1/records/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    int64

    The ID of the record.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataRecord

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

Examples: 
{
  "attributes": {
    "legal_name": {
      "given_name": "Jane"
    },
    "mailing_address": {
      "province_state": "CA",
      "city": "COLOMA",
      "zip_postal_code": "95613",
      "address_line1": "5955 EAST ST ANNE STREET",
      "address_line2": "Unit-89"
    },
    "birth_date": {
      "value": null,
    },
    "record_id": "12345",
    "record_source": "MDM"
  },
  "type": "record",
  "type_name": "person"
}

Response

Response Body

DataRecordResponse

Information about a record.

Status Code

  • 200

    The record has been successfully patched.

  • 202

    Update request accepted but not processed. Quarantined record.

  • 400

    Problem patching record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem patching record. The record could not be found.

  • 409

    Update request rejected for quarantined record due to max allowed limit.

  • 500

    Problem patching record. An internal error occurred while attempting to patch 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"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "40964176",
    "type": "record",
    "record_number": 40964176,
    "type_name": "person"
  }
}

List the records

View a list of records that have been added to the graph for given record type. If record type is not provided, then list all records

GET /mdm/v1/records

Authorization

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

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • offset
    integer

    The number of records to skip over.

    Default: 0

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • recordtype
    string

    Record type

    Default:

Response

Response Body

DataRecordsResponse

Paged information about a collection of records.

Status Code

  • 200

    The records have been successfully retrieved.

  • 400

    Problem getting records. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

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

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 > User > Access.

  • mdm-oc.data.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataRecord

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

Examples: 
{
  "attributes": {
    "legal_name": {
      "last_name": "Smith",
      "given_name": "Jane"
    },
    "record_id": "12345",
    "record_source": "MDM"
  },
  "id": "40964176",
  "type": "record",
  "record_number": 40964176,
  "type_name": "person"
}

Response

Response Body

DataRecordResponse

Information about a record.

Status Code

  • 201

    The record has been successfully created.

  • 400

    Problem creating record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    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"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "40964176",
    "type": "record",
    "record_number": 40964176,
    "type_name": "person"
  }
}

Get a record given record_type, record_source and record_id

View information about the specified record on the graph.

GET /mdm/v1/records/bysourceid

Authorization

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

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    The type of the record.

  • record_source
    Required*
    string

    source of record

    Example: MDM

  • record_id
    Required*
    string

    Id of record

    Example: 15687873482748

  • collection_id
    string

    Collection Id of record

    Default:

Response

Response Body

DataRecordResponse

Information about a record.

Status Code

  • 200

    The record has been successfully retrieved.

  • 400

    Problem getting record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting record: Record does not exist.

  • 500

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

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

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 > User > Access.

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    int64

    The ID of the record.

  • relationship_id
    Required*
    string

    The ID of the linked relationship to return.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • source_include
    string[]

    Attributes from the data model to include in the results for the source vertex.

    Possible values: contains only unique items

    Examples: 
    [
  "all"
]
  • target_include
    string[]

    Attributes from the data model to include in the results for the target vertex.

    Possible values: contains only unique items

    Examples: 
    [
  "all"
]

Response

Response Body

DataRelationshipResponse

Information about a relationship.

Status Code

  • 200

    The relationship has been successfully retrieved.

  • 400

    Problem getting relationship for record. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting relationship for record. Relationship does not exist.

  • 500

    Problem getting relationship for record. 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"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "215tzl-5cw8-q7f9-oi7u8",
    "type": "relationship",
    "type_name": "preference_association"
  }
}

Create a new relationship

Add a new relationship to the graph.

POST /mdm/v1/relationships

Authorization

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

  • mdm-oc.data.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataRelationship

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

Examples: 
{
  "relationship": {
    "attributes": {
      "relationship_id": "123",
      "relationship_source": "MDM"
    },
    "id": "7x80m4-oe09s-i711-2u49q8",
    "source": {
      "id": "40964320",
      "type": "record",
      "type_name": "person"
    },
    "target": {
      "id": "171520064",
      "type": "record",
      "type_name": "person"
    },
    "type": "relationship",
    "type_name": "party_relationship"
  }
}

Response

Response Body

DataRelationshipResponse

Information about a relationship.

Status Code

  • 201

    The relationship has been successfully created.

  • 400

    Problem creating relationship. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

Example responses
  • {
  "metadata": {
    "href": "${host}/mdm/v1/relationships/7x80m4-oe09s-i711-2u49q8?crn=${crn}",
    "id": "7x80m4-oe09s-i711-2u49q8",
    "updated_at": "2021-08-19T18:33:55.679Z"
  },
  "relationship": {
    "attributes": {
      "relationship_id": "123",
      "relationship_last_updated": "1629398035679",
      "relationship_source": "MDM"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "7x80m4-oe09s-i711-2u49q8",
    "source": {
      "id": "40964320",
      "type": "record",
      "type_name": "person"
    },
    "target": {
      "id": "171520064",
      "type": "record",
      "type_name": "person"
    },
    "type": "relationship",
    "type_name": "party_relationship"
  }
}

Get a relationship

View information about the specified relationship on the graph.

GET /mdm/v1/relationships/{id}

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • id
    Required*
    string

    The ID of the relationship.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • source_include
    string[]

    Attributes from the data model to include in the results for the source vertex.

    Possible values: contains only unique items

    Examples: 
    [
  "all"
]
  • target_include
    string[]

    Attributes from the data model to include in the results for the target vertex.

    Possible values: contains only unique items

    Examples: 
    [
  "all"
]
  • relationship_type
    string

    Relationship type from the data model to include in the results

    Examples: 
    [
  "all"
]

Response

Response Body

DataRelationshipResponse

Information about a relationship.

Status Code

  • 200

    The relationship has been successfully retrieved.

  • 400

    Problem getting relationship. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem getting relationship. The relationship could not be found.

  • 500

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

Example responses
  • {
  "metadata": {
    "href": "${host}/mdm/v1/relationships/7x80m4-oe09s-i711-2u49q8?crn=${crn}",
    "id": "7x80m4-oe09s-i711-2u49q8",
    "updated_at": "2021-08-19T18:33:55.679Z"
  },
  "relationship": {
    "attributes": {
      "relationship_id": "123",
      "relationship_last_updated": "1629398035679",
      "relationship_source": "MDM"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "7x80m4-oe09s-i711-2u49q8",
    "source": {
      "id": "40964320",
      "type": "record",
      "type_name": "person"
    },
    "target": {
      "id": "171520064",
      "type": "record",
      "type_name": "person"
    },
    "type": "relationship",
    "type_name": "party_relationship"
  }
}

Replace attributes for a relationship

Replace the existing relationship attributes on the graph with the new set of attributes.

PUT /mdm/v1/relationships/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the relationship.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataRelationship

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

Examples: 
{
  "relationship": {
    "attributes": {
      "relationship_id": "123",
      "relationship_source": "MDM"
    },
    "id": "7x80m4-oe09s-i711-2u49q8",
    "source": {
      "id": "40964320",
      "type": "record",
      "type_name": "person"
    },
    "target": {
      "id": "171520064",
      "type": "record",
      "type_name": "person"
    },
    "type": "relationship",
    "type_name": "party_relationship"
  }
}

Response

Response Body

DataRelationshipResponse

Information about a relationship.

Status Code

  • 200

    The relationship has been successfully updated.

  • 400

    Problem updating relationship. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem updating relationship. The relationship could not be found.

  • 409

    Problem updating relationship. The resulting composite key conflicts with an existing relationship.

  • 500

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

Example responses
  • {
  "metadata": {
    "href": "${host}/mdm/v1/relationships/7x80m4-oe09s-i711-2u49q8?crn=${crn}",
    "id": "7x80m4-oe09s-i711-2u49q8",
    "updated_at": "2021-08-19T18:33:55.679Z"
  },
  "relationship": {
    "attributes": {
      "relationship_id": "123",
      "relationship_last_updated": "1629398035679",
      "relationship_source": "MDM"
    },
    "system_attributes": {
      "created_date": "1547836463189",
      "last_updated_user": "user",
      "created_user": "user",
      "last_updated_date": "1548936493189"
    },
    "id": "7x80m4-oe09s-i711-2u49q8",
    "source": {
      "id": "40964320",
      "type": "record",
      "type_name": "person"
    },
    "target": {
      "id": "171520064",
      "type": "record",
      "type_name": "person"
    },
    "type": "relationship",
    "type_name": "party_relationship"
  }
}

Delete a relationship

Delete an existing relationship from the graph.

DELETE /mdm/v1/relationships/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the relationship.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • 204

    The relationship was successfully deleted.

  • 400

    Problem deleting relationship. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem deleting relationship. Relationship does not exist.

  • 500

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

No Sample Response

This method does not specify any sample responses.

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 > User > Access.

  • mdm-oc.data.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • 204

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

  • 400

    Problem updating schema. Input validation failed.

  • 401

    Problem updating schema. The user is not authenticated.

  • 403

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

  • 409

    Problem updating schema.

  • 500

    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 > User > Access.

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • return_type
    string

    The type of results to return from the search.

    Allowable values: [results,results_as_entities,results_as_hierarchy_nodes]

    Default: results

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • offset
    integer

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

    Default: 0

  • include
    string[]

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

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]
  • exclude
    string[]

    Record attributes from the data model to exclude from the results.

    Possible values: contains only unique items

    Examples: 
    [
  "legal_name.given_name"
]

Request Body

Required*
DataSearchCriteria

Valid input defining the search criteria.

Examples: 
{
  "search_type": "record",
  "query": {
    "expressions": [
      {
        "property": "legal_name.last_name",
        "condition": "equal",
        "value": "smith"
      }
    ]
  }
}

Response

Response Body

DataSearchResults

Results of a search operation.

Status Code

  • 200

    The search was performed successfully.

  • 400

    Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 408

    Request timed out.

  • 500

    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 global/user settings

Get global/user settings from EM-UI

GET /mdm/v1/ui_settings/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the settings doc.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

JsonUISettingsResponse

Information about a Json UI Settings Response.

Status Code

  • 200

    The global/user setings has been successfully retrieved.

  • 400

    Problem getting settings. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting settings. An internal error occurred while attempting to get the settings.

Example responses
  • {
  "entity_types": {
    "person_entity": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "entity type",
          "show": true,
          "type": "key_relationship ",
          "record_type": "person ",
          "result_type": "results_as_entities ",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          " table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        },
        {
          "label": "entity type 2",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results_as_entities",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        }
      ]
    }
  },
  "record_types": {
    "person": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "one",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "record_id",
            "record_source",
            "record_display_label"
          ]
        }
      ]
    }
  }
}

Update global/user settings

Update global/user settings from EM-UI

PUT /mdm/v1/ui_settings/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the settings doc.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
UISettings

Valid object defining the updated settings to be added.

Examples: 
{
  "entity_types": {
    "person_entity": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "entity type",
          "show": true,
          "type": "key_relationship ",
          "record_type": "person ",
          "result_type": "results_as_entities ",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          " table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        },
        {
          "label": "entity type 2",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results_as_entities",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        }
      ]
    }
  },
  "record_types": {
    "person": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "one",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "record_id",
            "record_source",
            "record_display_label"
          ]
        }
      ]
    }
  }
}

Response

Response Body

JsonUISettingsResponse

Information about a Json UI Settings Response.

Status Code

  • 200

    The global/user setings has been successfully updated.

  • 400

    Problem updating settings. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

Example responses
  • {
  "entity_types": {
    "person_entity": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "entity type",
          "show": true,
          "type": "key_relationship ",
          "record_type": "person ",
          "result_type": "results_as_entities ",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          " table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        },
        {
          "label": "entity type 2",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results_as_entities",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        }
      ]
    }
  },
  "record_types": {
    "person": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "one",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "record_id",
            "record_source",
            "record_display_label"
          ]
        }
      ]
    }
  }
}

Reset global/user settings

Reset global/user settings from EM-UI

DELETE /mdm/v1/ui_settings/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the settings doc.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

JsonUISettingsResponse

Information about a Json UI Settings Response.

Status Code

  • 200

    The global/user setings has been successfully reset.

  • 400

    Problem resetting settings. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem resetting settings. An internal error occurred while attempting to reset the settings.

Example responses
  • {
  "entity_types": {
    "person_entity": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "entity type",
          "show": true,
          "type": "key_relationship ",
          "record_type": "person ",
          "result_type": "results_as_entities ",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          " table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        },
        {
          "label": "entity type 2",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results_as_entities",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        }
      ]
    }
  },
  "record_types": {
    "person": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "one",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "record_id",
            "record_source",
            "record_display_label"
          ]
        }
      ]
    }
  }
}

Update global/user settings

Update global/user settings from EM-UI

PATCH /mdm/v1/ui_settings/{id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • id
    Required*
    string

    The ID of the settings doc.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
UISettings

Valid object defining the updated settings to be added.

Examples: 
{
  "entity_types": {
    "person_entity": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "entity type",
          "show": true,
          "type": "key_relationship ",
          "record_type": "person ",
          "result_type": "results_as_entities ",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          " table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        },
        {
          "label": "entity type 2",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results_as_entities",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        }
      ]
    }
  },
  "record_types": {
    "person": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "one",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "record_id",
            "record_source",
            "record_display_label"
          ]
        }
      ]
    }
  }
}

Response

Response Body

JsonUISettingsResponse

Information about a Json UI Settings Response.

Status Code

  • 200

    The global/user setings has been successfully updated.

  • 400

    Problem updating settings. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

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

Example responses
  • {
  "entity_types": {
    "person_entity": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "entity type",
          "show": true,
          "type": "key_relationship ",
          "record_type": "person ",
          "result_type": "results_as_entities ",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          " table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        },
        {
          "label": "entity type 2",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results_as_entities",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "entity_id",
            "entity_display_label"
          ],
          "entity_type": "person_entity"
        }
      ]
    }
  },
  "record_types": {
    "person": {
      "label": [],
      "search_result_attributes": [],
      "summary": {
        "label": "Summary",
        "attributes": [
          [],
          []
        ]
      },
      "attribute_groups": [],
      "cards": [
        {
          "label": "one",
          "show": true,
          "type": "key_relationship",
          "record_type": "person",
          "result_type": "results",
          "key_mappings": [
            {
              "condition": "equal"
            }
          ],
          "table_attributes": [
            "record_id",
            "record_source",
            "record_display_label"
          ]
        }
      ]
    }
  }
}

Get global and user settings for all users

Get global and user settings of all users from EM-UI

GET /mdm/v1/ui_settings

Authorization

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

  • mdm-oc.data.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • offset
    integer

    The number of records to skip over.

    Default: 0

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

Response

Response Body

JsonUIAllSettingsResponse

Information about a Json UI Settings Response for all users.

Status Code

  • 200

    The global and user setings for all users has been successfully retrieved.

  • 400

    Problem getting settings. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting settings. An internal error occurred while attempting to get the settings.

Example responses
  • [
  {
    "entity_types": {
      "person_entity": {
        "label": [],
        "search_result_attributes": [],
        "summary": {
          "label": "Summary",
          "attributes": [
            [],
            []
          ]
        },
        "attribute_groups": [],
        "cards": [
          {
            "label": "entity type",
            "show": true,
            "type": "key_relationship ",
            "record_type": "person ",
            "result_type": "results_as_entities ",
            "key_mappings": [
              {
                "condition": "equal"
              }
            ],
            " table_attributes": [
              "entity_id",
              "entity_display_label"
            ],
            "entity_type": "person_entity"
          },
          {
            "label": "entity type 2",
            "show": true,
            "type": "key_relationship",
            "record_type": "person",
            "result_type": "results_as_entities",
            "key_mappings": [
              {
                "condition": "equal"
              }
            ],
            "table_attributes": [
              "entity_id",
              "entity_display_label"
            ],
            "entity_type": "person_entity"
          }
        ]
      }
    },
    "record_types": {
      "person": {
        "label": [],
        "search_result_attributes": [],
        "summary": {
          "label": "Summary",
          "attributes": [
            [],
            []
          ]
        },
        "attribute_groups": [],
        "cards": [
          {
            "label": "one",
            "show": true,
            "type": "key_relationship",
            "record_type": "person",
            "result_type": "results",
            "key_mappings": [
              {
                "condition": "equal"
              }
            ],
            "table_attributes": [
              "record_id",
              "record_source",
              "record_display_label"
            ]
          }
        ]
      }
    }
  }
]

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 > User > Access.

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • include_source_statistics
    string

    Include source statistics

    Default: true

  • approximate_statistics
    string

    Show approximate entity statistics

    Default: false

Response

Response Body

DataStatistics

A collection of statistics for the graph.

Status Code

  • 200

    The graph statistics have been successfully retrieved.

  • 400

    Problem getting graph statistics. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem getting 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 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 > User > Access.

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
SubgraphParameters

Valid object defining scope parameters for the subgraph.

Response

Response Body

Subgraph

A graph view representing a scoped subset of the graph.

Status Code

  • 200

    The subgraph has been successfully retrieved.

  • 400

    Problem retrieving subgraph. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem 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"
    }
  ]
}

List the workflows

View a list of workflow nodes that have been added to the graph for given workflow type.

GET /mdm/v1/workflows

Authorization

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

  • mdm-oc.data.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • workflow_type
    Required*
    string

    The workflow type to return.

    Example: potential_overlay

  • record_number
    string

    Return workflow node associated with record number.

  • offset
    integer

    The number of workflows to skip over.

    Default: 0

  • limit
    integer

    The number of workflow nodes to be returned. The maximum limit is 50.

    Possible values: value ≤ 50

    Default: 10

Response

Response Body

DataRecordsResponse

Paged information about a collection of records.

Status Code

  • 200

    The workflow nodes have been successfully retrieved.

  • 400

    Problem retrieving workflow nodes. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem retrieving workflow nodes for workflow type. workflow node not found.

  • 500

    Problem retrieving workflow node. An internal error occurred.

Example responses
  • {  "first": {    "href": "${host}/mdm/v1/workflow?crn=${crn}&offset=0&limit=10"  },  "last": {    "href": "${host}/mdm/v1/workflow?crn=${crn}&offset=0&limit=10"  },  "next": {    "href": "${host}/mdm/v1/workflow?crn=${crn}&offset=0&limit=10"  },  "previous": {    "href": "${host}/mdm/v1/workflow?crn=${crn}&offset=0&limit=10"  },  "limit": 10,  "offset": 2,  "total_count": 240,  "workflows": [     {         "id": "123441",         "type": "potential_overlay",         "last_updated_date": ",         "last_updated_user": ",         "entities": [{             "type": "record",             "type_name": "person",             "id": "2413sd53",             "number": "122441"        }]      }  ]}

Get a workflow

View information about a specific workflow node on the graph.

GET /mdm/v1/workflows/{workflow_id}

Authorization

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

  • mdm-oc.data.read

Request

Path Parameters

  • workflow_id
    Required*
    string

    The ID of the workflow.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • workflow_type
    Required*
    string

    The workflow type to return.

Response

Response Body

DataWorkflowResponse

Information about a workflow.

Status Code

  • 200

    The workflow node has been successfully retrieved.

  • 400

    Problem retrieving workflow node. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem retrieving workflow node for record. workflow node not found.

  • 500

    Problem retrieving workflow node. An internal error occurred.

Example responses
  • {         "id": "123441",         "type": "potential_overlay",         "last_updated_date": ",         "last_updated_user": ",         "entities": [{             "type": "record",             "type_name": "person",             "id": "2413sd53",             "number": "122441"        }]}

Delete a workflow

Delete an existing workflow

DELETE /mdm/v1/workflows/{workflow_id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • workflow_id
    Required*
    string

    The ID of the workflow.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • workflow_type
    Required*
    string

    The type of the workflow.

Response

Status Code

  • 204

    The workflow was successfully deleted.

  • 400

    Problem deleting workflow. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 404

    Problem deleting workflow. Record does not exist.

  • 500

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

No Sample Response

This method does not specify any sample responses.

patch a workflow

Patch the workflow associated to the given id and worklfow_type.

PATCH /mdm/v1/workflows/{workflow_id}

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • workflow_id
    Required*
    string

    The ID of the workflow.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • workflow_type
    Required*
    string

    The type of the workflow.

Request Body

Required*
PatchWorkflowRequest

Valid object defining the information to patch a workflow of the given type.

Examples: 
{
  "actions": [
    {
      "action_type": "update",
      "action_values": {
        "update_seq": [
          1,
          4,
          6
        ]
      }
    }
  ]
}

Response

Status Code

  • 200

    The workflow has been successfully patched.

  • 400

    Problem patching workflow. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem patching workflow. An internal error occurred while attempting to patch the workflow.

No Sample Response

This method does not specify any sample responses.

Resolve a workflow

Resolve the workflow associated to the given id and worklfow_type.

POST /mdm/v1/workflows/{workflow_id}/resolve

Authorization

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

  • mdm-oc.data.write

Request

Path Parameters

  • workflow_id
    Required*
    string

    The ID of the workflow.

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • workflow_type
    Required*
    string

    The type of the workflow.

  • preview_only
    boolean

    Flag to preview the resolved workflow changes or to apply them. Defualt is false

    Default: false

Request Body

Required*
ResolveWorkflowRequest

Valid object defining the information to resolve a workflow of the given type.

Examples: 
{
  "actions": [
    {
      "action_type": "update",
      "entities": [
        {
          "type": "record",
          "type_name": "person",
          "number": "124451"
        }
      ],
      "action_values": {
        "update_seq": [
          1,
          4,
          6
        ]
      }
    }
  ],
  "comments": ""
}

Response

Status Code

  • 200

    The workflow has been successfully resolved.

  • 400

    Problem resolving workflow. Input validation failed.

  • 401

    Problem processing request. The user is not authenticated.

  • 403

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

  • 500

    Problem resolving workflow. An internal error occurred while attempting to resolve the workflow.

No Sample Response

This method does not specify any sample responses.

Initiate export manual rules job

  • This service initiates asynchronous processing of the export rules job.
POST /mdm/v1/bulk_export_linkage_rules

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

Request Body

Required*
PostExportRulesRequest

The wrapper object for export manual rules request body

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}

Initiate score entities job

  • This service initiates asynchronous processing of the score entities job.
POST /mdm/v1/bulk_score_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 > User > Access.

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • output_path
    Required*
    string

    Output directory

    Example: /entities

  • record_type
    Required*
    string

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

    Example: person

  • entity_type
    Required*
    string

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

    Example: person_entity

  • cos_endpoint
    Required*
    string

    IBM COS end point

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

  • cos_bucket
    Required*
    string

    IBM COS bucket

    Example: mdmexport

  • cos_access_key
    Required*
    string

    IBM COS access key

    Example: b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret

  • cos_secret_key
    Required*
    string

    IBM COS secret key

    Example: <hex string>

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

Request Body

Required*
PairComparatorEntityRequest

The wrapper object for List of entity ids

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "61687493865291776",
  "arguments": "runEntityPairCompare.sh -d person -m person_entity -o /entities -a",
  "start_time": "",
  "process_id": 151,
  "end_time": "",
  "exit_code": 0,
  "metrics": {
    "entity_pair_matched_count": {}
  }
}

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 > User > Access.

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • entity_type
    string

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

    Example: person_entity

  • do_force
    boolean

    Force to re-match all records, default is false

    Default: false

  • do_deduplicate
    boolean

    Deduplicate pairs, default is false

    Default: false

  • do_analytics
    boolean

    collect analysis report, default is false

    Default: false

  • do_replicate
    boolean

    Replicate entity id, default is true

    Default: true

  • do_checkpoint
    boolean

    Do checkpoint

    Default: false

  • resume_from_driver
    boolean

    Resume from step copying entity id, default is false

    Default: false

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

  • log_cos_endpoint
    string

    IBM COS end point for job log storage.

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

  • log_cos_bucket
    string

    IBM COS bucket for job log storage.

    Example: mdmdata

  • log_cos_access_key
    string

    IBM COS access key for spark log storage

    Example: b33037e4e8954207a434cc032c1139d1

  • log_cos_secret_key
    string

    IBM COS secret key for spark log storage

    Example: <hex string>

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 202

    The request has been successfully created.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

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

Initiate import manual rules job

  • This service initiates asynchronous processing of the import rules job.
POST /mdm/v1/bulk_import_linkage_rules

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

Request Body

Required*
PostImportRulesRequest

The wrapper object for import manual rules request body

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "",
  "exit_code": 0,
  "arguments": "runImportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}

Initiate matching export job

  • This service initiates asynchronous processing of a matching export job.
  • Match export job exports the existing matching data, pairs data, data quality data and workflow data to a given path under /service-exports.
POST /mdm/v1/bulk_matching_export

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

  • output_path
    string

    The output path under /service-exports for the exported data

    Default: /service-exports/matching

    Example: /service-exports/customFolder

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 202

    The request has been successfully created.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

  • 501

    The request cannot be processed due to the server not supporting the required functionality

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

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 > User > Access.

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • do_force
    boolean

    Force to re-derive all records, default is false

    Default: false

  • csv_file
    string

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

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

  • csv_column
    string

    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

  • cos_endpoint
    string

    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

  • cos_bucket
    string

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

    Example: mdmdata

  • cos_access_key
    string

    IBM COS access key (i.e. cf4965cebe074720a4929759f57e1214)

    Example: b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret

  • cos_secret_key
    string

    The unique secret code to access IBM COS

    Example: <hex string>

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

  • log_cos_endpoint
    string

    IBM COS end point for job log storage.

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

  • log_cos_bucket
    string

    IBM COS bucket for job log storage.

    Example: mdmdata

  • log_cos_access_key
    string

    IBM COS access key for spark log storage

    Example: b33037e4e8954207a434cc032c1139d1

  • log_cos_secret_key
    string

    IBM COS secret key for spark log storage

    Example: <hex string>

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 202

    The request has been successfully created.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "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, etc..
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 > User > Access.

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • entity_type
    string

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

    Example: person_entity

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

  • job_list
    string

    Comma separated analytics report identifier to be collected, ie. entity_summary, bucket_summary

    Default: entity_summary,bucket_summary

    Example: entity_summary,bucket_summary

  • do_analytics
    boolean

    collect analysis report, default is false

    Default: false

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 202

    The request has been successfully created.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "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 generate pairs job

  • This service initiates asynchronous processing of the generate pairs job.
POST /mdm/v1/bulk_generate_pairs

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    Required*
    string

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

    Example: person_entity

  • record_type
    Required*
    string

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

    Example: person

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • max_pairs
    string

    The maximum number of pairs to return

    Default: 500

    Example: 500

  • executor_count
    integer

    The number of spark executors

    Example: 1

  • executor_memory
    string

    Amount of memory to use per executor process

    Example: 8g

  • executor_core_count
    integer

    The number of cores to use on each executor

    Example: 1

  • spark_parallelism
    integer

    The number of partitions to be used by spark

    Example: 2

  • exclude_reviewed_pairs
    boolean

    Exclude reviewd pairs. Default is false

    Default: false

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "44465189566855168",
  "arguments": "runPairScore.sh -d person -m person_entity",
  "start_time": "2021-02-17T10:55:09.264Z",
  "process_id": 1550,
  "end_time": "2021-02-17T10:55:22.487Z",
  "exit_code": 0,
  "metrics": {
    "total_pairs": 118,
    "bucket_count_compared": 1125,
    "bucket_count_large": 0,
    "bucket_count_singleton": 1776,
    "record_count_updated": 0,
    "record_count_deleted": 0,
    "record_count_no_buckets": 0,
    "record_count_low_score": 0,
    "record_count_candidate": 100,
    "pair_comparison_count": 5614,
    "pair_matched_count": 5101
  }
}

resolve matching remediation workflows

  • This service resolves the matching workflow with given workflow id.
POST /mdm/v1/data_quality/remediation_workflows/{workflow_id}/resolve

Authorization

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

  • mdm-oc.matching.write

Request

Path Parameters

  • workflow_id
    Required*
    string

    The workflow identifier of an workflow as assigned by the system

    Example: cd4431f4-505b-11ed-bdc3-0242ac120002

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • 204

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

get matching remediation workflows

  • This service get the matching workflow with given workflow id.
GET /mdm/v1/data_quality/remediation_workflows/{workflow_id}

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

  • workflow_id
    Required*
    string

    The unique identifier of a workflow as assigned by the system

    Example: cd4431f4-505b-11ed-bdc3-0242ac120002

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

GetSingleRemediationWorkflow

The wrapper object for get single workflow response

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "type": "potential_match",
  "id": "cd4431f4-505b-11ed-bdc3-0242ac120002",
  "entities": [
    "person_entity-48242682",
    "person_entity-93523223"
  ],
  "last_update_date": "2022-10-31T16:18:01.864Z",
  "last_update_user": "ID1234",
  "bulk_action": {
    "decision": "link",
    "comments": "these entities are obviously the same."
  },
  "bulk_recommendation": {
    "action": "link",
    "probability": "0.5689"
  },
  "issue_actions": [
    {
      "issue_id": 123456,
      "decision": "link",
      "records": [
        "1",
        "2"
      ],
      "comments": "the social id is matching",
      "last_update_date": "2022-10-31T16:18:01.864Z",
      "last_update_user": "ID1234"
    }
  ]
}

delete matching remediation workflows

  • This service deletes the matching workflow with given workflow id.
DELETE /mdm/v1/data_quality/remediation_workflows/{workflow_id}

Authorization

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

  • mdm-oc.matching.write

Request

Path Parameters

  • workflow_id
    Required*
    string

    The workflow identifier of an workflow as assigned by the system

    Example: cd4431f4-505b-11ed-bdc3-0242ac120002

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • remove_workflow_instance
    boolean

    The API will not delete workflow instance if the value is set to false. Default is true

    Default: true

Response

Status Code

  • 204

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

patch matching remediation workflows

  • This service updates the matching workflow with given workflow id.
PATCH /mdm/v1/data_quality/remediation_workflows/{workflow_id}

Authorization

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

  • mdm-oc.matching.write

Request

Path Parameters

  • workflow_id
    Required*
    string

    The workflow identifier of an workflow as assigned by the system

    Example: cd4431f4-505b-11ed-bdc3-0242ac120002

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
PatchRemediationWorkflow

The wrapper object for patch remediation workflow request

Examples: 
{
  "bulk_action": {
    "decision": "link",
    "comments": "these entities are obviously the same."
  },
  "issue_actions": [
    {
      "issue_id": 123456,
      "decision": "link",
      "records": [
        1,
        2
      ],
      "comments": "the social id is matching",
    }
  ]
}

Response

Response Body

GetSingleRemediationWorkflow

The wrapper object for get single workflow response

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "type": "potential_match",
  "id": "cd4431f4-505b-11ed-bdc3-0242ac120002",
  "entities": [
    "person_entity-48242682",
    "person_entity-93523223"
  ],
  "last_update_date": "2022-10-31T16:18:01.864Z",
  "last_update_user": "ID1234",
  "bulk_action": {
    "decision": "link",
    "comments": "these entities are obviously the same."
  },
  "bulk_recommendation": {
    "action": "link",
    "probability": "0.5689"
  },
  "issue_actions": [
    {
      "issue_id": 123456,
      "decision": "link",
      "records": [
        "1",
        "2"
      ],
      "comments": "the social id is matching",
      "last_update_date": "2022-10-31T16:18:01.864Z",
      "last_update_user": "ID1234"
    }
  ]
}

Report entity confidence metrics

  • This service reports the entity confidence metrics.
GET /mdm/v1/data_quality/entity_confidence_metrics

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    Required*
    string

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

    Example: person_entity

  • update_dq_dashboard
    boolean

    The API will report the entity confidence metrics to DQ dashboard when the parameter is true. Default is false

    Default: false

Response

Response Body

ReportEntityMetrics

Response wrapper object for getting entity quality metrics

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "entity_count_with_potential_match_issues": 10,
  "total_entity_count": 50
}

Retrieve list of issues for given entities

  • This service retrieves list issues for given entities.
GET /mdm/v1/data_quality/issues

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    Required*
    string

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

    Example: person_entity

  • entities
    string[]

    The entity identifiers of an entity as assigned by the system

    Examples: 
    [
  "entity_type-12345678"
]
  • limit
    integer

    The number of issues to be retrieved for the given entities

    Default: 1

    Example: 1

  • offset
    integer

    The number of issues to skip before returning the result

    Default: 0

  • fetch_total_count
    boolean

    If true, the total number of issues for the given entity ids and types will be returned. Otherwise, the number of results will be returned. Default value is true

    Default: true

    Example: true

Response

Response Body

GetDataQualityIssues

The wrapper object for getting data quality issues

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "first": {
    "href": "https://matching:9443/mdm/v1/data_quality/issues?crn=:::::::msk::&offset=0&limit=1"
  },
  "last": {
    "href": "https://matching:9443/mdm/v1/data_quality/issues?crn=:::::::msk::&offset=4&limit=1"
  },
  "next": {
    "href": "https://matching:9443/mdm/v1/data_quality/issues?crn=:::::::msk::&offset=1&limit=1"
  },
  "issues": [
    {
      "type": "potential_match",
      "entity_type": "person_entity",
      "entities": [
        {
          "record_number": "107618727585906689",
          "entity_id": "person_entity-107618727577518081"
        },
        {
          "record_number": "107618727585906689",
          "entity_id": "person_entity-107618727577518081"
        }
      ],
      "created_at": "Jan 15, 2023",
      "resolution_prediction": {
        "probability": 0.7095238,
        "action": "link"
      },
      "id": "vs68cku9hfmp"
    }
  ],
  "total_count": 5,
  "offset": 0,
  "limit": 1
}

list matching remediation workflows

  • This service lists the matching remediation workflows for a given entities.
GET /mdm/v1/data_quality/remediation_workflows

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    Required*
    string

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

    Example: person_entity

  • entities
    string[]

    The entity identifiers of an entity as assigned by the system

    Examples: 
    [
  "entity_type-12345678"
]
  • limit
    integer

    The number of issues to be retrieved for the given entities

    Default: 1

    Example: 1

  • offset
    integer

    The number of issues to skip before returning the result

    Default: 0

Response

Response Body

GetRemediationWorkflows

The wrapper object for getting the remediation workflows for given entity_ids

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "limit": 25,
  "total_count": 1,
  "workflows": [
    {
      "type": "potential_match",
      "id": "cd4431f4-505b-11ed-bdc3-0242ac120002",
      "entities": [
        "person_entity-48242682",
        "person_entity-93523223"
      ],
      "last_update_date": "2022-10-31T16:18:01.864Z",
      "last_update_user": "ID1234",
      "bulk_action": {
        "decision": "link",
        "comments": "these entities are obviously the same."
      },
      "bulk_recommendation": {
        "action": "link",
        "probability": "0.5689"
      },
      "issue_actions": [
        {
          "issue_id": 123456,
          "decision": "link",
          "records": [
            "1",
            "2"
          ],
          "comments": "the social id is matching",
          "last_update_date": "2022-10-31T16:18:01.864Z",
          "last_update_user": "ID1234"
        }
      ]
    }
  ]
}

Start matching remediation workflow

  • This service starts the matching workflow.
POST /mdm/v1/data_quality/remediation_workflows

Authorization

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

  • mdm-oc.matching.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
StartWorkflowRequest

The wrapper object for remediation workflow start request

Examples: 
{
  "type": "potential_match",
  "entities": [
    "person_entity-48242682",
    "person_entity-93523223"
  ]
}

Response

Response Body

StartRemediationWorkflow

The wrapper object for post start workflow response

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "type": "potential_match",
  "id": "cd4431f4-505b-11ed-bdc3-0242ac120002",
  "entities": [
    "person_entity-48242682",
    "person_entity-93523223"
  ],
  "last_update_date": "2022-10-31T16:18:01.864Z",
  "last_update_user": "ID1234",
  "bulk_action": {
    "decision": "link",
    "comments": "these entities are obviously the same."
  },
  "bulk_recommendation": {
    "action": "link",
    "probability": "0.5689"
  },
  "issue_actions": [
    {
      "issue_id": 123456,
      "decision": "link",
      "records": [
        "1",
        "2"
      ],
      "comments": "the social id is matching",
      "last_update_date": "2022-10-31T16:18:01.864Z",
      "last_update_user": "ID1234"
    }
  ]
}

Starts matching bulk remediation workflows

  • This service starts bulk workflows.
POST /mdm/v1/data_quality/remediation_workflows/bulk_start_workflows

Authorization

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

  • mdm-oc.matching.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
StartBulkWorkflowRequest

The wrapper object for starting bulk remediation workflow request

Examples: 
{
  "limit": 25,
  "search_criteria": {
    "search_type": "record",
    "filters": [
      {
        "type": "record",
        "values": [
          "person"
        ]
      }
    ],
    "query": {
      "expressions": [
        {
          "property": "customer_segment.value",
          "condition": "equal",
          "value": "vip",
          "record_type": "person"
        },
        {
          "property": "primary_address.city",
          "condition": "equal",
          "value": "London",
          "record_type": "person"
        }
      ],
      "operation": "and"
    }
  }
}

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

  • 202

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "job_name": "string",
  "last_updated_at": "string",
  "created_at": "string",
  "id": "string",
  "status": "string",
  "additionalProp1": {}
}

Compare records

  • This service compares the input records and returns comparison details.
  • This service supports comparing two records by supplying payload or record_id.
  • This service also supports self comparison of a single input record.
POST /mdm/v1/compare

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    Required*
    string

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

    Example: person_entity

  • details
    string

    The level of information detail in response, ie. low, high, debug

    Default: low

  • record_number1
    int64

    The unique identifier of the first source record as assigned by the system

    Example: 123456789

  • record_number2
    int64

    The unique identifier of the second source record as assigned by the system

    Example: 123456789

  • record_type
    string

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

    Default: person

    Example: person

Request Body

Required*
CompareRecordsRequest

The wrapper object for collection of records

Examples: 
{
  "records": [
    {
      "record_type": "person",
      "attributes": {
        "record_source": "MDM",
        "record_id": "2",
        "record_last_updated": 1506982103000,
        "birth_date": [
          {
            "value": "11/05/1993"
          }
        ],
        "gender": [
          {
            "value": "male"
          }
        ],
        "primary_residence": [
          {
            "record_start": " ",
            "address_line1": "7908 NE VAN TRUMP AVE",
            "city": "LEFOR",
            "province_state": "Texas"
          }
        ]
      }
    }
  ]
}

Response

Response Body

Compare

Response object for comparing records

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "score": 238,
  "score_category": "matched",
  "record_number1": 168071492364660740,
  "record_number2": 168071476032040960
}

Get member records of a cluster

  • This service retrieves member records of a cluster. Clusters can be created for the records of an entity. A cluster represents a closely matched collection of records of an entity.
GET /mdm/v1/clusters/{cluster_id}/records

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

  • cluster_id
    Required*
    string

    The cluster identifier of a cluster as assigned by the system

    Example: entity_type-123456789-0

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • offset
    integer

    The number of entries to skip before returning a page of results. The default offset is 0.

    Default: 0

  • limit
    integer

    The maximum expected number of entries in each page of results. The default limit is 10.

    Default: 10

Response

Response Body

GetClusterRecords

Response wrapper object for getting member records from a cluster

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "first": {
    "href": "https://matching:9443/mdm/v1/clusters/person_entity-110505294894774272-0/records?crn=:::::::msk::&offset=0&limit=10"
  },
  "last": {
    "href": "https://matching:9443/mdm/v1/clusters/person_entity-110505294894774272-0/records?crn=:::::::msk::&offset=0&limit=10"
  },
  "total_count": 1,
  "offset": 0,
  "limit": 10,
  "members": "[110505294894774272]"
}

Get entity detail

  • This service provides entity members, matched pairs, and manual rules.
POST /mdm/v1/entity_detail

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
EntityRequest

The wrapper object of entity and record numbers

Response

Response Body

EntityResponse

Response object for entity details

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "records": [
    {
      "record_number": "52538957658369024",
      "entity_number": "52538957658369024",
      "score": "186"
    },
    {
      "record_number": "52538759671491584",
      "entity_number": "52538759671491584",
      "score": "186"
    },
    {
      "record_number": "52538887606152192",
      "entity_number": "52538759671491584",
      "score": "186"
    }
  ],
  "pairs": [
    {
      "source": "52538759671491584",
      "target": "52538887606152192",
      "score": "183",
      "type": "LINKED"
    },
    {
      "source": "52538759671491584",
      "target": "52538957658369024",
      "score": "58",
      "type": "NOT_LINKED"
    },
    {
      "source": "52538887606152192",
      "target": "52538957658369024",
      "score": "67",
      "type": "NOT_LINKED"
    }
  ]
}

Retrieve information for a job

  • This service retrieves the information about a job which is identified with the supplied job id.
GET /mdm/v1/matching_jobs/{job_id}

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

  • job_id
    Required*
    string

    The unique identifier of the job.

    Example: 95364

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

GetMatchingJobs

Response object for get matching job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "image": "mdm-spark-job",
  "job_name": "match-bulkderiver",
  "created_at": "2021-07-08T06:55:53.000Z",
  "id": "2a01507e-92a8-41c4-8568-2b3dec10889b",
  "last_updated_at": "2021-07-08T07:01:41.000Z",
  "started_at": "2021-07-08T06:55:53.000Z",
  "status": "Success"
}

Add or update manual link/unlink

  • This service adds or updates a collection of manual link/unlink rules.
PUT /mdm/v1/linkage_rules

Authorization

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

  • mdm-oc.matching.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
RulesRequest

The wrapper object of linkage rules

Response

Response Body

object

Response wrapper object for linkage rules

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 409

    The request cannot be processed due to presence of quarantine record(s)

  • 500

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

Example responses
  • {
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}

Compare pairs of records

  • This service compares the input pairs of records and returns comparison details.
  • This service supports comparing multiple pairs of records by supplying pairs of record numbers in the payload.
POST /mdm/v1/batch_compare

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    Required*
    string

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

    Example: person_entity

  • record_type
    Required*
    string

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

    Example: person

  • details
    string

    The level of information detail in response, ie. low, high, debug

    Default: low

Request Body

Required*
BatchComparePairsRequest

The wrapper Object for pairs of record numbers

Examples: 
{
  "pairs": [
    {
      "record_number1": "123",
      "record_number2": "456"
    },
    {
      "record_number1": "321",
      "record_number2": "654"
    }
  ]
}

Response

Response Body

BatchComparePairsResponse

The wrapper object for the comparison details of the pairs compared

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "comparison_details": [
    {
      "score": 238,
      "score_category": "matched",
      "record_number1": 168071492364660740,
      "record_number2": 168071476032040960
    }
  ]
}

Retrieve a cluster

  • This service retrieves the information and explanation of a cluster. Clusters can be created for the records of an entity. A cluster represents a closely matched collection of records of an entity.
GET /mdm/v1/clusters/{cluster_id}

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

  • cluster_id
    Required*
    string

    The cluster identifier of a cluster as assigned by the system

    Example: entity_type-123456789-0

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

GetCluster

Response wrapper object for retrieving one cluster

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "cluster_id": "person_entity-93822496058376193-1",
  "entity_id": "person_entity-93822496058376200",
  "records_count": 1,
  "anomaly": false,
  "explanation": {
    "primary_residence": {
      "city": [
        "MONT",
        "ALTO"
      ],
      "postal_code": [
        "17237"
      ]
    },
    "gender": {}
  }
}

Retrieve derived data for a record

  • This service retrieves the derived data for a given input record.
GET /mdm/v1/index

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_number
    int64

    The unique identifier of a source record as assigned by the system

    Example: 1234567890

  • record_source
    string

    The source system name of the record

    Example: MDM

  • record_id
    string

    The record identifier of the record

    Example: 123456

  • record_type
    string

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

    Example: person

Response

Response Body

GetIndex

Response wrapper object for retrieving the derived matching data for given source record keys

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "self_scores": {
    "person_entity": 344
  },
  "record_number": 35676912450780160,
  "buckets": [],
  "standardized_values": " "
}

Derive and link a record

  • This service performs data derivation for a given input record and assigns entity_ids.
  • Data derivation is the process to standardize and generate buckets for the input records.
  • Entity assignment is the process of finding similar records and linking them with single entity_id.
PUT /mdm/v1/index

Authorization

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

  • mdm-oc.matching.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
SingleRecordRequest

The wrapper Object for a single record

Examples: 
{
  "record_type": "person",
  "attributes": {
    "record_source": "MDM",
    "record_id": "2",
    "record_last_updated": 1506982103000,
    "birth_date": [
      {
        "value": "1964-08-21T00:00:00.000Z"
      }
    ],
    "gender": [
      {
        "value": "mALe"
      }
    ],
    "legal_name": [
      {
        "record_start": "017-10-02 18:08:23.689",
        "generation": "NEWBORN",
        "given_name": [
          "GIRL1",
          "GIRL1",
          "GIRL2",
          "GIRL3",
          "GIRL4"
        ],
        "middle_name": "BABYGIRL"
      }
    ]
  }
}

Response

Response Body

PutIndex

Response wrapper object for the derived matching data for a given source record

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "impacted_records": {
    "person_entity": [
      {
        "record_id": "1",
        "record_number": "35676431109307390",
        "entity_id": "35676431109307390",
        "record_source": "MDM"
      }
    ]
  }
}

Remove derived data for a record

  • This service removes the derived data for a given input record.
DELETE /mdm/v1/index

Authorization

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

  • mdm-oc.matching.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_number
    int64

    The unique identifier of a source record as assigned by the system

    Example: 1234567890

  • record_source
    string

    The source system name of the record

    Example: MDM

  • record_id
    string

    The identifier of the record

    Example: 123456

  • record_type
    string

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

    Example: person

Response

Response Body

PutIndex

Response wrapper object for the derived matching data for a given source record

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "impacted_records": {
    "person_entity": []
  }
}

Preview derived data

  • This service computes and returns a preview of the derived data for the input records.
  • Data derivation is the process to standardize and generate buckets for the input records.
POST /mdm/v1/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 > User > Access.

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • details
    string

    The level of information detail in response, ie. low, high, debug

    Default: low

Request Body

Required*
DeriveRecordsRequest

The wrapper object for collection of records

Examples: 
{
  "records": [
    {
      "record_type": "person",
      "attributes": {
        "record_source": "MDM",
        "record_id": "2",
        "record_last_updated": 1506982103000,
        "birth_date": [
          {
            "value": "1964-08-21T00:00:00.000Z"
          }
        ],
        "gender": [
          {
            "value": "Female"
          }
        ],
        "primary_residence": [
          {
            "record_start": "017-10-02 18:08:23.689",
            "address.residence": "condo",
            "address.address_line1": "7908 NE VAN TRUMP AVE",
            "address.city": "LEFOR"
          }
        ]
      }
    }
  ]
}

Response

Response Body

PostDerive

Response object for previewing the derived matching data for given records

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "index_response": [
    {
      "record_id": "1",
      "record_type": "person",
      "record_source": "MDM",
      "algorithm_name": "person",
      "standardized_values": {},
      "buckets": []
    }
  ]
}

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

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
RulesRequest

The wrapper object of linkage rules

Response

Response Body

object

Response wrapper object for previewing the impacted entities by hypothesizing one or more linkage rules

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 409

    The request cannot be processed due to presence of quarantine record(s)

  • 500

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

Example responses
  • {
  "person_entity": {
    "35678330629897216": [],
    "35678327655087104": [
      "35678330629897216",
      "35678327655087104"
    ]
  }
}

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 > User > Access.

  • mdm-oc.matching.read

Request

Path Parameters

  • entity_id
    Required*
    string

    The entity identifier of an entity as assigned by the system

    Example: entity_type-123456789

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

GetRecordKeys

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

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "records": []
}

Search records by matching algorithm

  • This service searches for the supplied payload and returns record_ids of potential matches.
  • The order of record_ids in the response is determined by matching algorithms.
POST /mdm/v1/probabilistic_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 > User > Access.

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • include_logical_key
    boolean

    To include logical keys in the response, default is true

    Default: true

  • details
    string

    The level of information detail in response, ie. low, high, debug

    Default: low

  • min_score
    integer

    The minimum score to filter the matching records in the results. The default min_score is 0.

  • max_score
    integer

    The maximum score to filter the matching records in the results. The default max_score is 32767.

  • offset
    integer

    The number of entries to skip before returning a page of results. The default offset is 0.

  • entity_type
    string

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

    Default: person_entity

  • limit
    integer

    The maximum expected number of entries in each page of results. The default limit is 20.

Request Body

Required*
SingleRecordRequest

The wrapper Object for a single record

Examples: 
{
  "record_type": "person",
  "attributes": {
    "record_source": "MDM",
    "record_id": "2",
    "record_last_updated": 1506982103000,
    "birth_date": [
      {
        "value": "1964-08-21T00:00:00.000Z"
      }
    ],
    "gender": [
      {
        "value": "mALe"
      }
    ],
    "legal_name": [
      {
        "record_start": "017-10-02 18:08:23.689",
        "generation": "NEWBORN",
        "given_name": [
          "GIRL1",
          "GIRL1",
          "GIRL2",
          "GIRL3",
          "GIRL4"
        ],
        "middle_name": "BABYGIRL"
      }
    ]
  }
}

Response

Response Body

PostSearch

Response object for searching the potential matches of a given search criteria

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "records": [
    {
      "record_id": "101",
      "score": 238,
      "record_source": "PERSONLIST"
    },
    {
      "record_id": "1",
      "score": 238,
      "record_source": "PERSONLIST"
    }
  ]
}

Retrieve an entity's manual links/unlinks

  • This service retrieves all manual link/unlink rules for specified entity.
GET /mdm/v1/entities/{entity_id}/linkage_rules

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

  • entity_id
    Required*
    string

    The entity identifier of an entity as assigned by the system

    Example: person_entity-1234

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

object

Response wrapper object for linkage rules

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "person_entity": [
    {
      "last_updated": "1611866992413",
      "rule_type": "UNLINK",
      "src_recno": "42690607485214720",
      "description": "string",
      "target_recno": "42690601550274560",
      "user": "admin"
    }
  ]
}

Retrieve sample pairs of records

  • This service retrieves the sample pairs from the generated pairs of records for analysis.
GET /mdm/v1/pairs

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • entity_type
    Required*
    string

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

    Example: person_entity

  • size
    integer

    The number of pairs to be retrieved from the generated pairs

    Default: 1

    Example: 1

  • offset
    integer

    The number of pairs to skip before returning the result

    Default: 0

Response

Response Body

GetPairs

Response wrapper object for getting the sample pairs from the generated pairs

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • [
  {
    "score": 207,
    "record_number_1 ": "47096809827657730",
    "comparison_details": {
      "gender_compare": 3,
      "address_compare": 52,
      "phone_compare": 52,
      "name_compare": 34,
      "identifiers_compare": 54,
      "birth_date_compare": 12
    },
    "id": 4.709680982765773e+33,
    "category": "matched",
    "record_number_2": "47096809840240640"
  }
]

Retrieve all entity ids

  • This service retrieves all assigned entity_ids for a given record.
GET /mdm/v1/entity_ids

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_number
    int64

    The unique identifier of a source record as assigned by the system

    Example: 1234567890

  • record_source
    string

    The source system name of the record

    Example: MDM

  • record_id
    string

    The record identifier of the record

    Example: 123

  • record_type
    string

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

    Example: person

Response

Response Body

GetEntityIds

Response wrapper object for getting entity ids

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "entities": [
    {
      "entity_type": "person_entity",
      "entity_id": 32995408531474430
    }
  ]
}

Return clusters, if they exist, for a given entity.

  • This service retrieve all the clusters for records belonging to an entity. Returns existing clusters if present, otherwise, they are generated, stored and then returned.
GET /mdm/v1/entities/{entity_id}/clusters

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

  • entity_id
    Required*
    string

    The entity identifier of an entity as assigned by the system

    Example: entity_type-123456789

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • offset
    integer

    The number of entries to skip before returning a page of results. The default offset is 0.

    Default: 0

  • limit
    integer

    The maximum expected number of entries in each page of results. The default limit is 10.

    Default: 10

  • anomalous_only
    boolean

    The response would contain only anomalous clusters when it is set to true. Default is false

    Default: false

  • fetch_total_count
    boolean

    The response would return total_count as the number of persisted clusters when set to true, otherwise the size of the response. Default is true

    Default: true

Response

Response Body

GetEntityClusters

Response wrapper object for getting the clusters of a given entity_id

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "first": {
    "href": "https://matching:9443/mdm/v1/entities/person_entity-107883101313352704/clusters?crn=:::::::msk::&offset=0&limit=2&anomalous_only=false"
  },
  "last": {
    "href": "https://matching:9443/mdm/v1/entities/person_entity-107883101313352704/clusters?crn=:::::::msk::&offset=4&limit=2&anomalous_only=false"
  },
  "next": {
    "href": "https://matching:9443/mdm/v1/entities/person_entity-107883101313352704/clusters?crn=:::::::msk::&offset=2&limit=2&anomalous_only=false"
  },
  "results": [
    {
      "cluster_id": "person_entity-107883101313352704-0",
      "records_count": 1,
      "anomaly": false
    },
    {
      "cluster_id": "person_entity-107883101313352704-1",
      "records_count": 1,
      "anomaly": false
    }
  ],
  "total_count": 5,
  "offset": 0,
  "limit": 2
}

Retrieve a summary of all derived data

  • This service retrieves a summary of all derived data in system (e.g. entity distribution).
GET /mdm/v1/summary

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • entity_type
    Required*
    string

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

    Example: person_entity

Response

Response Body

GetSummary

Response wrapper object for summary of derived matching data

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
"total_records": 100,
"unique_source_count": 1,
"total_entities": 27,
"stats_and_entities": {
"entity_size_stats": {},
}
}

Retrieve a record's manual links/unlinks

  • This service retrieves all manual link/unlink rules for given record and entity type.
GET /mdm/v1/records/{record_number}/linkage_rules

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

  • record_number
    Required*
    int64

    The unique identifier of a source record as assigned by the system

    Example: 123456789

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    string

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

    Example: entity-type

Response

Response Body

object

Response wrapper object for linkage rules

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "person_entity": [
    {
      "src_recno": "35677335438998529",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user2",
      "last_updated": "1605178647781"
    }
  ]
}

Remove manual link/unlink

  • This service removes one or more manual link/unlink rules supplied by user.
POST /mdm/v1/delete_linkage_rules

Authorization

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

  • mdm-oc.matching.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
RulesRequest

The wrapper object of linkage rules

Response

Response Body

object

Response wrapper object for linkage rules

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 409

    The request cannot be processed due to presence of quarantine record(s)

  • 500

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

Example responses
  • {
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}

Check the existence of linkage rules

  • This service checks for the existence of valid and invalid linkage rules for specified entity type when record filter is enabled.*
GET /mdm/v1/linkage_rules/exist

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • entity_type
    string

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

    Example: person_entity

  • invalid
    boolean

    To check if invalid manual linkage rules exist, default is false

    Default: false

Response

Response Body

RulesExist

Response wrapper object of checking existence of linkage rules

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
    "linkage_rules_exist": "true",
}

Retrieve bucket hash details

  • This service retrives details about all the bucket hashes supplied as an input
POST /mdm/v1/bucket_details

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • include_standardized_data
    boolean

    To check if invalid manual linkage rules exist, default is false

    Default: false

Request Body

Required*
PostHashDetailsRequest

The wrapper Object for list of bucket hashes

Response

Response Body

object

Response wrapper object for bucket hash details

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "1277079518137406915": {
    "candidate_records_count": 1,
    "bucket_group": 1,
    "member_records": [
      "130063453988585473"
    ],
    "isLarge": false,
    "contributing_prehashed_value": "JRLT",
    "contributing_attributes_derived_data": {
      "130063453988585473": {
        "legal_name": [
          {
            "last_name": [
              "TEEL"
            ],
            "given_name": [
              "JERRY"
            ]
          }
        ]
      }
    }
  }
}

Remove all derived data

  • This service removes all derived data for the specified record types.
POST /mdm/v1/reset_matching

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    string

    The data type identifier of source records, ie. person, organization, contract. If not supplied, all record types will be considered

    Example: person

Response

Response Body

PostReset

Response object for removing all the derived matching data

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
    "done_reset": "true",
}

Get comparison details between two clusters

  • This service retrieves comparison details between two clusters in the system. A cluster represents a closely matched collection of records of an entity.
POST /mdm/v1/clusters/compare

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • cluster_id1
    Required*
    string

    The cluster identifier of a cluster as assigned by the system

    Example: entity_type-123456789-0

  • cluster_id2
    Required*
    string

    The cluster identifier of a cluster as assigned by the system

    Example: entity_type-123456789-0

Response

Response Body

ClustersCompare

Response wrapper object for previewing comparison between two clusters

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {"comparison":{"primary_residence":{"cluster1_value":[{"city":["SAN","MATEO"],"postal_code":["32187"]}],"cluster2_value":[{"city":["SAN","MATEO"],"postal_code":["32187"]}]},"gender":{"cluster1_value":[{}],"cluster2_value":[{}]},"social_security_number":{"cluster1_value":[{"identification_number":["398724006"]}],"cluster2_value":[{"identification_number":["398724006"]}]},"legal_name":{"cluster1_value":[{"given_name":["WILDER"]}],"cluster2_value":[{"given_name":["ROSEMARY"]}]}}}

Perform pair wise comparisons of the records for each entity in entities list

Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/score_entities

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • output_path
    Required*
    string

    Output directory

    Example: /entities

  • record_type
    Required*
    string

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

    Example: person

  • entity_type
    Required*
    string

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

    Example: person_entity

  • cos_endpoint
    Required*
    string

    IBM COS end point

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

  • cos_bucket
    Required*
    string

    IBM COS bucket

    Example: mdmexport

  • cos_access_key
    Required*
    string

    IBM COS access key

    Example: b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret

  • cos_secret_key
    Required*
    string

    IBM COS secret key

    Example: <hex string>

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

Request Body

Required*
PairComparatorEntityRequest

The wrapper object for List of entity ids

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "61687493865291776",
  "arguments": "runEntityPairCompare.sh -d person -m person_entity -o /entities -a",
  "start_time": "",
  "process_id": 151,
  "end_time": "",
  "exit_code": 0,
  "metrics": {
    "entity_pair_matched_count": {}
  }
}

Perform asynchronous processing of the import linkage rules job

Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/import_linkage_rules

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

Request Body

Required*
PostImportRulesRequest

The wrapper object for import manual rules request body

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "",
  "exit_code": 0,
  "arguments": "runImportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}

Perform asynchronous processing of the matching export job

Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/matching_export

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • output_path
    string

    The output path under /home/default for the exported data

    Default: /home/default/matching

    Example: /home/default/customFolder

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExportData.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}

Perform asynchronous processing of the derive job of a data file

This job is performed in IBM Cloud Storage. Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/derive

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type of input data

    Example: person

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • do_force
    boolean

    Force to re-derive all records, default is false

    Default: false

  • csv_file
    string

    TSV or CSV file path

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

  • csv_column
    string

    Comma separated column specification of TSV/CSV 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

  • cos_endpoint
    string

    IBM COS end point

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

  • cos_bucket
    string

    IBM COS bucket

    Example: mdmdata

  • cos_access_key
    string

    IBM COS access key

    Example: b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret

  • cos_secret_key
    string

    IBM COS secret key

    Example: <hex string>

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "32616745843241984",
  "arguments": "runDerive.sh -d person",
  "start_time": "",
  "process_id": 13112,
  "end_time": "",
  "exit_code": 0,
  "metrics": {
    "record_count_derived": 100,
    "record_count_no_value": 0,
    "record_count_no_buckets": 0
  }
}

Perform asynchronous processing of the export linkage rules job

Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/export_linkage_rules

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

Request Body

Required*
PostExportRulesRequest

The wrapper object for export manual rules request body

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}

Get Job Summary

Requires the application role of 'MatchingReader'.

GET /mdm/v1/jobs/summary

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • job_id
    Required*
    string

    Job identifier after job been submitted

    Example: 95364

Response

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "job_id": "32616217173608448",
  "arguments": "runMatch.sh -d person -m person_entity",
  "start_time": "2020-10-09T16:00:48.616Z",
  "process_id": 16158,
  "end_time": "2020-10-09T16:00:54.800Z",
  "exit_code": 1,
  "metrics": {}
}

Perform asynchronous processing of the export job

Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/export

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • output_path
    Required*
    string

    Output directory

    Example: /entities

  • record_type
    Required*
    string

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

    Example: person

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • entity_type
    string

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

    Example: person_entity

  • cos_endpoint
    string

    IBM COS end point

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

  • cos_bucket
    string

    IBM COS bucket

    Example: mdmexport

  • cos_access_key
    string

    IBM COS access key

    Example: b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret

  • cos_secret_key
    string

    IBM COS secret key

    Example: <hex string>

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExport.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}

List job

Requires the application role of 'MatchingManager'.

GET /mdm/v1/jobs

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Destroy job

Requires the application role of 'MatchingManager'.

DELETE /mdm/v1/jobs

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • job_id
    Required*
    string

    Job identifier after job been submitted

    Example: 95364

Response

Status Code

  • 200

    The request has been successfully finished.

  • 201

    Created

  • 401

    Authentication error

  • 403

    Authorization error

  • 404

    Http error not found

  • 500

    Unchecked internal server error

No Sample Response

This method does not specify any sample responses.

Perform asynchronous processing of the match job

Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/match

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • do_force
    boolean

    Force to re-match all records, default is false

    Default: false

  • do_deduplicate
    boolean

    Deduplicate pairs, default is false

    Default: false

  • entity_type
    string

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

    Example: person_entity

  • do_analytics
    boolean

    collect analytics report, default is false

    Default: false

  • do_replicate
    boolean

    Replicate entity id, default is false

    Default: false

  • do_checkpoint
    boolean

    Do checkpoint

    Default: false

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "32616805717798912",
  "arguments": "runMatch.sh -d person -m person_entity",
  "start_time": "",
  "process_id": 12941,
  "end_time": "",
  "exit_code": 0,
  "metrics": {
    "person_entity": {
      "bucket_count_compared": 1125,
      "bucket_count_large": 0,
      "bucket_count_singleton": 1776,
      "record_count_updated": 100,
      "record_count_no_buckets": 0,
      "record_count_low_score": 0,
      "record_count_candidate": 100,
      "pair_comparison_count": 5614
    }
  }
}

Index Report

Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/report

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

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

    Example: person

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • entity_type
    string

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

    Example: person_entity

  • job_list
    string

    Comma separated analytics report identifier to be collected, ie. entity_summary, bucket_summary

    Default: entity_summary,bucket_summary

    Example: entity_summary,bucket_summary

  • do_analytics
    boolean

    collect analytics report, default is false

    Default: false

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "32629164350425088",
  "arguments": "runReport.sh -l entity_summary,bucket_summary -d person",
  "start_time": "",
  "process_id": 21901,
  "end_time": "",
  "exit_code": 0,
  "metrics": {
    "bucket_summary": {
      "bucket_dist": {},
      "top_buckets": {}
    },
    "entity_summary": {
      "person_entity": {
        "entity_dist": {},
        "top_entities": {}
      }
    }
  }
}

Initiate generate pairs job

  • This service initiates asynchronous processing of the generate pairs job. Requires the application role of 'MatchingManager'.
POST /mdm/v1/jobs/generate_pairs

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • entity_type
    Required*
    string

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

    Example: person_entity

  • record_type
    Required*
    string

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

    Example: person

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • max_pairs
    string

    The maximum number of pairs to return

    Default: 500

    Example: 500

Response

Response Body

PostJob

Response object for asynchronous processing of a bulk job

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "job_id": "44465189566855168",
  "arguments": "runPairScore.sh -d person -m person_entity",
  "start_time": "2021-02-17T10:55:09.264Z",
  "process_id": 1550,
  "end_time": "2021-02-17T10:55:22.487Z",
  "exit_code": 0,
  "metrics": {
    "total_pairs": 118,
    "bucket_count_compared": 1125,
    "bucket_count_large": 0,
    "bucket_count_singleton": 1776,
    "record_count_updated": 0,
    "record_count_deleted": 0,
    "record_count_no_buckets": 0,
    "record_count_low_score": 0,
    "record_count_candidate": 100,
    "pair_comparison_count": 5614,
    "pair_matched_count": 5101
  }
}

generate weights

Requires the application role of 'MatchingManager'.

POST /mdm/v1/jobs/weights

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • record_type
    Required*
    string

    Record type to be matched

    Example: person

  • do_wait
    boolean

    Wait for job finish, default is false

    Default: false

  • entity_type
    string

    Entity type to be matched, matchs all if missing

    Example: person_entity

Response

Status Code

  • 200

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Get Job Log

Requires the application role of 'MatchingReader'.

GET /mdm/v1/jobs/log

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • job_id
    Required*
    string

    Job identifier after job been submitted

    Example: 95364

Response

Status Code

  • 200

    Success

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Get Job Results

Requires the application role of 'MatchingReader'.

GET /mdm/v1/jobs/result

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • job_id
    Required*
    string

    Job identifier after job been submitted

    Example: 95364

  • relative_filepath
    string

    it is relative filepath for a particular job result

    Example: person.json

Response

Status Code

  • 200

    The request has been successfully finished.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Get matching health status

GET /mdm/v1/matching_health

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • target
    string

    a target of the health check, ie. es, fdb, rabbitmq, neo4j, all

    Default: all

Response

Response Body

GetMatchingHealth

Response object for get matching health

Status Code

  • 200

    The matching service is healthy on the specified target.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Get model health status

GET /mdm/v1/model_health

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • target
    string

    a target of the health check, ie. fdb, rabbitmq

    Default: all

Response

Response Body

GetModelHealth

Response object for get model health

Status Code

  • 200

    The model service is healthy on the specified target.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

No Sample Response

This method does not specify any sample responses.

Retrieve record types of all the matching algorithms

  • This service retrieves the record types of all the matching algorithms present.
  • A matching algorithm contains the matching metadata for a given record type and is comprised of standardization, bucket generation and comparison sections.
GET /mdm/v1/algorithms

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

AlgorithmNames

Response wrapper object for all algorithm names

Status Code

  • 200

    The algorithms' record types has been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "algorithm_names": [
    "organization",
    "person"
  ]
}

Retrieve the matching algorithm

  • This service retrieves the matching algorithm for a given record type.
  • A matching algorithm contains the matching metadata for a given record type and is comprised of standardization, bucket generation and comparison sections.
GET /mdm/v1/algorithms/{record_type}

Authorization

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

  • mdm-oc.model.read

Request

Path Parameters

  • record_type
    Required*
    string

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

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • template
    boolean

    response will return the default template algorithm when set to true

    Default: false

Response

Response Body

Algorithm

The matching algorithm for a given record type (i.e. person)

Status Code

  • 200

    The algorithm has been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "locale": "en_us",
  "encryption": {},
  "standardizers": {},
  "entity_types": {}
}

Overwrite the matching algorithm

  • This service completely overwrites the matching algorithm for a given record type.
  • A matching algorithm defines how two records of a given type are compared.
  • A matching algorithm contains the matching metadata for a given record type and is comprised of standardization, bucket generation and comparison sections.
PUT /mdm/v1/algorithms/{record_type}

Authorization

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

  • mdm-oc.model.write

Request

Path Parameters

  • record_type
    Required*
    string

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

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
Algorithm

The matching algorithm for a given record type (i.e. person)

Response

Response Body

PutAlgorithm

Response wrapper object for overwriting matching algorithm

Status Code

  • 200

    The algorithm has been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_id": "41017488",
  "algorithm": {}
}

generate matching algorithm

  • This service customizes the matching algorithm for a given record type.
  • A matching algorithm defines how two records of a given type are compared.
  • A matching algorithm contains the matching metadata for a given record type and is comprised of standardization, bucket generation and comparison sections.
POST /mdm/v1/algorithms/{record_type}

Authorization

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

  • mdm-oc.model.write

Request

Path Parameters

  • record_type
    Required*
    string

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

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
object

The matching algorithm for a given record type (i.e. person)

Response

Response Body

PutAlgorithm

Response wrapper object for overwriting matching algorithm

Status Code

  • 200

    The algorithm has been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_id": "41017488",
  "algorithm": {}
}

Partially modify matching algorithm

  • This service partially modifies the matching algorithm for a given record type.
  • A matching algorithm defines how two records of a given type are compared.
  • A matching algorithm contains the matching metadata for a given record type and is comprised of standardization, bucket generation and comparison sections.
PATCH /mdm/v1/algorithms/{record_type}

Authorization

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

  • mdm-oc.model.write

Request

Path Parameters

  • record_type
    Required*
    string

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

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
Algorithm

The matching algorithm for a given record type (i.e. person)

Response

Response Body

PutAlgorithm

Response wrapper object for overwriting matching algorithm

Status Code

  • 200

    The algorithm has been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_id": "135208",
  "algorithm": {}
}

Retrieve details of comparison parameters

  • This service retrieves the comparison parameters for a given specification name.
  • Comparison parameters are maintained in a json document and is used for comparing attributes within an algorithm.
GET /mdm/v1/compare_spec_resources/{resource_name}

Authorization

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

  • mdm-oc.model.read

Request

Path Parameters

  • resource_name
    Required*
    string

    The unique identifier for the comparison parameters

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

CompareSpecResource

A single comparison resource used to customize comparison logic of a matching algorithm

Status Code

  • 200

    The resources have been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "typo_distance": 0.25,
  "similar_characters_distance": 0.5,
  "similar_characters_map_resource": "person_map_character_similar_character",
  "feature_categories": {
    "id": {
      "features": [
        "similarity"
      ],
      "fields": [
        "email_local_part"
      ]
    },
    "domain": {
      "features": [
        "similarity"
      ],
      "fields": [
        "email_domain"
      ]
    }
  },
  "feature_coefficients": {
    "id_similarity": 0.9,
    "domain_similarity": 0.1
  }
}

Overwrite the comparison parameters

  • This service completely overwrites the comparison parameters for a given specification name.
  • Comparison parameters are maintained in a json document and is used for comparing attributes within an algorithm.
PUT /mdm/v1/compare_spec_resources/{resource_name}

Authorization

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

  • mdm-oc.model.write

Request

Path Parameters

  • resource_name
    Required*
    string

    The unique identifier for the comparison parameters

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
CompareSpecResource

A single comparison resource used to customize comparison logic of a matching algorithm

Response

Response Body

PutCompareSpecResources

Response wrapper object for overwriting comparison resource

Status Code

  • 200

    The resources have been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "compare_spec_resources": {}
}

Retrieve a summary of all comparison parameters

  • This service retrieves the list of specification names for the existing comparison parameters.
GET /mdm/v1/compare_spec_resources

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

CompareSpecResourceNames

Response wrapper object for all comparison resource names

Status Code

  • 200

    The resources have been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "compare_spec_resource_names": [
    "person_compare_spec_email",
    "org_compare_spec_identifier",
    "person_compare_spec_non_phone",
    "org_compare_spec_phone",
    "org_compare_spec_name",
    "persongnm_compare_spec_name",
    "person_compare_spec_identifier",
    "person_compare_spec_date",
    "person_compare_spec_name",
    "org_compare_spec_address",
    "person_compare_spec_gender",
    "person_compare_spec_phone",
    "person_compare_spec_address"
  ]
}

Retrieve details of equivalency criteria

  • This service retrieves all existing equivalency criteria for a given resource name.
  • A Map Resource is a json document containing a collection of equivalency criteria (e.g. BOB, ROB) for given tokens (e.g. ROBERT).
  • A Map Resource may be used in standardization, bucket generation and comparison recipes within one more more algorithms.
GET /mdm/v1/map_resources/{resource_name}

Authorization

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

  • mdm-oc.model.read

Request

Path Parameters

  • resource_name
    Required*
    string

    The unique identifier for the configuration for the equivalent words

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

object

A single map resource used for matching algorithm like for handling equivalent values. Map resource key must be lower snake case (i.e. nickname)

Status Code

  • 200

    The resources have been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The resources requested do not exist.

  • 500

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

Example responses
  • {
  "country": [
    {
      "category": "",
      "key": "USA",
      "values": [
        "UNITED STATES",
        "UNITED STATES OF AMERICA",
        "US"
      ],
      "regex": []
    },
    {
      "category": "",
      "key": "UK",
      "values": [
        "GREAT BRITAIN",
        "UNITED KINGDOM"
      ],
      "regex": []
    }
  ]
}

Overwrite equivalency criteria

  • This service completely overwrites equivalency criteria for a given resource name.
  • A Map Resource is a json document containing a collection of equivalency criteria (e.g. BOB, ROB) for given tokens (e.g. ROBERT).
  • A Map Resource may be used in standardization, bucket generation and comparison recipes within one more more algorithms.
PUT /mdm/v1/map_resources/{resource_name}

Authorization

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

  • mdm-oc.model.write

Request

Path Parameters

  • resource_name
    Required*
    string

    The unique identifier for the configuration for the equivalent words

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
object

A single map resource used for matching algorithm like for handling equivalent values. Map resource key must be lower snake case (i.e. nickname)

Response

Response Body

PutMapResources

Response wrapper object for overwriting map resource

Status Code

  • 200

    The resources have been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_id": "172056",
  "map_resources": {}
}

Retrieve a summary of all equivalency criteria

  • This service retrieves the list of resource names of all existing equivalency criteria.
  • A Map Resource is a json document containing a collection of equivalency criteria (e.g. BOB, ROB) for given tokens (e.g. ROBERT).
  • A Map Resource may be used in standardization, bucket generation and comparison recipes within one more more algorithms.
GET /mdm/v1/map_resources

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

MapResourceNames

Response wrapper object for all map resource names

Status Code

  • 200

    The resources have been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "map_resource_names": [
    "person_map_address_address_line_equivalents",
    "person_map_address_country_equivalents",
    "org_map_address_province_equivalents",
    "org_map_character_phone",
    "person_map_address_tokens_city",
    "org_map_address_province_state",
    "person_map_address_tokens_latitude",
    "org_map_address_sub_division_equivalents",
    "person_map_address_tokens_province",
    "person_map_address_tokens_street_number_name_direction_type",
    "org_map_address_tokens_longtitude"
  ]
}

Retrieve a summary of all anonymous words

  • This service retrieves a summary of resource names for all anonymous words.
  • A Set Resource is a json document that generally contains grouped list of values of interest.
  • A Set Resource may be used in one or more matching algorithms to filter out the anonymous words in the input fields from further processing.
GET /mdm/v1/set_resources

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

SetResourceNames

Response object wrapper for all set resource names

Status Code

  • 200

    The resources have been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "set_resource_names": [
    "org_set_phone_anon_phone",
    "person_set_address_postal_code",
    "person_set_identifier_corp_taxid",
    "person_set_character_date",
    "org_set_character_date",
    "person_set_phone_anon_phone",
    "org_set_identifier_anonymous",
    "org_set_name_bkt_anon",
    "person_set_identifier_anonymous",
    "person_set_identifier_duns_num",
    "person_set_name_digits",
    "person_set_name_acname",
    "person_set_character_cstop_pxnm"
  ]
}

Retrieve details of anonymous words

  • This service retrieves the details of all anonymous words for a given resource name.
  • A Set Resource is a json document that generally contains grouped list of values of interest.
  • A Set Resource may be used in one or more matching algorithms to filter out the anonymous words in the input fields from further processing.
GET /mdm/v1/set_resources/{resource_name}

Authorization

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

  • mdm-oc.model.read

Request

Path Parameters

  • resource_name
    Required*
    string

    he unique identifier for the configuration for the anonymous set of words

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

object

A single set resource used for matching algorithm like for handling anonymous values. Set resource key must be lower snake case (i.e. anonymous)

Status Code

  • 200

    The resources have been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "date": {
    "values": [
      "-"
    ],
    "regex": []
  }
}

Overwrite anonymous words

  • This service completely overwrites the anonymous words for a given resource name.
  • A Set Resource is a json document that generally contains grouped list of values of interest.
  • A Set Resource may be used in one or more matching algorithms to filter out the anonymous words in the input fields from further processing.
PUT /mdm/v1/set_resources/{resource_name}

Authorization

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

  • mdm-oc.model.write

Request

Path Parameters

  • resource_name
    Required*
    string

    he unique identifier for the configuration for the anonymous set of words

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
object

A single set resource used for matching algorithm like for handling anonymous values. Set resource key must be lower snake case (i.e. anonymous)

Response

Response Body

PutSetResources

Response wrapper object for overwriting set resource

Status Code

  • 200

    The resources have been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_id": "172056",
  "set_resources": {
    "date": {
      "regex": [],
      "values": [
        "-"
      ]
    }
  }
}

Retrieve the survivorship composite rules

  • Retrieve the survivorship composite rules applicable to entity types, as defined by matching algorithms
  • The ability to construct survived "picture" of the linked records relies on Composite Rule definition.
  • Composite Rule is a json document that contains survivorship criteria at global level or within a specific scope.
GET /mdm/v1/composite_rules

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

CompositeRules

The wrapper object of composite rules

Status Code

  • 200

    The composite rules have been successfully modified.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "locale": "en_us",
  "rules": {
    "global": {
      "choices": [
        "mca",
        "mfa"
      ],
      "sources": []
    }
  }
}

Overwrite the survivorship composite rules

  • Overwrite the survivorship composite rules applicable to entity types, as defined by matching algorithm
  • The ability to construct survived "picture" of the linked records relies on Composite Rule definition.
  • Composite Rule is a json document that contains survivorship criteria at global level or within a specific scope.
PUT /mdm/v1/composite_rules

Authorization

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

  • mdm-oc.model.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
CompositeRules

The wrapper object of composite rules

Response

Response Body

PutCompositeRules

Response wrapper object for overwriting composite rules

Status Code

  • 200

    The composite rules have been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_id": "172056",
  "composite_rules": {}
}

Retrieve the data model

  • This service retrieves the data model for record types and relationship types.
  • Data model defines the fields and attributes associated to one or more record types (e.g. person, organization) and one or more relationship types (e.g. sibling, employment).
GET /mdm/v1/data_model

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • version
    string

    The identifier for a given state of the data model, ie. current, draft

    Default: current

Response

Response Body

DataModel

Collection of record and relationship types definition

Status Code

  • 200

    The data model has been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "locale": "en_us",
  "system_properties": {},
  "record_types": {},
  "attribute_types": {},
  "relationship_types": {}
}

Overwrite the data model

  • This service completely overwrites the data model for record types and relationship types.
  • Data model defines the fields and attributes associated to one or more record types (e.g. person, organization) and one or more relationship types (e.g. sibling, employment).
PUT /mdm/v1/data_model

Authorization

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

  • mdm-oc.model.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataModel

Collection of record and relationship types definition

Response

Response Body

PutDataModel

Response wrapper object for overwritting data model

Status Code

  • 200

    The data model has been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "draft",
  "flow_id": "41017488",
  "data_model": {
    "locale": "en_us",
    "system_properties": {},
    "record_types": {},
    "attribute_types": {},
    "relationship_types": {}
  }
}

Partially modify data model

  • This service partially modifies the data model for record types and relationship types.
  • Data model defines the fields and attributes associated to one or more record types (e.g. person, organization) and one or more relationship types (e.g. sibling, employment).
PATCH /mdm/v1/data_model

Authorization

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

  • mdm-oc.model.write

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
DataModel

Collection of record and relationship types definition

Response

Response Body

PutDataModel

Response wrapper object for overwritting data model

Status Code

  • 200

    The data model has been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_id": "135208",
  "data_model": {}
}

Retrieve list of event subscription based on filters

  • This service retrieves a list of event subscriptions based on filters.
GET /mdm/v1/event_subscription

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • limit
    integer

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

    Possible values: value ≤ 50

    Default: 10

  • offset
    integer

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

    Default: 0

  • event_type
    string

    Type of the event, i.e. entity_change or record_change

    Example: entity_change

Response

Response Body

EventSubscriptions

Response wrapper object for retrieving event subscriptions

Status Code

  • 200

    List of event subscriptions have been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "event_subscriptions": [
    {
      "subscription_id": "1678466128043",
      "filter": [
        "filter1",
        "filter2"
      ],
      "event_type": "entity_change",
      "created_user": "mdmadmin",
      "last_update_user": "mdmadmin",
      "stream_connection": {
        "stream_connection_properties": {
          "str3": "str1",
          "str1": "str1",
          "str2": "str1"
        },
        "stream_type": "Kafka",
        "asset_scope": "Project",
        "topic": "test",
        "asset_id": "asset01",
        "container_id": "containerid01"
      },
      "subscription_description": "Type of the event, i.e. entity_change or record_change",
      "subscription_name": "test_sub_01",
      "active": false,
      "created_date": 1678706808248,
      "last_update_date": 1678706808248
    },
    {
      "subscription_id": "1678466128056",
      "filter": [
        "filter1",
        "filter2"
      ],
      "event_type": "notification",
      "created_user": "mdmadmin",
      "last_update_user": "mdmadmin",
      "stream_connection": {
        "stream_connection_properties": {
          "prop2": "value2",
          "prop1": "value1"
        },
        "stream_type": "Pulsar",
        "asset_scope": "Catalog",
        "topic": "entityid",
        "asset_id": "asset02",
        "container_id": "containerid02"
      },
      "subscription_description": "test_sub_02 description",
      "subscription_name": "test_sub_02",
      "active": false,
      "created_date": 1678706808399,
      "last_update_date": 1678706808399
    }
  ]
}

Create or Update Event Subscription

  • This service performs the event subscription creation/update.
PUT /mdm/v1/event_subscription

Authorization

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

  • mdm-oc.model.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
EventSubscription

Request wrapper object for event subscription

Response

Response Body

EventSubscription

Request wrapper object for event subscription

Status Code

  • 200

    Event subscription process is successful.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "subscription_id": "11223344",
  "filter": "["11223344", "11223345"]",
  "event_type": "entity_change",
  "created_user": "mdmadmin",
  "last_update_user": "mdmadmin",
  "subscription_description": "Type of the event, i.e. entity_change or record_change",
 "stream_connection": "{
 "description": "Stream connection details",
 "asset_scope": "Project",
 "container_id": "Container01",
 "asset_id": "Project",
 "topic": "test",
 "stream_type": "Kafka",
 "stream_connection_properties": "{
 "key1": "value1",
 "key2": "value2"
 "key3": "value3"
 "}"
 "}"
  "subscription_name": "test_sub_01",
  "active": "false",
  "created_date": "1678706808248",
  "last_update_date": "1678706808248"
}

Remove an existing Event subscription

  • This service removes an existing Event subscription specified by the supplied subscription_id.
DELETE /mdm/v1/event_subscription/{subscription_id}

Authorization

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

  • mdm-oc.model.manage

Request

Path Parameters

  • subscription_id
    Required*
    string

    The unique identifier of a subscription_id as assigned by the system

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

object

Status Code

  • 200

    The event subscription has been successfully removed.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {}

This service exports the model data to shared volume at the destination folder

Requires the application role of 'ModelManager'.

POST /mdm/v1/jobs/model_export

Authorization

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

  • mdm-oc.model.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • output_path
    string

    The output path under for the exported data

    Default: /shared-volume/model

    Example: /shared-volume/model

Response

Status Code

  • 204

    The request has been successfully finished.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

  • 501

    The request cannot be processed due to the server not supporting the required functionality

No Sample Response

This method does not specify any sample responses.

Retrieve the active workflow information

  • This service retrieves the active workflow information, if present, of a previously requested change to data model.
  • An update to data model is only finalized when its corresponding workflow is approved by the authorized approvers.
  • This capability is primarily built for internal approval processes.
GET /mdm/v1/flows

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

ActiveFlow

Response wrapper object for retrieving active flow

Status Code

  • 200

    The flow status of an active workflow has been successfully retrieved

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "flows": [
    {
      "flow_state": "draft",
      "flow_type": "data_model",
      "rejections": [],
      "flow_id": "327733440",
      "approvals": [],
      "active": true
    }
  ]
}

Retrieve the latest workflow information

  • This service retrieves the latest workflow information of a previously requested change to data model.
  • An update to data model is only finalized when its corresponding workflow is approved by the authorized approvers.
  • This capability is primarily built for internal approval processes.
GET /mdm/v1/flows/{flow_id}

Authorization

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

  • mdm-oc.model.read

Request

Path Parameters

  • flow_id
    Required*
    string

    The unique identifier of a workflow as assigned by the system

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

Flow

Response wrapper object for retrieving a flow

Status Code

  • 200

    The flow status has been successfully retrieved

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_type": "data_model",
  "rejections": [],
  "flow_id": "192696",
  "approvals": [],
  "active": false
}

Remove an existing workflow

  • This service removes an existing workflow specified by the supplied flow_id.
  • An update to data model is only finalized when its corresponding workflow is approved by the authorized approvers.
  • This capability is primarily built for internal approval processes.
DELETE /mdm/v1/flows/{flow_id}

Authorization

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

  • mdm-oc.model.manage

Request

Path Parameters

  • flow_id
    Required*
    string

    The unique identifier of a workflow as assigned by the system

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

object

Status Code

  • 200

    The flow has been successfully removed.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {}

Approve or Reject an active workflow

  • This service is used to approve or reject an active workflow specified by the supplied flow_id.
  • An update to data model is only finalized when its corresponding workflow is approved by the authorized approvers.
  • This capability is primarily built for internal approval processes.
PATCH /mdm/v1/flows/{flow_id}

Authorization

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

  • mdm-oc.model.write

Request

Path Parameters

  • flow_id
    Required*
    string

    The unique identifier of a workflow as assigned by the system

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
FlowRequest

Request wrapper object for updating a flow

Response

Response Body

Flow

Response wrapper object for retrieving a flow

Status Code

  • 200

    The flow has been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "flow_state": "published",
  "flow_type": "data_model",
  "rejections": [],
  "flow_id": "192696",
  "approvals": [],
  "active": false
}

Retrieve masked attributes for a user.

  • This service retrieves the masked attributes for a user
GET /mdm/v1/masked_attributes

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • data_type
    Required*
    string

    The type identifier for record_types or entity_types

    Example: record_types

  • data_value
    Required*
    string

    The data type identifier of source records, ie. person, organization, contract or entity, ie. person_entity, organization_entity, household_entity

    Example: person

Response

Response Body

GetMaskedAttributes

Response wrapper object for masked fields for a user

Status Code

  • 200

    The list of masked columns has been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "masked_columns": [
    {
      "masked_type": "obfuscate",
      "masked_column": "drivers_licence.identification_number"
    },
    {
      "masked_type": "substitute",
      "masked_column": "legal_name.last_nam"
    }
  ]
}

Retrieve the governance metadata containing the connected data asset details.

  • This service retrieves the connected data asset details for record types and entity types
GET /mdm/v1/governance_metadata

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

GovernanceMetadata

Wrapper object for connected data asset for record types and entity types

Status Code

  • 200

    The connected data asset details has been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "entity_types": {
    "person_entity": {
      "asset_id": "723383939"
    }
  },
  "record_types": {
    "person": {
      "asset_id": "1262727272"
    }
  }
}

Retrieve the configured metadata

  • This service retrieves the configured metadata for a provisioned instance of system.
  • The onboarding process of a new subscriber to Master Data Management On Cloud depends on capturing and maintaining certain configured metadata for their provisioned instance.
  • Instance Metadata is a json document that primarily contains the catalog and project information in Watson Knowledge Catalog and the details of Cloud Object Storage if provided by the user.
GET /mdm/v1/instance_metadata

Authorization

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

  • mdm-oc.model.read

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

InstanceMetadataResponse

Wrapper object for instance metadata response

Status Code

  • 200

    The instance metadata has been successfully retrieved.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 404

    The request cannot be processed due to resource not found.

  • 500

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

Example responses
  • {
  "label": "test instance",
  "catalogs": [
    {
      "catalog_instance": "wkc instance",
      "catalog_id": "123_catalog"
    }
  ],
  "projects": [
    {
      "project_id": "123_project",
      "project_name": "test project",
      "asset_id": "123_asset"
    }
  ],
  "job_project_id": "123",
  "workflow_configuration_id": "worflow-config-id",
  "workflow_type_id": "type-id"
}

Overwrite the configured metadata

  • This service overwrites the configured metadata for a provisioned instance of system.
  • The onboarding process of a new subscriber to Master Data Management On Cloud depends on capturing and maintaining certain configured metadata for their provisioned instance.
  • Instance Metadata is a json document that primarily contains the catalog and project information in Watson Knowledge Catalog and the details of Cloud Object Storage if provided by the user.
PUT /mdm/v1/instance_metadata

Authorization

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

  • mdm-oc.model.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
InstanceMetadata

Wrapper object for instance metadata

Response

Response Body

InstanceMetadataResponse

Wrapper object for instance metadata response

Status Code

  • 200

    The instance metadata has been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 403

    The request cannot be processed due to insufficient permission error.

  • 500

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

Example responses
  • {
  "label": "test instance",
  "catalogs": [
    {
      "catalog_instance": "wkc instance",
      "catalog_id": "123_catalog"
    }
  ],
  "projects": [
    {
      "project_id": "123_project",
      "project_name": "test project",
      "asset_id": "123_asset"
    }
  ],
  "job_project_id": "123"
}

Configure workflow in WKC Workflow service

  • This service performs the workflow configuration for Potential Matches in WKC Workflow services.
POST /mdm/v1/configure_workflow

Authorization

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

  • mdm-oc.model.manage

Request

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

  • workflow_template_name
    string

    To select one workflow template

Request Body

Required*
ConfigureWorkflow

Request for initiating workflow configuration

Response

Response Body

ConfigureWorkflowResponse

Response wrapper object for workflow configuration

Status Code

  • 200

    Workflow service configuration is successful.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 500

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

Example responses
  • {
  "workflow_configuration_id": "f37fed77-5d2a-4ca5-9914-7d5b3b4dcf62",
  "workflow_type_id": "d24cfe5e-35aa-4085-b688-24b2bd984e15"
}

Get generic workflows per workflow type

  • This service completely retrieves the workflow configuration for a given workflow type.
GET /mdm/v1/workflows_configuration/{workflow_type}

Authorization

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

  • mdm-oc.model.manage

Request

Path Parameters

  • workflow_type
    Required*
    string

    The workflow confiuration type

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Response

Response Body

WorkflowConfiguration

A configuration object for a workflow for a given workflow type.

Status Code

  • 200

    The workflow has been successfully retrieved.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 500

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

Example responses
  • {
  "description": "",
  "applicable_data_types": {
    "record_types": [],
    "entity_types": []
  },
  "auto_create_tasks": true,
  "max_accumulated_updates": 50,
  "custom_tags": {},
  "max_tasks": {
    "default": 300,
    "sources": {
      "sourceA": {
        "default": 100,
        "record_types": {
          "person": 50
        },
        "entity_types": {
          "household_entity": 100
        }
      }
    }
  },
  "trigger_operator": {
    "record_types": {
      "person": {
        "excluded_sources": [],
        "included_sources": [],
        "entity_types": {
          "person_entity": {
            "triggers": {
              "default": [
                {
                  "label": "Name and DOB",
                  "recipe": {
                    "pername_compare": 2,
                    "date_compare": 3
                  }
                },
                {
                  "label": "SSN",
                  "recipe": {
                    "identification_compare": 1
                  }
                }
              ],
              "source_based": {
                "sourceA": [
                  {
                    "label": "Name and Gender",
                    "recipe": {
                      "pername_compare": 2,
                      "gender_compare": 1
                    }
                  }
                ],
                "sourceB": []
              }
            }
          },
          "household_entity": {}
        }
      },
      "organization": {}
    },
    "entity_types": {},
    "hierarchy_types": {}
  }
}

Put generic workflows per workflow type

  • This service completely overwrites the workflow configuration for a given workflow type.
PUT /mdm/v1/workflows_configuration/{workflow_type}

Authorization

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

  • mdm-oc.model.manage

Request

Path Parameters

  • workflow_type
    Required*
    string

    The workflow confiuration type

Query Parameters

  • crn
    Required*
    string

    The cloud resource name of the service.

Request Body

Required*
WorkflowConfiguration

A configuration object for a workflow for a given workflow type.

Response

Response Body

WorkflowConfiguration

A configuration object for a workflow for a given workflow type.

Status Code

  • 200

    The workflow has been successfully modified.

  • 400

    The request cannot be processed due to user error.

  • 401

    The request cannot be processed due to authentication error.

  • 500

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

Example responses
  • {
  "description": "",
  "applicable_data_types": {
    "record_types": [],
    "entity_types": []
  },
  "auto_create_tasks": true,
  "max_accumulated_updates": 50,
  "custom_tags": {},
  "max_tasks": {
    "default": 300,
    "sources": {
      "sourceA": {
        "default": 100,
        "record_types": {
          "person": 50
        },
        "entity_types": {
          "household_entity": 100
        }
      }
    }
  },
  "trigger_operator": {
    "record_types": {
      "person": {
        "excluded_sources": [],
        "included_sources": [],
        "entity_types": {
          "person_entity": {
            "triggers": {
              "default": [
                {
                  "label": "Name and DOB",
                  "recipe": {
                    "pername_compare": 2,
                    "date_compare": 3
                  }
                },
                {
                  "label": "SSN",
                  "recipe": {
                    "identification_compare": 1
                  }
                }
              ],
              "source_based": {
                "sourceA": [
                  {
                    "label": "Name and Gender",
                    "recipe": {
                      "pername_compare": 2,
                      "gender_compare": 1
                    }
                  }
                ],
                "sourceB": []
              }
            }
          },
          "household_entity": {}
        }
      },
      "organization": {}
    },
    "entity_types": {},
    "hierarchy_types": {}
  }
}
id=curlclassName=tab-item-selected