IBM Match 360 as a Service API Reference

Introduction

Last updated: 2025-05-28

IBM Match 360 as a Service provides APIs that enable you to connect its powerful master data matching capabilities to your systems and processes. IBM Match 360 as a Service is an IBM Cloud service delivered through IBM Cloud Pak for Data as a Service that enables you to establish a single, trusted, 360-degree view of your customers -- a digital twin. IBM Match 360 includes cloud-native, 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 as a Service, you can ensure that your users and systems have a total view of your data. With a seamlessly integrated, cross-solution cloud experience, your users can discover master data directly in the space where they expect to consume it.

The IBM Match 360 as a Service APIs support:

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

For more information about using IBM Match 360 as a Service, see the Cloud Pak for Data as a Service documentation.

Tip: To access the API documentation by using the Swagger UI tool, open a web browser and go to: https://api.{endpoint-location}.mdm.watson.cloud.ibm.com/api-{api-name}/explorer/. Replace {endpoint-location} in the URL with the location code of your deployment's multizone region, and replace {api-name} with the name of the IBM Match 360 API service you are accessing: data, model, job, matching, or configuration.

For example, to access the APIs in the Dallas global endpoint (us-south), go to the following URLs:

Configuration API: https://api.us-south.mdm.watson.cloud.ibm.com/api-configuration/explorer/
Entity Maintenance API: https://api.us-south.mdm.watson.cloud.ibm.com/api-data/explorer/
Job API: https://api.us-south.mdm.watson.cloud.ibm.com/api-job/explorer/
Matching API: https://api.us-south.mdm.watson.cloud.ibm.com/api-matching/explorer/
Model API: https://api.us-south.mdm.watson.cloud.ibm.com/api-model/explorer/

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install --save master-data—management-cloud

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
  <groupId>com.ibm.cloud</groupId>
  <artifactId>mdm</artifactId>
  <version>1.0.6</version>
</dependency>
Copy to clipboard

Gradle

implementation 'com.ibm.cloud:mdm:1.0.6'

GitHub https://github.com/IBM/mdm-java-sdk

The code examples on this tab use the client library that is provided for Python.

Installation

pip install master-data-management

Endpoint URLs

The IBM Match 360 as a Service API uses the Dallas global endpoint URL for all regions. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://api.dataplatform.cloud.ibm.com

Example request to the Dallas endpoint

curl -u "apikey:{apikey}" -X {request_method} "https://api.dataplatform.cloud.ibm.com/{method_endpoint}"

Replace {apikey}, {request_method}, and {method_endpoint} in this example with the values for your particular API call.

Example request to the Dallas endpoint

const MasterDataManagementV1 = require('ibm/master-data-management/v4');
const { IamAuthenticator } = require('ibm/auth');

const masterDataManagement = new MasterDataManagementV1({
  version: '{version}',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  url: 'https://api.dataplatform.cloud.ibm.com/{method_endpoint}',
});

Replace {apikey}, {version}, and {method_endpoint} in this example with the values for your particular API call.

Example request to the Dallas endpoint

import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.ibm.cloud.mdm.v1.Mdm;
Authenticator authenticator = new BearerTokenAuthenticator("<access-token>");
Mdm mdm = new Mdm(crn, Mdm.DEFAULT_SERVICE_NAME, authenticator);

Replace <access-token> in this example with the values for your particular API call.

Later, when the access token expires, the application must acquire a new access token, then set it on the authenticator. Subsequent request invocations will include the new access token.

authenticator.setBearerToken("<new-access-token>")

Alternatively, use external configuration and provide values for the below properties

MDM_URL=https://api.dataplatform.cloud.ibm.com/
MDM_AUTH_TYPE=bearertoken
MDM_BEARER_TOKEN=<access-token>

and access the service using

Mdm service = Mdm.newInstance(crn);

Example request to the Dallas endpoint

from ibm import MasterDataManagementV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
master_data_management = MasterDataManagementV1(
    version='{version}',
    authenticator=authenticator
)

master_data_management.set_service_url('https://api.dataplatform.cloud.ibm.com/{method_endpoint}')

Replace {apikey}, {version}, and {method_endpoint} in this example with the values for your particular API call.

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.
`400`	Bad Request	The input parameters in the request body 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 IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access '{namespace}'.
`404`	Not Found	The requested resource could not be found.
`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.
`500`	Internal Server Error	offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

ErrorContainer

Field name	Type	Description
status_code	integer	The HTTP status code of the response.
errors	`List<ErrorMessage>`	A list of errors.
trace	string	The lower case UUID that uniquely identies the request.

ErrorMessage

Field name	Type	Description
code	string	A snake_case string succinctly identifying the problem.
message	string	An explanation of the solution to the problem.
more_info	string	A publicly-accessible URL where information about the error can be read in a web browser.
target	`ErrorTarget`	An error target model.

ErrorTarget

Field name	Type	Description
type	string	The type of the error target. One of: `field`, `parameter`, or `header`.
name	string	The name of the field, parameter, or header.

When the Node SDK receives an error response from the IBM Match 360 service, it creates an Error object with information describing the error that occurred. This error object is passed as the first parameter to the callback function for the method. The contents of the error object are as shown in the following table:

Errors

Error field	Description
code	The HTTP status code returned.
message	A message describing the error.

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 from the com.ibm.master_data_management.service.exception package. All service exceptions contain the following fields:

Error 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 a MasterDataManagementAPIException containing the following fields:

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

masterDataManagement.method(params,
    function(err, response) {
        // The error will be the first argument of the callback
        if (err.code == 404) {
            // Handle Not Found (404) error
        } else if (err.code == 413) {
            // Handle Request Too Large (413) error
        } else {
            console.log('Unexpected error: ', err.code);
            console.log('error:', err);
        }
    });
Copy to clipboard

Example error handling

try {
    // Invoke an 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());
}
Copy to clipboard

Example error handling

from master_data_management import MasterDataManagementAPIException
try:
    # Invoke an IBM Match 360 method
except MasterDataManagementAPIException as ex:
    print "Method failed with status code " + str(ex.code) + ": " + ex.message
Copy to clipboard

Authentication

To authenticate to the IBM Match 360 API, you pass a bearer token in an Authorization header. The token is associated with a user name.

The bearer authentication token can be obtained using cURL: curl -X POST https://iam.cloud.ibm.com/identity/token -H "content-type: application/x-www-form-urlencoded" -H "accept: application/json" -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=APIKEY"

The following cURL example shows authentication being passed using a bearer token: curl -X PUT --header "Authorization: Bearer {accessToken}" --header "Accept: application/json" "{url}/mdm/configuration/v1/config_data_model/publish_model?project_id=config_42d00915_1497_4d65_90af_cfd09d015769%3A31925406598685396&crn=CRN”

Replace {accessToken} with your authentication bearer token.

Generating a bearer token. The response includes an accessToken property.

Replace {cpd_cluster_host} and {port} with the details for the service instance. Replace {username} and {password} with your IBM Cloud Pak for Data credentials.

curl -k -u "{username}:{password}" "https://{cpd_cluster_host}{:port}/v1/preauth/validateAuth"

Authenticating to the API. Replace {accessToken} with your authentication bearer token.

curl -H "Authorization: Bearer {accessToken}" "{url}/v1/{method}"

Example header parameter in a request

masterDataManagement.methodName(
    {
        parameters,
        headers: {
            'Custom-Header': '{header_value}'
        }
    }, function(err, response) {
        if (err)
            console.log('error:', err);
        else
            console.log(response);
    }
);
Copy to clipboard

Example header parameter in a request

ReturnType returnValue = masterDataManagement.methodName(parameters)
        .addHeader("Custom-Header", "{header_value}")
        .execute();
Copy to clipboard

Example header parameter in a request

response = masterDataManagement.methodName(
    parameters,
    headers = {
        'Custom-Header': '{header_value}'
    })

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

GET /mdm/v1/config_data_model/attributes

ServiceCall<ConfigDataModelAttributes> getConfiguratorConfigDataModelAttributes(GetConfiguratorConfigDataModelAttributesOptions getConfiguratorConfigDataModelAttributesOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetConfiguratorConfigDataModelAttributesOptions.Builder to create a GetConfiguratorConfigDataModelAttributesOptions object that contains the parameter values for the getConfiguratorConfigDataModelAttributes method.

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

GetConfiguratorConfigDataModelAttributesOptions

The getConfiguratorConfigDataModelAttributes options.

Get Config Data Model Record Type Attributes

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/config_data_model/attributes?type_name=person&type_category=employee&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Response

Response Body

ConfigDataModelAttributes

The Config Data Model attributes for a record type.

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

Status 200

{
  "attributes": [
    {
      "name": "record_id",
      "default_display_name": "Record identifier"
    },
    {
      "name": "record_source",
      "default_display_name": "Record source"
    }
  ]
}
Copy to clipboard

Success example

{
  "attributes": [
    {
      "name": "record_id",
      "default_display_name": "Record identifier"
    },
    {
      "name": "record_source",
      "default_display_name": "Record source"
    }
  ]
}
Copy to clipboard

Gets the data model present in configuration space.

GET /mdm/v1/config_data_model

ServiceCall<ConfigDataModel> getConfiguratorConfigDataModel(GetConfiguratorConfigDataModelOptions getConfiguratorConfigDataModelOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetConfiguratorConfigDataModelOptions.Builder to create a GetConfiguratorConfigDataModelOptions object that contains the parameter values for the getConfiguratorConfigDataModel method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Gets the data model present in the configuration space

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/config_data_model?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorConfigDataModelOptions getConfiguratorConfigDataModelOptions = new GetConfiguratorConfigDataModelOptions();

Response<ConfigDataModel> response = mdmService.getConfiguratorConfigDataModel(getConfiguratorConfigDataModelOptions).execute();
ConfigDataModel configDataModel = response.getResult();

System.out.println(configDataModel);

Response

Response Body

ConfigDataModel

Collection of record and relationship types and system properties definition

ConfigDataModel

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

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
        }
      ]
    }
  ]
}
Copy to clipboard

Replaces the config data model present in configuration space.

PUT /mdm/v1/config_data_model

ServiceCall<ConfigDataModel> replaceConfiguratorConfigDataModel(ReplaceConfiguratorConfigDataModelOptions replaceConfiguratorConfigDataModelOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceConfiguratorConfigDataModelOptions.Builder to create a ReplaceConfiguratorConfigDataModelOptions object that contains the parameter values for the replaceConfiguratorConfigDataModel method.

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:

ReplaceConfiguratorConfigDataModelOptions

The replaceConfiguratorConfigDataModel options.

Replace Config Data Model

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/config_data_model?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"locale":"en_us","system_properties":{"record_types":{"collection_id":{"label":"Collection ID","description":"Optional identifier for identifying a collection of records","data_type":"String","editable":true,"indexed":true},"record_source":{"label":"Record source","description":"A user provided record source.","data_type":"String","editable":true,"indexed":true},"record_id":{"label":"Record identifier","description":"User provided or autogenerated record identifier","data_type":"String","editable":true,"indexed":true},"record_number":{"label":"Record number","description":"System generated record number","data_type":"String","editable":false,"indexed":true},"record_last_updated":{"label":"Record last updated","description":"System generated record last updated","data_type":"Long","editable":false,"indexed":false}},"entity_types":{"entity_id":{"label":"Entity identifier","data_type":"String","editable":false,"indexed":true},"entity_last_updated":{"label":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}},"attribute_types":{"attribute_last_updated":{"label":"Attribute last updated date","description":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}},"relationship_types":{"relationship_last_updated":{"label":"Relationship last updated date","description":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}}},"record_types":{"person":{"label":"Person","description":"The record type for person records.","entity_types":{"person_entity":{"label":"Person Entity","description":"The entity type for person records."}},"attributes":{"birth_date":{"label":"Birth Date","description":"The birth date associated with this person record.","attribute_type":"string","classification":"","cardinality":"LIST","indexed":true,"matching_type":"DATE"},"gender":{"label":"Gender","description":"The gender of the the person associated with this record.","attribute_type":"string","classification":"","cardinality":"LIST","indexed":true,"matching_type":"GENDER"},"primary_residence":{"label":"Primary Residence","description":"Indicates that this address is a primary residence.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"mailing_address":{"label":"Mailing Address","description":"Indicates that this address is a mailing address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"home_telephone":{"label":"Home Telephone","description":"Indicates that this phone number is for a home telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"mobile_telephone":{"label":"Mobile Telephone","description":"Indicates that this phone number is for a mobile telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"personal_email":{"label":"Personal Email","description":"Indicates that this email address is a personal email address.","attribute_type":"email","classification":"","cardinality":"LIST","indexed":true},"twitter":{"label":"Twitter","description":"Indicates that this social media type is Twitter.","attribute_type":"social_media","classification":"","cardinality":"LIST","indexed":true},"drivers_licence":{"label":"Driver's Licence","description":"Indicates that this identifier is a driver's license.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"passport":{"label":"Passport","description":"Indicates that this identifier is a passport.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"credit_card":{"label":"Credit Card","description":"Indicates that this identifier is a credit card.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"PAYMENTCARDNUMBER"},"social_insurance_number":{"label":"Social Insurance Number","description":"Indicates that this identifier is a social insurance number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"legal_name":{"label":"Legal Name","description":"Indicates that this name is a legal name.","attribute_type":"person_name","classification":"","cardinality":"LIST","indexed":true},"previous_name":{"label":"Previous Name","description":"Indicates that this name is a previous name.","attribute_type":"person_name","classification":"","cardinality":"LIST","indexed":true}}},"organization":{"label":"Organization","description":"The record type for organization records.","entity_types":{"organization_entity":{"label":"Organization Entity","description":"The entity type for org records."}},"attributes":{"business_name":{"label":"Business Name","description":"Indicates that this name is a business name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"doing_business_as":{"label":"Doing Business As","description":"Indicates that this name is a Doing Business As name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"abbreviated_name":{"label":"Abbreviated Name","description":"Indicates that this name is an abbreviated name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"business_address":{"label":"Business Address","description":"Indicates that this address is a business address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"mailing_address":{"label":"Mailing Address","description":"Indicates that this address is a mailing address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"business_telephone":{"label":"Business Telephone","description":"Indicates that this phone number is for a business telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"business_email":{"label":"Business Email","description":"Indicates that this email address is a business email.","attribute_type":"email","classification":"","cardinality":"LIST","indexed":true},"business_tax_identification":{"label":"Business Tax Identification","description":"Indicates that this identifier is a business tax identification number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"duns":{"label":"DUNS","description":"Indicates that this identifier is a D-U-N-S Number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"}}}},"attribute_types":{"address":{"label":"Address","description":"The address locations associated with a record. Only one address per usage value is allowed. For example, there can only be one mailing address for a contact.","classification":"","matching_types":["ADDRESS"],"fields":{"residence":{"label":"Residence Value","description":"The type of residence for this address, such as home, apartment, or suite.","classification":"","indexed":true},"address_line1":{"label":"Address Line 1","description":"The first line of this address.","classification":"","indexed":true},"address_line2":{"label":"Address Line 2","description":"The second line of this address.","classification":"","indexed":true},"address_line3":{"label":"Address Line 3","description":"The third line of this address.","classification":"","indexed":true},"city":{"label":"City","description":"The city of this address.","classification":"","indexed":true},"zip_postal_code":{"label":"Postal Code","description":"The postal code of this address.","classification":"","indexed":true},"residence_number":{"label":"Residence Number","description":"The residence number of this address.","classification":"","indexed":true},"province_state":{"label":"State/Province Value","description":"The state or province of this address.","classification":"","indexed":true},"county":{"label":"County","description":"The county of this address.","classification":"","indexed":true},"country":{"label":"Country Value","description":"The country of this address.","classification":"","indexed":true},"latitude_degrees":{"label":"Latitude Degrees","description":"The latitude of this address.","classification":"","indexed":true},"longitude_degrees":{"label":"Longitude Degrees","description":"The longitude of this address.","classification":"","indexed":true}}},"telephone":{"label":"Telephone","description":"Indicates that this attribute is a telephone number. Create attributes of this type for each category of telephone number, such as mobile, home, or business.","classification":"","matching_types":["PHONE"],"fields":{"phone_number":{"label":"Phone Number","description":"A string containing the digits for this telephone number.","classification":"","indexed":true}}},"email":{"label":"Email","description":"Indicates that this attribute is an email address. Create attributes of this type for each category of email address, such as personal or business.","classification":"","matching_types":["EMAIL"],"fields":{"email_id":{"label":"Email Id","description":"A string containing the email address value.","classification":"","indexed":true}}},"social_media":{"label":"Social Media","description":"Indicates that this attribute is a social media handle or user name. Create attributes of this type for each social media platform, such as Twitter or Instagram.","classification":"","matching_types":["SOCIALMEDIA"],"fields":{"social_media_handle":{"label":"Social Media Handle","description":"A string containing the handle or user name value.","classification":"","indexed":true}}},"identification":{"label":"Identification","description":"A unique identifier that can be used to distinguish a party from others.","classification":"","matching_types":["NATIONALIDENTIFIER","PAYMENTCARDNUMBER","OTHERIDENTIFIER"],"fields":{"identification_number":{"label":"Identification Number","description":"The actual alphanumeric identifier. For example, if the identification type indicates a social security number, then this value contains the 9 characters of the social security number.","classification":"","indexed":true}}},"person_name":{"label":"Person Name","description":"Information about a name associated with a person record.","classification":"","matching_types":["PERSONNAME"],"fields":{"generation":{"label":"Generation Value","description":"Identifies familial generational information in the form of a generation type. Examples include The First, The Second, Junior or Senior.","classification":"","indexed":true},"prefix":{"label":"Prefix Value","description":"The name prefix, such as Mr, Mrs, Miss, Dr, and others.","classification":"","indexed":true},"given_name":{"label":"Given Name","description":"The first given name of a person. Commonly known as the first name.","classification":"","indexed":true},"middle_name":{"label":"Middle Name","description":"The second given name of a person. Commonly known as the middle name.","classification":"","indexed":true},"last_name":{"label":"Last Name","description":"The surname or family name of a person. Commonly known as the last name.","classification":"","indexed":true},"suffix":{"label":"suffix","description":"The name suffix, such as Jr, MD, Esq, PhD, and others.","classification":"","indexed":true},"full_name":{"label":"Full name","description":"The complete name of this person in a single string, including first, middle, and last names.","classification":"","indexed":true}}},"organization_name":{"label":"Organization Name","description":"Information about a name associated with an organization record.","classification":"","matching_types":["ORGNAME"],"fields":{"name":{"label":"name","description":"The organization name.","classification":"","indexed":true}}},"string":{"label":"Simple attribute","description":"A single field primitive attribute","classification":"","fields":{"value":{"label":"Value","description":"","classification":"","indexed":true}}}},"relationship_types":{"linkage":{"label":"Linkage","label_from_source":"Linked into","label_from_target":"Linked from","description":"This is the built in linkage relationship type the matching engine creates between records and their resolved entities","cardinality":"ONE2MANY","directional":true}}}" 
Copy to clipboard

Example request

RecordType recordTypeModel = new RecordType.Builder()
  .label("testString")
  .build();
ReplaceConfiguratorConfigDataModelOptions replaceConfiguratorConfigDataModelOptions = new ReplaceConfiguratorConfigDataModelOptions.Builder()
  .build();

Response<ConfigDataModel> response = mdmService.replaceConfiguratorConfigDataModel(replaceConfiguratorConfigDataModelOptions).execute();
ConfigDataModel configDataModel = response.getResult();

System.out.println(configDataModel);
Copy to clipboard

Response

Response Body

ConfigDataModel

Collection of record and relationship types and system properties definition

ConfigDataModel

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

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
        }
      ]
    }
  ]
}
Copy to clipboard

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 200

{
  "status": "healthy/unhealthy.",
  "severity": "info/critical.",
  "message": "Additional details of the configuration health status.",
}
Copy to clipboard

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

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:

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.

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

Status 200

{
  "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
        }
      ]
    }
  ]
}
Copy to clipboard

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:

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

Status 200

{
  "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
        }
      ]
    }
  ]
}
Copy to clipboard

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

GET /mdm/v1/match_statistics

ServiceCall<MatchStatistics> getConfiguratorMatchingStatistics(GetConfiguratorMatchingStatisticsOptions getConfiguratorMatchingStatisticsOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetConfiguratorMatchingStatisticsOptions.Builder to create a GetConfiguratorMatchingStatisticsOptions object that contains the parameter values for the getConfiguratorMatchingStatistics method.

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

GetConfiguratorMatchingStatisticsOptions

The getConfiguratorMatchingStatistics options.

Get matching statistics

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/match_statistics?record_type=person&entity_type=person_entity&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorMatchingStatisticsOptions getConfiguratorMatchingStatisticsOptions = new GetConfiguratorMatchingStatisticsOptions.Builder()
  .recordType("person")
  .entityType("person_entity")
  .build();

Response<MatchStatistics> response = mdmService.getConfiguratorMatchingStatistics(getConfiguratorMatchingStatisticsOptions).execute();
MatchStatistics matchStatistics = response.getResult();

System.out.println(matchStatistics);
Copy to clipboard

Response

Response Body

MatchStatistics

The Statistics of the match process results.

MatchStatistics

The Statistics of the match process results.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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
  }
}
Copy to clipboard

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.

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:

Response

Response Body

PairAnalysisResponse

Status Code

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

No Sample Response

This method does not specify any sample responses.

This is a internal REST call.

DELETE /mdm/v1/pair_analysis

Request

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.

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:

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.

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

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

GET /mdm/v1/configuration_metadata

ServiceCall<ConfigurationMetadata> getConfiguratorConfigurationMetadata(GetConfiguratorConfigurationMetadataOptions getConfiguratorConfigurationMetadataOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetConfiguratorConfigurationMetadataOptions.Builder to create a GetConfiguratorConfigurationMetadataOptions object that contains the parameter values for the getConfiguratorConfigurationMetadata method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Get configuration metadata

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorConfigurationMetadataOptions getConfiguratorConfigurationMetadataOptions = new GetConfiguratorConfigurationMetadataOptions();

Response<ConfigurationMetadata> response = mdmService.getConfiguratorConfigurationMetadata(getConfiguratorConfigurationMetadataOptions).execute();
ConfigurationMetadata configurationMetadata = response.getResult();

System.out.println(configurationMetadata);

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

ConfigurationMetadata

Configuration metadata details.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

PUT /mdm/v1/configuration_metadata

ServiceCall<ConfigurationMetadata> replaceConfiguratorConfigurationMetadata(ReplaceConfiguratorConfigurationMetadataOptions replaceConfiguratorConfigurationMetadataOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceConfiguratorConfigurationMetadataOptions.Builder to create a ReplaceConfiguratorConfigurationMetadataOptions object that contains the parameter values for the replaceConfiguratorConfigurationMetadata method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

ConfigurationMetadata

Configuration metadata details.

Examples:

ReplaceConfiguratorConfigurationMetadataOptions

The replaceConfiguratorConfigurationMetadata options.

Replace configuration metadata

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"collaborators":"AP","storage_type":"Cloud storage","project_id":"0e4bb17d-4871-40a5-b5a1-55b2866fe000","catalog_id":"ee1de5f6-54da-4246-95bc-7bc282151000","description":"Example project","role":"admin","name":"Project 1"}" 
Copy to clipboard

Example request

ReplaceConfiguratorConfigurationMetadataOptions replaceConfiguratorConfigurationMetadataOptions = new ReplaceConfiguratorConfigurationMetadataOptions.Builder()
  .projectId("52a72453-597c-4fb3-a518-c815225e3ea9")
  .catalogId("8a3cc967-81c4-49a3-86a2-208059819b24")
  .description("sample configuration metadata")
  .name("configuration_metadata")
  .build();

Response<ConfigurationMetadata> response = mdmService.replaceConfiguratorConfigurationMetadata(replaceConfiguratorConfigurationMetadataOptions).execute();
ConfigurationMetadata configurationMetadata = response.getResult();

System.out.println(configurationMetadata);
Copy to clipboard

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

ConfigurationMetadata

Configuration metadata details.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

PATCH /mdm/v1/configuration_metadata

ServiceCall<ConfigurationMetadata> updateConfiguratorConfigurationMetadata(UpdateConfiguratorConfigurationMetadataOptions updateConfiguratorConfigurationMetadataOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the UpdateConfiguratorConfigurationMetadataOptions.Builder to create a UpdateConfiguratorConfigurationMetadataOptions object that contains the parameter values for the updateConfiguratorConfigurationMetadata method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

ConfigurationMetadata

Configuration metadata details.

Examples:

UpdateConfiguratorConfigurationMetadataOptions

The updateConfiguratorConfigurationMetadata options.

Update configuration metadata

curl -X PATCH --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"collaborators":"AP","storage_type":"Cloud storage","project_id":"0e4bb17d-4871-40a5-b5a1-55b2866fe000","catalog_id":"ee1de5f6-54da-4246-95bc-7bc282151000","description":"Example project","role":"admin","name":"Project 1"}" 
Copy to clipboard

Example request

UpdateConfiguratorConfigurationMetadataOptions updateConfiguratorConfigurationMetadataOptions = new UpdateConfiguratorConfigurationMetadataOptions.Builder()
  .projectId("52a72453-597c-4fb3-a518-c815225e3ea9")
  .catalogId("8a3cc967-81c4-49a3-86a2-208059819b24")
  .description("sample configuration metadata")
  .name("configuration_metadata")
  .build();

Response<ConfigurationMetadata> response = mdmService.updateConfiguratorConfigurationMetadata(updateConfiguratorConfigurationMetadataOptions).execute();
ConfigurationMetadata configurationMetadata = response.getResult();

System.out.println(configurationMetadata);
Copy to clipboard

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

ConfigurationMetadata

Configuration metadata details.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

Status 200

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

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

GET /mdm/v1/configuration_metadata/processes

ServiceCall<ProcessList> listConfiguratorProcesses(ListConfiguratorProcessesOptions listConfiguratorProcessesOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListConfiguratorProcessesOptions.Builder to create a ListConfiguratorProcessesOptions object that contains the parameter values for the listConfiguratorProcesses method.

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

ListConfiguratorProcessesOptions

The listConfiguratorProcesses options.

List the process details

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/processes?status=Complete&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListConfiguratorProcessesOptions listConfiguratorProcessesOptions = new ListConfiguratorProcessesOptions.Builder()
  .status("In-progress")
  .build();

Response<ProcessList> response = mdmService.listConfiguratorProcesses(listConfiguratorProcessesOptions).execute();
ProcessList processList = response.getResult();

System.out.println(processList);

Response

Response Body

ProcessList

Response wrapper with the list of Processes.

ProcessList

Response wrapper with the list of Processes.

Status Code

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

Example responses

Status 200

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

Success example

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

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

POST /mdm/v1/configuration_metadata/processes

ServiceCall<ProcessStatus> createConfiguratorProcess(CreateConfiguratorProcessOptions createConfiguratorProcessOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CreateConfiguratorProcessOptions.Builder to create a CreateConfiguratorProcessOptions object that contains the parameter values for the createConfiguratorProcess method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

ProcessRequest

Process creation request details.

Examples:

CreateConfiguratorProcessOptions

The createConfiguratorProcess options.

Add the process details

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/processes?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"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" }" 
Copy to clipboard

Example request

ProcessRequestAssetSourceDetailsProject processRequestAssetSourceDetailsProjectModel = new ProcessRequestAssetSourceDetailsProject.Builder()
  .cosBucketName("bucket-name")
  .cosApiKey("project_api_key")
  .cosEndpoint("https://s3.us-south.cloud-object-storage.appdomain.cloud")
  .build();
ProcessRequestAssetSourceDetails processRequestAssetSourceDetailsModel = new ProcessRequestAssetSourceDetails.Builder()
  .project(processRequestAssetSourceDetailsProjectModel)
  .build();
CreateConfiguratorProcessOptions createConfiguratorProcessOptions = new CreateConfiguratorProcessOptions.Builder()
  .processName("publish_data")
  .assetSourceDetails(processRequestAssetSourceDetailsModel)
  .initiator("IAM ID")
  .build();

Response<ProcessStatus> response = mdmService.createConfiguratorProcess(createConfiguratorProcessOptions).execute();
ProcessStatus processStatus = response.getResult();

System.out.println(processStatus);
Copy to clipboard

Response

Response Body

ProcessStatus

Process Status.

ProcessStatus

Process Status.

Status Code

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

Example responses

Status 201

{
  "status": "In-Progress_bulkderive",
  "message": "Matching is in progress."
}
Copy to clipboard

Success example

{
  "status": "In-Progress_bulkderive",
  "message": "Matching is in progress."
}
Copy to clipboard

Status 201

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

Success example

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

Status 201

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

Success example

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

Status 201

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

Success example

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

Status 201

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

Success example

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

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

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

ServiceCall<AssetMetadata> replaceConfiguratorConfigurationAsset(ReplaceConfiguratorConfigurationAssetOptions replaceConfiguratorConfigurationAssetOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceConfiguratorConfigurationAssetOptions.Builder to create a ReplaceConfiguratorConfigurationAssetOptions object that contains the parameter values for the replaceConfiguratorConfigurationAsset method.

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:

ReplaceConfiguratorConfigurationAssetOptions

The replaceConfiguratorConfigurationAsset options.

Replace configuration metadata asset

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/assets/d8868c51-a96e-48ab-a4cd-0000000?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"asset_created_date":"{}","asset_mappings":[{"exclude_column":false,"auto_mapped":true,"completeness_percent":100,"data_mapping_default_display_name":"Record Source","classified_class":"GEN","data_mapping_name":"gender","key":"COLUMN 1"}],"asset_name":"Person10k.csv","asset_status":"Mapped","asset_record_type":"Person"}" 
Copy to clipboard

Example request

AssetMapping assetMappingModel = new AssetMapping.Builder()
  .completenessPercent("100")
  .dataMappingName("record_source")
  .excludeColumn(false)
  .autoMapped(false)
  .classifiedClass("X")
  .key("COLUMN1")
  .build();
ReplaceConfiguratorConfigurationAssetOptions replaceConfiguratorConfigurationAssetOptions = new ReplaceConfiguratorConfigurationAssetOptions.Builder()
  .assetId("testString")
  .assetName("Person10.csv")
  .assetStatus("Mapped")
  .assetCreatedDate("2020-05-12 13:21:21.727000+00:00")
  .assetMappings(new java.util.ArrayList<AssetMapping>(java.util.Arrays.asList(assetMappingModel)))
  .build();

Response<AssetMetadata> response = mdmService.replaceConfiguratorConfigurationAsset(replaceConfiguratorConfigurationAssetOptions).execute();
AssetMetadata assetMetadata = response.getResult();

System.out.println(assetMetadata);
Copy to clipboard

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
}
Copy to clipboard

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:

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

Status 200

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

Gets the process details for the specified process name.

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

ServiceCall<ProcessModelStatus> getConfiguratorProcess(GetConfiguratorProcessOptions getConfiguratorProcessOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetConfiguratorProcessOptions.Builder to create a GetConfiguratorProcessOptions object that contains the parameter values for the getConfiguratorProcess method.

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

GetConfiguratorProcessOptions

The getConfiguratorProcess options.

Get configurator process

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/processes/publish_model?record_type=person&entity_type=person_entity&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorProcessOptions getConfiguratorProcessOptions = new GetConfiguratorProcessOptions.Builder()
  .processName("testString")
  .recordType("person")
  .entityType("person_entity")
  .build();

Response<ProcessModelStatus> response = mdmService.getConfiguratorProcess(getConfiguratorProcessOptions).execute();
ProcessModelStatus processModelStatus = response.getResult();

System.out.println(processModelStatus);
Copy to clipboard

Response

Response Body

ProcessModelStatus

Details of the Process.

ProcessModelStatus

Details of the Process.

Status Code

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

Example responses

Status 200

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

Success example

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

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

ServiceCall<AssetMetadata> addConfiguratorConfigurationAsset(AddConfiguratorConfigurationAssetOptions addConfiguratorConfigurationAssetOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the AddConfiguratorConfigurationAssetOptions.Builder to create a AddConfiguratorConfigurationAssetOptions object that contains the parameter values for the addConfiguratorConfigurationAsset method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

AssetMetadataCreateRequest

Request details for creating new Data Asset.

Examples:

AddConfiguratorConfigurationAssetOptions

The addConfiguratorConfigurationAsset options.

Add configuration metadata asset

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/assets?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"asset_created_date":"{}","asset_mappings":[{"exclude_column":false,"auto_mapped":true,"completeness_percent":100,"data_mapping_default_display_name":"Record Source","classified_class":"GEN","data_mapping_name":"gender","key":"COLUMN 1"}],"asset_id":"d8868c51-a96e-48ab-a4cd-0000000","asset_name":"Person10k.csv","asset_status":"Mapped","asset_record_type":"Person"}" 
Copy to clipboard

Example request

AssetMapping assetMappingModel = new AssetMapping.Builder()
  .completenessPercent("100")
  .dataMappingName("record_source")
  .excludeColumn(false)
  .autoMapped(false)
  .classifiedClass("X")
  .key("COLUMN1")
  .build();
AddConfiguratorConfigurationAssetOptions addConfiguratorConfigurationAssetOptions = new AddConfiguratorConfigurationAssetOptions.Builder()
  .assetId("asset_id")
  .assetName("Person10.csv")
  .assetStatus("Mapped")
  .assetCreatedDate("2020-05-12 13:21:21.727000+00:00")
  .assetMappings(new java.util.ArrayList<AssetMapping>(java.util.Arrays.asList(assetMappingModel)))
  .build();

Response<AssetMetadata> response = mdmService.addConfiguratorConfigurationAsset(addConfiguratorConfigurationAssetOptions).execute();
AssetMetadata assetMetadata = response.getResult();

System.out.println(assetMetadata);
Copy to clipboard

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

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

Example responses

Status 201

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

Success example

{
  "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"
}
Copy to clipboard

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

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

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:

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

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:

Response

Response Body

SnapshotCompareResponse

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

Status Code

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

Example responses

Status 200

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

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

ServiceCall<SuggestedDataMapping> suggestConfiguratorDataMappings(SuggestConfiguratorDataMappingsOptions suggestConfiguratorDataMappingsOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the SuggestConfiguratorDataMappingsOptions.Builder to create a SuggestConfiguratorDataMappingsOptions object that contains the parameter values for the suggestConfiguratorDataMappings method.

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:

SuggestConfiguratorDataMappingsOptions

The suggestConfiguratorDataMappings options.

Suggest data mappings

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/suggest_data_mappings?record_type=person&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

DataMapping dataMappingModel = new DataMapping.Builder()
  .classifiedClass("X")
  .key("COLUMN1")
  .build();
SuggestConfiguratorDataMappingsOptions suggestConfiguratorDataMappingsOptions = new SuggestConfiguratorDataMappingsOptions.Builder()
  .recordType("person")
  .columns(new java.util.ArrayList<DataMapping>(java.util.Arrays.asList(dataMappingModel)))
  .build();

Response<SuggestedDataMapping> response = mdmService.suggestConfiguratorDataMappings(suggestConfiguratorDataMappingsOptions).execute();
SuggestedDataMapping suggestedDataMapping = response.getResult();

System.out.println(suggestedDataMapping);
Copy to clipboard

Response

Response Body

SuggestedDataMapping

Response wrapper with details of Suggested Data Mappings.

SuggestedDataMapping

Response wrapper with details of Suggested Data Mappings.

Status Code

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

Example responses

Status 200

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

Success example

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

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

GET /mdm/v1/suggested_matching_attributes

ServiceCall<SuggestedMatchAttributes> getConfiguratorSuggestedMatchingAttributes(GetConfiguratorSuggestedMatchingAttributesOptions getConfiguratorSuggestedMatchingAttributesOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetConfiguratorSuggestedMatchingAttributesOptions.Builder to create a GetConfiguratorSuggestedMatchingAttributesOptions object that contains the parameter values for the getConfiguratorSuggestedMatchingAttributes method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type for matching attribute suggestions

GetConfiguratorSuggestedMatchingAttributesOptions

The getConfiguratorSuggestedMatchingAttributes options.

Suggests matching attributes

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/suggested_matching_attributes?record_type=person&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorSuggestedMatchingAttributesOptions getConfiguratorSuggestedMatchingAttributesOptions = new GetConfiguratorSuggestedMatchingAttributesOptions.Builder()
  .recordType("testString")
  .build();

Response<SuggestedMatchAttributes> response = mdmService.getConfiguratorSuggestedMatchingAttributes(getConfiguratorSuggestedMatchingAttributesOptions).execute();
SuggestedMatchAttributes suggestedMatchAttributes = response.getResult();

System.out.println(suggestedMatchAttributes);

Response

Response Body

SuggestedMatchAttributes

Response wrapper for attributes suggested for running match process.

SuggestedMatchAttributes

Response wrapper for attributes suggested for running match process.

Status Code

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

Example responses

Status 200

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

Success example

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

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.

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

ServiceCall<TuningJobResponse> createWeightTuningJob(CreateWeightTuningJobOptions createWeightTuningJobOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CreateWeightTuningJobOptions.Builder to create a CreateWeightTuningJobOptions object that contains the parameter values for the createWeightTuningJob method.

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

CreateWeightTuningJobOptions

The createWeightTuningJob options.

Example request

CreateWeightTuningJobOptions createWeightTuningJobOptions = new CreateWeightTuningJobOptions.Builder()
  .recordType("person")
  .entityType("person_entity")
  .build();

Response<TuningJobResponse> response = mdmService.createWeightTuningJob(createWeightTuningJobOptions).execute();
TuningJobResponse tuningJobResponse = response.getResult();

System.out.println(tuningJobResponse);
Copy to clipboard

Response

Response Body

TuningJobResponse

Response object for asynchronous processing of a tuning job

TuningJobResponse

Response object for asynchronous processing of a tuning job.

Status Code

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

Example responses

Status 201

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

Success example

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

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.

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

GET /mdm/job/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.

GET /mdm/v1/job_health

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
target
string
a target of the health check, ie. fdb

Default: all

Response

Response Body

HealthMonitorResponse

Status Code

200
The health check was successfully performed and the service considered live and healthy.
400
Wrong health monitor target option
500
Problem getting health monitor status. An internal error occurred while attempting to determine the health monitor status.

No Sample Response

This method does not specify any sample responses.

Requires the application role of 'JobWriter'.

POST /mdm/v1/job_runs/{job_run_id}/cancel

Request

Path Parameters

job_run_id
Required*
string
The id of the job run.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Status Code

204
The job run was cancelled successfully.
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 run information. Job run not found.
500
An internal server error occurred.

No Sample Response

This method does not specify any sample responses.

Requires the application role of 'JobReader'.

GET /mdm/v1/job_runs

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
job_name
string
The name of the job.
status
string
The status of the job run.
offset
integer
The offset from the start of the list.

Default: 0
limit
integer
The chunk size (default '50') of the requested sublist.

Default: 50

Response

Response Body

JobRunListResponse

Status Code

200
The job runs were retrieved successfully.
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. Status used for filter is invalid.
500
An internal server error occurred.

No Sample Response

This method does not specify any sample responses.

Requires the application role of 'Service'.

POST /mdm/v1/job_runs

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

JobRunRequest

Response

Response Body

JobRunResponseDetail

Status Code

201
The job run was started successfully.
400
Problem processing request. Invalid or missing input.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
An internal server error occurred.

No Sample Response

This method does not specify any sample responses.

Requires the application role of 'JobReader'.

GET /mdm/v1/job_runs/{job_run_id}

Request

Path Parameters

job_run_id
Required*
string
The id of the job run.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

JobRunResponseDetail

Status Code

200
The job run information was retrieved 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 run not found.
500
An internal server error occurred.

No Sample Response

This method does not specify any sample responses.

Requires the application role of 'Service'. Only the status can be updated using this endpoint.

PATCH /mdm/v1/job_runs/{job_run_id}

Request

Path Parameters

job_run_id
Required*
string
The id of the job run.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

JobRunUpdateRequest

Response

Response Body

JobRunResponseDetail

Status Code

200
The job run was updated successfully.
400
Problem processing request. Status used is invalid.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Job run not found.
500
An internal server error occurred.

No Sample Response

This method does not specify any sample responses.

Requires the application role of 'JobReader'.

GET /mdm/v1/job_runs/import_all_jobs

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.

Requires the application role of 'JobReader'.

GET /mdm/v1/job_runs/export_all_jobs

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.

Requires the application role of 'JobReader'.

GET /mdm/v1/job_runs/statistics

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

JobStatsResponse

Status Code

200
The job run stats were retrieved successfully.
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. Status used for filter is invalid.
500
An internal server error occurred.

No Sample Response

This method does not specify any sample responses.

Requires the application role of 'Service'.

POST /mdm/v1/job_runs/restore

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

JobRunResponseDetail

Status Code

200
The job run was started successfully.
204
The job queue is empty.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
An internal server error occurred.

No Sample Response

This method does not specify any sample responses.

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.

There are four options for a delete:

Delete by search, which removes all records matching a search criteria.
Delete by source, which removes all records of a specified record source.
Delete by asset, which removes all records loaded from a particular asset or list of assets.
Full delete, which removes all records from the graph.

POST /mdm/v1/bulk_delete

ServiceCall<BulkDeleteJob> runDataBulkDelete(RunDataBulkDeleteOptions runDataBulkDeleteOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the RunDataBulkDeleteOptions.Builder to create a RunDataBulkDeleteOptions object that contains the parameter values for the runDataBulkDelete method.

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.

RunDataBulkDeleteOptions

The runDataBulkDelete options.

Start an operation to bulk delete data from the graph

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_delete?crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"delete_type":"full"}" 
Copy to clipboard

Example request

RunDataBulkDeleteOptions runDataBulkDeleteOptions = new RunDataBulkDeleteOptions.Builder()
  .deleteType("asset")
  .build();

Response<BulkDeleteJob> response = mdmService.runDataBulkDelete(runDataBulkDeleteOptions).execute();
BulkDeleteJob bulkDeleteJob = response.getResult();

System.out.println(bulkDeleteJob);

Response

Response Body

BulkDeleteJob

Information about a bulk delete job.

BulkDeleteJob

Information about a bulk delete job.

Status Code

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

Example responses

Status 202

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

Success example

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

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.

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 data files] relationship
--[relationship data files]

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

POST /mdm/v1/bulk_load

ServiceCall<BulkLoadJob> runDataBulkLoad(RunDataBulkLoadOptions runDataBulkLoadOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the RunDataBulkLoadOptions.Builder to create a RunDataBulkLoadOptions object that contains the parameter values for the runDataBulkLoad method.

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.

RunDataBulkLoadOptions

The runDataBulkLoad options.

Start a bulk load of data into the graph

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_load?crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"data_source":{"directory_path":"34dcd76c-f083-4186-8e0f-5a6a43bf481f/","type":"dfs"},"data_structure":{"record_path":"person/record/person-100.csv","record_properties":"person/record.properties"}}" 
Copy to clipboard

Example request

DataLoadSource dataLoadSourceModel = new DataLoadSource.Builder()
  .type("dfs")
  .build();
RunDataBulkLoadOptions runDataBulkLoadOptions = new RunDataBulkLoadOptions.Builder()
  .dataSource(dataLoadSourceModel)
  .build();

Response<BulkLoadJob> response = mdmService.runDataBulkLoad(runDataBulkLoadOptions).execute();
BulkLoadJob bulkLoadJob = response.getResult();

System.out.println(bulkLoadJob);
Copy to clipboard

Response

Response Body

BulkLoadJob

Information about a bulk load job.

BulkLoadJob

Information about a bulk load job.

Status Code

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

Example responses

Status 202

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

Success example

{
  "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"
}
Copy to clipboard

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.

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

The operation runs as follows:

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

POST /mdm/v1/ongoing_sync

ServiceCall<Void> runDataOngoingSync(RunDataOngoingSyncOptions runDataOngoingSyncOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the RunDataOngoingSyncOptions.Builder to create a RunDataOngoingSyncOptions object that contains the parameter values for the runDataOngoingSync method.

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.

RunDataOngoingSyncOptions

The runDataOngoingSync options.

Example request

RunDataOngoingSyncOptions runDataOngoingSyncOptions = new RunDataOngoingSyncOptions.Builder()
  .build();

Response<Void> response = mdmService.runDataOngoingSync(runDataOngoingSyncOptions).execute();

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

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:

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

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

Example responses

Status 200

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

View a list of member records that form the entity.

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

ServiceCall<DataRecordsResponse> listDataRecordsForEntity(ListDataRecordsForEntityOptions listDataRecordsForEntityOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataRecordsForEntityOptions.Builder to create a ListDataRecordsForEntityOptions object that contains the parameter values for the listDataRecordsForEntity method.

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

ListDataRecordsForEntityOptions

The listDataRecordsForEntity options.

List the records linked into an entity

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entities/12345/records?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&include=legal_name.given_name&exclude=legal_name.last_name" 
Copy to clipboard

Example request

ListDataRecordsForEntityOptions listDataRecordsForEntityOptions = new ListDataRecordsForEntityOptions.Builder()
  .id("testString")
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<DataRecordsResponse> response = mdmService.listDataRecordsForEntity(listDataRecordsForEntityOptions).execute();
DataRecordsResponse dataRecordsResponse = response.getResult();

System.out.println(dataRecordsResponse);
Copy to clipboard

Response

Response Body

DataRecordsResponse

Paged information about a collection of records.

DataRecordsResponse

Paged information about a collection of records.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

GET /mdm/v1/entities/{id}

ServiceCall<DataEntityResponse> getDataEntity(GetDataEntityOptions getDataEntityOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataEntityOptions.Builder to create a GetDataEntityOptions object that contains the parameter values for the getDataEntity method.

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

GetDataEntityOptions

The getDataEntity options.

Get the composite view for an entity

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entities/12345?include=legal_name.given_name&exclude=legal_name.last_name&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetDataEntityOptions getDataEntityOptions = new GetDataEntityOptions.Builder()
  .id("testString")
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<DataEntityResponse> response = mdmService.getDataEntity(getDataEntityOptions).execute();
DataEntityResponse dataEntityResponse = response.getResult();

System.out.println(dataEntityResponse);
Copy to clipboard

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
  }
}
Copy to clipboard

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:

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

Status 200

{
  "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"
  }
}
Copy to clipboard

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

ServiceCall<DataRelationshipsResponse> listDataRelationshipsForEntity(ListDataRelationshipsForEntityOptions listDataRelationshipsForEntityOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataRelationshipsForEntityOptions.Builder to create a ListDataRelationshipsForEntityOptions object that contains the parameter values for the listDataRelationshipsForEntity method.

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

ListDataRelationshipsForEntityOptions

The listDataRelationshipsForEntity options.

Example request

ListDataRelationshipsForEntityOptions listDataRelationshipsForEntityOptions = new ListDataRelationshipsForEntityOptions.Builder()
  .id("testString")
  .build();

Response<DataRelationshipsResponse> response = mdmService.listDataRelationshipsForEntity(listDataRelationshipsForEntityOptions).execute();
DataRelationshipsResponse dataRelationshipsResponse = response.getResult();

System.out.println(dataRelationshipsResponse);

Response

Response Body

DataRelationshipsResponse

Paged information about a collection of relationships.

DataRelationshipsResponse

Paged information about a collection of relationships.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

ServiceCall<RelatedRecords> listDataRelatedRecordsForEntity(ListDataRelatedRecordsForEntityOptions listDataRelatedRecordsForEntityOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataRelatedRecordsForEntityOptions.Builder to create a ListDataRelatedRecordsForEntityOptions object that contains the parameter values for the listDataRelatedRecordsForEntity method.

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

ListDataRelatedRecordsForEntityOptions

The listDataRelatedRecordsForEntity options.

List the records associated with entity records

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entities/12345/related_records?relationship_type=party_relationship&record_type=person&limit=10&offset=0&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListDataRelatedRecordsForEntityOptions listDataRelatedRecordsForEntityOptions = new ListDataRelatedRecordsForEntityOptions.Builder()
  .id("testString")
  .recordType("testString")
  .relationshipType("testString")
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<RelatedRecords> response = mdmService.listDataRelatedRecordsForEntity(listDataRelatedRecordsForEntityOptions).execute();
RelatedRecords relatedRecords = response.getResult();

System.out.println(relatedRecords);
Copy to clipboard

Response Body

RelatedRecords

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

RelatedRecords

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

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

GET /mdm/v1/data_exports

ServiceCall<DataExports> listDataExports(ListDataExportsOptions listDataExportsOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataExportsOptions.Builder to create a ListDataExportsOptions object that contains the parameter values for the listDataExports method.

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

ListDataExportsOptions

The listDataExports options.

List the export jobs

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/data_exports?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListDataExportsOptions listDataExportsOptions = new ListDataExportsOptions.Builder()
  .build();

Response<DataExports> response = mdmService.listDataExports(listDataExportsOptions).execute();
DataExports dataExports = response.getResult();

System.out.println(dataExports);

Response

Response Body

DataExports

Paged information about a collection of exports.

DataExports

Paged information about a collection of exports.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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
}
Copy to clipboard

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.

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

The operation runs as follows:

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

POST /mdm/v1/data_exports

ServiceCall<DataExport> createDataExport(CreateDataExportOptions createDataExportOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CreateDataExportOptions.Builder to create a CreateDataExportOptions object that contains the parameter values for the createDataExport method.

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.

CreateDataExportOptions

The createDataExport options.

Start an export of search results

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/data_exports?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::"  --data "{ "export_type": "entity", "format": "csv", "file_name":"records", "search_criteria": { "search_type": "record", "query": { "operation": "and", "expressions": [ { "value": "JOHN" } ] } } }" 
Copy to clipboard

Example request

DataSearchCriteria dataSearchCriteriaModel = new DataSearchCriteria.Builder()
  .build();
CreateDataExportOptions createDataExportOptions = new CreateDataExportOptions.Builder()
  .exportType("record")
  .format("csv")
  .searchCriteria(dataSearchCriteriaModel)
  .build();

Response<DataExport> response = mdmService.createDataExport(createDataExportOptions).execute();
DataExport dataExport = response.getResult();

System.out.println(dataExport);
Copy to clipboard

Response

Response Body

DataExport

Information about an export.

DataExport

Information about an export.

Status Code

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

Example responses

Status 202

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

Success example

{
  "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"
        ]
      }
    ]
  }
}
Copy to clipboard

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

ServiceCall<InputStream> getDataExportDownload(GetDataExportDownloadOptions getDataExportDownloadOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataExportDownloadOptions.Builder to create a GetDataExportDownloadOptions object that contains the parameter values for the getDataExportDownload method.

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.

GetDataExportDownloadOptions

The getDataExportDownload options.

Download an export file

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/data_exports/24403560707830722/download?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetDataExportDownloadOptions getDataExportDownloadOptions = new GetDataExportDownloadOptions.Builder()
  .exportId("testString")
  .build();

Response<InputStream> response = mdmService.getDataExportDownload(getDataExportDownloadOptions).execute();
InputStream inputStream = response.getResult();

System.out.println(inputStream);

Response

Response type: InputStream

Response Body

binary

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

ServiceCall<DataExport> getDataExport(GetDataExportOptions getDataExportOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataExportOptions.Builder to create a GetDataExportOptions object that contains the parameter values for the getDataExport method.

Path Parameters

export_id
Required*
string
The ID of the export.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

GetDataExportOptions

The getDataExport options.

Get information for an export

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/data_exports/24403560707830722?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetDataExportOptions getDataExportOptions = new GetDataExportOptions.Builder()
  .exportId("testString")
  .build();

Response<DataExport> response = mdmService.getDataExport(getDataExportOptions).execute();
DataExport dataExport = response.getResult();

System.out.println(dataExport);

Response

Response Body

DataExport

Information about an export.

DataExport

Information about an export.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
  }
}
Copy to clipboard

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

Status 200

[
{ "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"
] 
Copy to clipboard

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

Status 200

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

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:

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

Status 200

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

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

Status 200

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

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

Status 200

{
  "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"
            }
          }
        ]
      }
    }
  ]
}
Copy to clipboard

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

Status 200

{
  "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"
  }
}
Copy to clipboard

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

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

Status 200

{
  "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"
  }
}
Copy to clipboard

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.

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:

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

Status 200

{
  "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"
    }
  }
}
Copy to clipboard

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

Status 200

{
  "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"
}
Copy to clipboard

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

Status 200

{    "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"    }
Copy to clipboard

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

Status 200

{
  "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"
  }
}
Copy to clipboard

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:

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

Status 201

{
  "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"
  }
}
Copy to clipboard

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.

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

Status 200

{
  "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
          }
        }
      ]
    }
  }
}
Copy to clipboard

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

ServiceCall<DataJobs> listDataJobs(ListDataJobsOptions listDataJobsOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataJobsOptions.Builder to create a ListDataJobsOptions object that contains the parameter values for the listDataJobs method.

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]

ListDataJobsOptions

The listDataJobs options.

List the jobs

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "/mdm/v1/data_jobs?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&status=running&type=bulk_load" 
Copy to clipboard

Example request

ListDataJobsOptions listDataJobsOptions = new ListDataJobsOptions.Builder()
  .build();

Response<DataJobs> response = mdmService.listDataJobs(listDataJobsOptions).execute();
DataJobs dataJobs = response.getResult();

System.out.println(dataJobs);

Response

Response Body

DataJobs

Paged information about a collection of jobs.

DataJobs

Paged information about a collection of jobs.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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
}
Copy to clipboard

View information about the specified job.

GET /mdm/v1/data_jobs/{job_id}

ServiceCall<DataJob> getDataJob(GetDataJobOptions getDataJobOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataJobOptions.Builder to create a GetDataJobOptions object that contains the parameter values for the getDataJob method.

Path Parameters

job_id
Required*
string
The ID of the job.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

GetDataJobOptions

The getDataJob options.

Get information for a job

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "/mdm/v1/data_jobs/24403560707830722?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetDataJobOptions getDataJobOptions = new GetDataJobOptions.Builder()
  .jobId("testString")
  .build();

Response<DataJob> response = mdmService.getDataJob(getDataJobOptions).execute();
DataJob dataJob = response.getResult();

System.out.println(dataJob);

Response

Response Body

DataJob

Information about a job.

DataJob

Information about a job.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
}
Copy to clipboard

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

ServiceCall<DataJob> stopDataJob(StopDataJobOptions stopDataJobOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the StopDataJobOptions.Builder to create a StopDataJobOptions object that contains the parameter values for the stopDataJob method.

Path Parameters

job_id
Required*
string
The ID of the job.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

StopDataJobOptions

The stopDataJob options.

Stop a given job

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "/mdm/v1/data_jobs/24403560707830722/stop?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

StopDataJobOptions stopDataJobOptions = new StopDataJobOptions.Builder()
  .jobId("testString")
  .build();

Response<DataJob> response = mdmService.stopDataJob(stopDataJobOptions).execute();
DataJob dataJob = response.getResult();

System.out.println(dataJob);

Response

Response Body

DataJob

Information about a job.

DataJob

Information about a job.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
}
Copy to clipboard

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

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

ServiceCall<Void> cleanUpDataJob(CleanUpDataJobOptions cleanUpDataJobOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CleanUpDataJobOptions.Builder to create a CleanUpDataJobOptions object that contains the parameter values for the cleanUpDataJob method.

Path Parameters

job_id
Required*
string
The ID of the job.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

CleanUpDataJobOptions

The cleanUpDataJob options.

Clean up job data

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "/mdm/v1/data_jobs/24403560707830722/clean_up?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

CleanUpDataJobOptions cleanUpDataJobOptions = new CleanUpDataJobOptions.Builder()
  .jobId("testString")
  .build();

Response<Void> response = mdmService.cleanUpDataJob(cleanUpDataJobOptions).execute();

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.

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:

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

Status 200

{
  "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
}
Copy to clipboard

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

ServiceCall<RelatedRecords> listDataRelatedRecordsForRecord(ListDataRelatedRecordsForRecordOptions listDataRelatedRecordsForRecordOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataRelatedRecordsForRecordOptions.Builder to create a ListDataRelatedRecordsForRecordOptions object that contains the parameter values for the listDataRelatedRecordsForRecord method.

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

ListDataRelatedRecordsForRecordOptions

The listDataRelatedRecordsForRecord options.

List the related records for a record

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records/249992/related_records?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&offset=0&limit=10" 
Copy to clipboard

Example request

ListDataRelatedRecordsForRecordOptions listDataRelatedRecordsForRecordOptions = new ListDataRelatedRecordsForRecordOptions.Builder()
  .id(Long.valueOf("26"))
  .build();

Response<RelatedRecords> response = mdmService.listDataRelatedRecordsForRecord(listDataRelatedRecordsForRecordOptions).execute();
RelatedRecords relatedRecords = response.getResult();

System.out.println(relatedRecords);

Response Body

RelatedRecords

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

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

View a list of entities which the record contributes to.

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

ServiceCall<DataEntitiesResponse> listDataEntitiesForRecord(ListDataEntitiesForRecordOptions listDataEntitiesForRecordOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataEntitiesForRecordOptions.Builder to create a ListDataEntitiesForRecordOptions object that contains the parameter values for the listDataEntitiesForRecord method.

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

ListDataEntitiesForRecordOptions

The listDataEntitiesForRecord options.

List the entities for a record

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records/53496/entities?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListDataEntitiesForRecordOptions listDataEntitiesForRecordOptions = new ListDataEntitiesForRecordOptions.Builder()
  .id(Long.valueOf("26"))
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<DataEntitiesResponse> response = mdmService.listDataEntitiesForRecord(listDataEntitiesForRecordOptions).execute();
DataEntitiesResponse dataEntitiesResponse = response.getResult();

System.out.println(dataEntitiesResponse);
Copy to clipboard

Response

Response Body

DataEntitiesResponse

Paged information about a collection of entities.

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

Status 200

{
  "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"
      }
    }
  ]
}
Copy to clipboard

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

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

ServiceCall<DataRelationshipsResponse> listDataRelationshipsForRecord(ListDataRelationshipsForRecordOptions listDataRelationshipsForRecordOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataRelationshipsForRecordOptions.Builder to create a ListDataRelationshipsForRecordOptions object that contains the parameter values for the listDataRelationshipsForRecord method.

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

ListDataRelationshipsForRecordOptions

The listDataRelationshipsForRecord options.

List the relationships for a record

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records/40964176/relationships?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListDataRelationshipsForRecordOptions listDataRelationshipsForRecordOptions = new ListDataRelationshipsForRecordOptions.Builder()
  .id(Long.valueOf("26"))
  .build();

Response<DataRelationshipsResponse> response = mdmService.listDataRelationshipsForRecord(listDataRelationshipsForRecordOptions).execute();
DataRelationshipsResponse dataRelationshipsResponse = response.getResult();

System.out.println(dataRelationshipsResponse);

Response

Response Body

DataRelationshipsResponse

Paged information about a collection of relationships.

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

View information about the specified record on the graph.

GET /mdm/v1/records/{id}

ServiceCall<DataRecordResponse> getDataRecord(GetDataRecordOptions getDataRecordOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataRecordOptions.Builder to create a GetDataRecordOptions object that contains the parameter values for the getDataRecord method.

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

GetDataRecordOptions

The getDataRecord options.

Get a record

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records/40964176?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetDataRecordOptions getDataRecordOptions = new GetDataRecordOptions.Builder()
  .id(Long.valueOf("26"))
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<DataRecordResponse> response = mdmService.getDataRecord(getDataRecordOptions).execute();
DataRecordResponse dataRecordResponse = response.getResult();

System.out.println(dataRecordResponse);
Copy to clipboard

Response

Response Body

DataRecordResponse

Information about a record.

DataRecordResponse

Information about a record.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
  }
}
Copy to clipboard

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}

ServiceCall<DataRecordResponse> replaceDataRecord(ReplaceDataRecordOptions replaceDataRecordOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceDataRecordOptions.Builder to create a ReplaceDataRecordOptions object that contains the parameter values for the replaceDataRecord method.

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:

ReplaceDataRecordOptions

The replaceDataRecord options.

Example request

ReplaceDataRecordOptions replaceDataRecordOptions = new ReplaceDataRecordOptions.Builder()
  .id(Long.valueOf("26"))
  .newAttributes(new java.util.HashMap<String, Object>() { { put("foo", TestUtilities.createMockMap()); } })
  .newTypeName("testString")
  .build();

Response<DataRecordResponse> response = mdmService.replaceDataRecord(replaceDataRecordOptions).execute();
DataRecordResponse dataRecordResponse = response.getResult();

System.out.println(dataRecordResponse);
Copy to clipboard

Response

Response Body

DataRecordResponse

Information about a record.

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

Status 200

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

Success example

{
  "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"
  }
}
Copy to clipboard

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}

ServiceCall<Void> deleteDataRecord(DeleteDataRecordOptions deleteDataRecordOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the DeleteDataRecordOptions.Builder to create a DeleteDataRecordOptions object that contains the parameter values for the deleteDataRecord method.

Path Parameters

id
Required*
int64
The ID of the record.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

DeleteDataRecordOptions

The deleteDataRecord options.

Delete a record

curl -X DELETE --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records/40964176?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

DeleteDataRecordOptions deleteDataRecordOptions = new DeleteDataRecordOptions.Builder()
  .id(Long.valueOf("26"))
  .build();

Response<Void> response = mdmService.deleteDataRecord(deleteDataRecordOptions).execute();

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 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:

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

Status 200

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

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

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

GET /mdm/v1/records

ServiceCall<DataRecordsResponse> listDataRecords(ListDataRecordsOptions listDataRecordsOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListDataRecordsOptions.Builder to create a ListDataRecordsOptions object that contains the parameter values for the listDataRecords method.

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:

ListDataRecordsOptions

The listDataRecords options.

List the records

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListDataRecordsOptions listDataRecordsOptions = new ListDataRecordsOptions.Builder()
  .build();

Response<DataRecordsResponse> response = mdmService.listDataRecords(listDataRecordsOptions).execute();
DataRecordsResponse dataRecordsResponse = response.getResult();

System.out.println(dataRecordsResponse);

Response

Response Body

DataRecordsResponse

Paged information about a collection of records.

DataRecordsResponse

Paged information about a collection of records.

Status Code

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

Example responses

Status 200

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

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

ServiceCall<DataRecordResponse> createDataRecord(CreateDataRecordOptions createDataRecordOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CreateDataRecordOptions.Builder to create a CreateDataRecordOptions object that contains the parameter values for the createDataRecord method.

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:

CreateDataRecordOptions

The createDataRecord options.

Create a new record

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"attributes":{"record_id":"12345","record_source":"MDM","legal_name":{"given_name":"Jane","last_name":"Smith"}},"type_name":"person"}" 
Copy to clipboard

Example request

CreateDataRecordOptions createDataRecordOptions = new CreateDataRecordOptions.Builder()
  .attributes(new java.util.HashMap<String, Object>() { { put("foo", TestUtilities.createMockMap()); } })
  .typeName("testString")
  .build();

Response<DataRecordResponse> response = mdmService.createDataRecord(createDataRecordOptions).execute();
DataRecordResponse dataRecordResponse = response.getResult();

System.out.println(dataRecordResponse);
Copy to clipboard

Response

Response Body

DataRecordResponse

Information about a record.

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

Status 201

{
  "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"
  }
}
Copy to clipboard

Success example

{
  "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"
  }
}
Copy to clipboard

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

Status 200

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

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

GET /mdm/v1/records/{id}/relationships/{relationship_id}

ServiceCall<DataRelationshipResponse> getDataRelationshipForRecord(GetDataRelationshipForRecordOptions getDataRelationshipForRecordOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataRelationshipForRecordOptions.Builder to create a GetDataRelationshipForRecordOptions object that contains the parameter values for the getDataRelationshipForRecord method.

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

GetDataRelationshipForRecordOptions

The getDataRelationshipForRecord options.

Get a relationship for a record

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records/40964176/relationships/215tzl-5cw8-q7f9-oi7u8?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetDataRelationshipForRecordOptions getDataRelationshipForRecordOptions = new GetDataRelationshipForRecordOptions.Builder()
  .id(Long.valueOf("26"))
  .relationshipId("testString")
  .build();

Response<DataRelationshipResponse> response = mdmService.getDataRelationshipForRecord(getDataRelationshipForRecordOptions).execute();
DataRelationshipResponse dataRelationshipResponse = response.getResult();

System.out.println(dataRelationshipResponse);
Copy to clipboard

Response

Response Body

DataRelationshipResponse

Information about a relationship.

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

Status 200

{
  "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"
  }
}
Copy to clipboard

Success example

{
  "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"
  }
}
Copy to clipboard

Add a new relationship to the graph.

POST /mdm/v1/relationships

ServiceCall<DataRelationshipResponse> createDataRelationship(CreateDataRelationshipOptions createDataRelationshipOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CreateDataRelationshipOptions.Builder to create a CreateDataRelationshipOptions object that contains the parameter values for the createDataRelationship method.

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:

CreateDataRelationshipOptions

The createDataRelationship options.

Example request

CreateDataRelationshipOptions createDataRelationshipOptions = new CreateDataRelationshipOptions.Builder()
  .attributes(new java.util.HashMap<String, Object>() { { put("foo", TestUtilities.createMockMap()); } })
  .typeName("testString")
  .build();

Response<DataRelationshipResponse> response = mdmService.createDataRelationship(createDataRelationshipOptions).execute();
DataRelationshipResponse dataRelationshipResponse = response.getResult();

System.out.println(dataRelationshipResponse);
Copy to clipboard

Response

Response Body

DataRelationshipResponse

Information about a relationship.

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

Status 201

{
  "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"
  }
}
Copy to clipboard

Success example

{
  "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"
  }
}
Copy to clipboard

View information about the specified relationship on the graph.

GET /mdm/v1/relationships/{id}

ServiceCall<DataRelationshipResponse> getDataRelationship(GetDataRelationshipOptions getDataRelationshipOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataRelationshipOptions.Builder to create a GetDataRelationshipOptions object that contains the parameter values for the getDataRelationship method.

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

GetDataRelationshipOptions

The getDataRelationship options.

Example request

GetDataRelationshipOptions getDataRelationshipOptions = new GetDataRelationshipOptions.Builder()
  .id("testString")
  .build();

Response<DataRelationshipResponse> response = mdmService.getDataRelationship(getDataRelationshipOptions).execute();
DataRelationshipResponse dataRelationshipResponse = response.getResult();

System.out.println(dataRelationshipResponse);

Response

Response Body

DataRelationshipResponse

Information about a relationship.

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

Status 200

{
  "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"
  }
}
Copy to clipboard

Success example

{
  "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"
  }
}
Copy to clipboard

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

PUT /mdm/v1/relationships/{id}

ServiceCall<DataRelationshipResponse> replaceDataRelationship(ReplaceDataRelationshipOptions replaceDataRelationshipOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceDataRelationshipOptions.Builder to create a ReplaceDataRelationshipOptions object that contains the parameter values for the replaceDataRelationship method.

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:

ReplaceDataRelationshipOptions

The replaceDataRelationship options.

Example request

ReplaceDataRelationshipOptions replaceDataRelationshipOptions = new ReplaceDataRelationshipOptions.Builder()
  .id("testString")
  .newAttributes(new java.util.HashMap<String, Object>() { { put("foo", TestUtilities.createMockMap()); } })
  .newTypeName("testString")
  .build();

Response<DataRelationshipResponse> response = mdmService.replaceDataRelationship(replaceDataRelationshipOptions).execute();
DataRelationshipResponse dataRelationshipResponse = response.getResult();

System.out.println(dataRelationshipResponse);
Copy to clipboard

Response

Response Body

DataRelationshipResponse

Information about a relationship.

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

Status 200

{
  "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"
  }
}
Copy to clipboard

Success example

{
  "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"
  }
}
Copy to clipboard

Delete an existing relationship from the graph.

DELETE /mdm/v1/relationships/{id}

ServiceCall<Void> deleteDataRelationship(DeleteDataRelationshipOptions deleteDataRelationshipOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the DeleteDataRelationshipOptions.Builder to create a DeleteDataRelationshipOptions object that contains the parameter values for the deleteDataRelationship method.

Path Parameters

id
Required*
string
The ID of the relationship.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

DeleteDataRelationshipOptions

The deleteDataRelationship options.

Example request

DeleteDataRelationshipOptions deleteDataRelationshipOptions = new DeleteDataRelationshipOptions.Builder()
  .id("testString")
  .build();

Response<Void> response = mdmService.deleteDataRelationship(deleteDataRelationshipOptions).execute();

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

ServiceCall<Void> runDataSchemaUpdate(RunDataSchemaUpdateOptions runDataSchemaUpdateOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the RunDataSchemaUpdateOptions.Builder to create a RunDataSchemaUpdateOptions object that contains the parameter values for the runDataSchemaUpdate method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Update the graph schema

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/schema_update?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

RunDataSchemaUpdateOptions runDataSchemaUpdateOptions = new RunDataSchemaUpdateOptions();

Response<Void> response = mdmService.runDataSchemaUpdate(runDataSchemaUpdateOptions).execute();

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.

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

ServiceCall<DataSearchResults> searchData(SearchDataOptions searchDataOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the SearchDataOptions.Builder to create a SearchDataOptions object that contains the parameter values for the searchData method.

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:

SearchDataOptions

The searchData options.

Search the data on the graph

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/search?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"search_type":"record","query":{"operation":"or","expressions":[{"value":"TX"},{"property":"legal_name.given_name","value":"John"}]},"filters":[{"type":"record","values":["person"]}]}" 
Copy to clipboard

Example request

Expression expressionModel = new Expression.Builder()
  .property("legal_name.last_name")
  .condition("equal")
  .value("smith")
  .build();
SearchQuery searchQueryModel = new SearchQuery.Builder()
  .expressions(new java.util.ArrayList<Expression>(java.util.Arrays.asList(expressionModel)))
  .build();
SearchDataOptions searchDataOptions = new SearchDataOptions.Builder()
  .searchType("record")
  .query(searchQueryModel)
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<DataSearchResults> response = mdmService.searchData(searchDataOptions).execute();
DataSearchResults dataSearchResults = response.getResult();

System.out.println(dataSearchResults);
Copy to clipboard

Response

Response Body

DataSearchResults

Results of a search operation.

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

Status 200

{
  "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
}
Copy to clipboard

Success example

{
  "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
}
Copy to clipboard

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

Status 200

{
  "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"
          ]
        }
      ]
    }
  }
}
Copy to clipboard

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:

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

Status 200

{
  "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"
          ]
        }
      ]
    }
  }
}
Copy to clipboard

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

Status 200

{
  "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"
          ]
        }
      ]
    }
  }
}
Copy to clipboard

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:

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

Status 200

{
  "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"
          ]
        }
      ]
    }
  }
}
Copy to clipboard

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

Status 200

[
  {
    "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"
            ]
          }
        ]
      }
    }
  }
]
Copy to clipboard

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

GET /mdm/v1/statistics

ServiceCall<DataStatistics> getDataGraphStatistics(GetDataGraphStatisticsOptions getDataGraphStatisticsOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataGraphStatisticsOptions.Builder to create a GetDataGraphStatisticsOptions object that contains the parameter values for the getDataGraphStatistics method.

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

Get graph statistics

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/statistics?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetDataGraphStatisticsOptions getDataGraphStatisticsOptions = new GetDataGraphStatisticsOptions();

Response<DataStatistics> response = mdmService.getDataGraphStatistics(getDataGraphStatisticsOptions).execute();
DataStatistics dataStatistics = response.getResult();

System.out.println(dataStatistics);

Response

Response Body

DataStatistics

A collection of statistics for the graph.

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

Status 200

{
  "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
}
Copy to clipboard

Success example

{
  "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
}
Copy to clipboard

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.

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

ServiceCall<Subgraph> getDataSubgraph(GetDataSubgraphOptions getDataSubgraphOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetDataSubgraphOptions.Builder to create a GetDataSubgraphOptions object that contains the parameter values for the getDataSubgraph method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

SubgraphParameters

Valid object defining scope parameters for the subgraph.

GetDataSubgraphOptions

The getDataSubgraph options.

Get the surrounding vertices and edges for a set of vertices

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/subgraph?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{ "distance": 1, "vertex_ids": [ "151592" ] }" 
Copy to clipboard

Example request

GetDataSubgraphOptions getDataSubgraphOptions = new GetDataSubgraphOptions.Builder()
  .vertexIds(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .build();

Response<Subgraph> response = mdmService.getDataSubgraph(getDataSubgraphOptions).execute();
Subgraph subgraph = response.getResult();

System.out.println(subgraph);
Copy to clipboard

Response

Response Body

Subgraph

A graph view representing a scoped subset of the graph.

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

Success example

{
  "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"
    }
  ]
}
Copy to clipboard

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

Status 200

{  "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"        }]      }  ]}
Copy to clipboard

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

Status 200

{         "id": "123441",         "type": "potential_overlay",         "last_updated_date": ",         "last_updated_user": ",         "entities": [{             "type": "record",             "type_name": "person",             "id": "2413sd53",             "number": "122441"        }]}
Copy to clipboard

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 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:

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 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:

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.

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

Status 200

{
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}
Copy to clipboard

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

Status 200

{
  "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": {}
  }
}
Copy to clipboard

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.

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

ServiceCall<PostCloudJob> createMatchingMatchJob(CreateMatchingMatchJobOptions createMatchingMatchJobOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CreateMatchingMatchJobOptions.Builder to create a CreateMatchingMatchJobOptions object that contains the parameter values for the createMatchingMatchJob method.

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>

CreateMatchingMatchJobOptions

The createMatchingMatchJob options.

Initiate match job

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_match?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&record_type=person&entity_type=person_entity&executor_count=1&executor_memory=8g&executor_core_count=1&log_cos_endpoint=http://s3.us-south.cloud-object-storage.appdomain.cloud&log_cos_bucket=mdmdata&log_cos_access_key=b33037e4e8954207a434cc032c1139d1&log_cos_secret_key=hex_string&do_force=false&do_deduplicate=false&do_analytics=false&do_replicate=false" 
Copy to clipboard

Example request

CreateMatchingMatchJobOptions createMatchingMatchJobOptions = new CreateMatchingMatchJobOptions.Builder()
  .recordType("person")
  .entityType("person_entity")
  .executorCount(Long.valueOf("1"))
  .executorMemory("8g")
  .executorCoreCount(Long.valueOf("1"))
  .sparkParallelism(Long.valueOf("2"))
  .logCosEndpoint("http://s3.us-south.cloud-object-storage.appdomain.cloud")
  .logCosBucket("mdmdata")
  .logCosAccessKey("b33037e4e8954207a434cc032c1139d1")
  .logCosSecretKey("<hex string>")
  .build();

Response<PostCloudJob> response = mdmService.createMatchingMatchJob(createMatchingMatchJobOptions).execute();
PostCloudJob postCloudJob = response.getResult();

System.out.println(postCloudJob);
Copy to clipboard

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

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

Status 202

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

Success example

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

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

Status 200

{
  "job_id": "",
  "exit_code": 0,
  "arguments": "runImportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}
Copy to clipboard

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

Status 202

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

This service initiates asynchronous processing of the derive job.
Data derivation is the process to standardize and generate buckets for the input records.

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

ServiceCall<PostCloudJob> createMatchingDeriveJob(CreateMatchingDeriveJobOptions createMatchingDeriveJobOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CreateMatchingDeriveJobOptions.Builder to create a CreateMatchingDeriveJobOptions object that contains the parameter values for the createMatchingDeriveJob method.

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>

CreateMatchingDeriveJobOptions

The createMatchingDeriveJob options.

Initiate data derivation job

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_derive?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&record_type=person&csv_file=person-100.tsv&csv_column=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=http://s3.us-south.cloud-object-storage.appdomain.cloud&cos_bucket=mdmdata&cos_access_key=1234567&cos_secret_key=7654321&executor_count=1&executor_memory=8g&executor_core_count=1&log_cos_endpoint=http://s3.us-south.cloud-object-storage.appdomain.cloud&log_cos_bucket=mdmdata&log_cos_access_key=b33037e4e8954207a434cc032c1139d1&log_cos_secret_key=hex_string" 
Copy to clipboard

Example request

CreateMatchingDeriveJobOptions createMatchingDeriveJobOptions = new CreateMatchingDeriveJobOptions.Builder()
  .recordType("person")
  .csvFile("/usr/mdm-matching/sample/person-100.tsv")
  .csvColumn("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")
  .cosEndpoint("http://s3.us-south.cloud-object-storage.appdomain.cloud")
  .cosBucket("mdmdata")
  .cosAccessKey("b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret")
  .cosSecretKey("<hex string>")
  .executorCount(Long.valueOf("1"))
  .executorMemory("8g")
  .executorCoreCount(Long.valueOf("1"))
  .sparkParallelism(Long.valueOf("2"))
  .logCosEndpoint("http://s3.us-south.cloud-object-storage.appdomain.cloud")
  .logCosBucket("mdmdata")
  .logCosAccessKey("b33037e4e8954207a434cc032c1139d1")
  .logCosSecretKey("<hex string>")
  .build();

Response<PostCloudJob> response = mdmService.createMatchingDeriveJob(createMatchingDeriveJobOptions).execute();
PostCloudJob postCloudJob = response.getResult();

System.out.println(postCloudJob);
Copy to clipboard

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

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

Status 202

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

Success example

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

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

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

ServiceCall<PostCloudJob> createMatchingReportJob(CreateMatchingReportJobOptions createMatchingReportJobOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CreateMatchingReportJobOptions.Builder to create a CreateMatchingReportJobOptions object that contains the parameter values for the createMatchingReportJob method.

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

CreateMatchingReportJobOptions

The createMatchingReportJob options.

Initiate report job

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_report?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&record_type=person&entity_type=person_entity&executor_count=1&executor_memory=8g&executor_core_count=1&job_list=entity_summary,bucket_summary&do_analytics=false" 
Copy to clipboard

Example request

CreateMatchingReportJobOptions createMatchingReportJobOptions = new CreateMatchingReportJobOptions.Builder()
  .recordType("person")
  .entityType("person_entity")
  .executorCount(Long.valueOf("1"))
  .executorMemory("8g")
  .executorCoreCount(Long.valueOf("1"))
  .sparkParallelism(Long.valueOf("2"))
  .jobList("entity_summary,bucket_summary")
  .build();

Response<PostCloudJob> response = mdmService.createMatchingReportJob(createMatchingReportJobOptions).execute();
PostCloudJob postCloudJob = response.getResult();

System.out.println(postCloudJob);
Copy to clipboard

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

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

Status 202

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

Success example

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

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

Status 200

{
  "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
  }
}
Copy to clipboard

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.

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

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.

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:

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

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

Status 200

{
  "entity_count_with_potential_match_issues": 10,
  "total_entity_count": 50
}
Copy to clipboard

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

Status 200

{
  "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
}
Copy to clipboard

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

Status 200

{
  "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"
        }
      ]
    }
  ]
}
Copy to clipboard

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:

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

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:

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

Status 202

{
  "job_name": "string",
  "last_updated_at": "string",
  "created_at": "string",
  "id": "string",
  "status": "string",
  "additionalProp1": {}
}
Copy to clipboard

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.

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

ServiceCall<Compare> compareMatchingIndex(CompareMatchingIndexOptions compareMatchingIndexOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the CompareMatchingIndexOptions.Builder to create a CompareMatchingIndexOptions object that contains the parameter values for the compareMatchingIndex method.

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:

CompareMatchingIndexOptions

The compareMatchingIndex options.

Compare records

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/compare?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&details=debug&entity_type=person_entity&record_number1=1234567890&record_number2=1234567899&record_type=person" --data "{"records":[{"record_type":"person","attributes":{"record_source":"MDM","record_id":"6","record_last_updated":"2017-10-02 18:08:23.638","birth_date":[{"value":"1961-08-24T00:00:00"}],"gender":[{"value":"mALe"}],"primary_residence":[{"record_start":"2017-10-02 18:08:23.689","record_last_updated":"2017-10-02 18:08:23.69","residence":"condo","address_line1":"7959 SW King AVE","city":"Toronto","zip_postal_code":"L5D4K8","residence_number":"120","province_state":"ON","county":"Peel","country":"canada"}],"home_telephone":[{"record_start":"2017-10-02 18:08:23.793","record_last_updated":"2017-10-02 18:08:23.793","phone_number":"905-722-5903","contact_method":"Telephone Number"}],"mobile_telephone":[{"record_start":"2017-10-02 18:08:23.793","record_last_updated":"2017-10-02 18:08:23.793","phone_number":"416-722-5903","contact_method":"Telephone Number"}],"personal_email":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"personal_email","email_id":"brownb@us.ibm.com","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"social_security_number":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"social_security_number","identification_number":"982588729873","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"drivers_licence":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"drivers_licence","identification_number":"803356781","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"passport":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"passport","identification_number":"EG346ASS9820M","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"legal_name":[{"record_start":"2017-10-02 18:08:23.641","record_last_updated":"2017-10-02 18:08:23.641","generation":"phd","usage":"Legal","prefix":"rev","given_name":"Bobby","middle_name":"Don","last_name":"Brown","suffix":"2d"}]}},{"record_type":"person","attributes":{"record_source":"MDMx","record_id":"7","record_last_updated":"2017-10-02 18:08:23.638","birth_date":[{"value":"1961-08-23T00:00:00"}],"gender":[{"value":"mALe"}],"primary_residence":[{"record_start":"2017-10-02 18:08:23.689","record_last_updated":"2017-10-02 18:08:23.69","residence":"condo","address_line1":"7950 SW King AVE","city":"Toronto","zip_postal_code":"L5D4K8","residence_number":"120","province_state":"ON","county":"Peel","country":"canada"}],"home_telephone":[{"record_start":"2017-10-02 18:08:23.793","record_last_updated":"2017-10-02 18:08:23.793","phone_number":"905-722-5903","contact_method":"Telephone Number"}],"personal_email":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"personal_email","email_id":"brownb@us.ibm.com","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"legal_name":[{"record_start":"2017-10-02 18:08:23.641","record_last_updated":"2017-10-02 18:08:23.641","generation":"phd","usage":"Legal","prefix":"rev","given_name":"Boby","middle_name":"Don","last_name":"Brown","suffix":"2d"}]}}]}" 
Copy to clipboard

Example request

SingleRecordRequestAttributes singleRecordRequestAttributesModel = new SingleRecordRequestAttributes.Builder()
  .recordLastUpdated(Long.valueOf("1506982103000"))
  .recordId("2")
  .recordSource("MDM")
  .add("birth_date", "[{\"value\":\"11/05/1993\"}]")
  .add("gender", "[{\"value\":\"male\"}]")
  .add("primary_residence", "[{\"record_start\":\" \",\"address_line1\":\"7908 NE VAN TRUMP AVE\",\"city\":\"LEFOR\",\"province_state\":\"Texas\"}]")
  .build();
SingleRecordRequest singleRecordRequestModel = new SingleRecordRequest.Builder()
  .recordType("person")
  .attributes(singleRecordRequestAttributesModel)
  .build();
CompareMatchingIndexOptions compareMatchingIndexOptions = new CompareMatchingIndexOptions.Builder()
  .records(new java.util.ArrayList<SingleRecordRequest>(java.util.Arrays.asList(singleRecordRequestModel)))
  .entityType("person_entity")
  .recordNumber1(Long.valueOf("123456789"))
  .recordNumber2(Long.valueOf("123456789"))
  .recordType("person")
  .build();

Response<Compare> response = mdmService.compareMatchingIndex(compareMatchingIndexOptions).execute();
Compare compare = response.getResult();

System.out.println(compare);
Copy to clipboard

Response

Response Body

Compare

Response object for comparing records

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

Status 200

{
  "score": 238,
  "score_category": "matched",
  "record_number1": 168071492364660740,
  "record_number2": 168071476032040960
}
Copy to clipboard

Success example

{
  "score": 238,
  "score_category": "matched",
  "record_number1": 168071492364660740,
  "record_number2": 168071476032040960
}
Copy to clipboard

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

Status 200

{
  "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]"
}
Copy to clipboard

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

Status 200

{
  "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"
    }
  ]
}
Copy to clipboard

This service retrieves the information about a job which is identified with the supplied job id.

This service retrieves the information about a job which is identified with the supplied job id.

GET /mdm/v1/matching_jobs/{job_id}

ServiceCall<GetMatchingJobs> getMatchingJobInfo(GetMatchingJobInfoOptions getMatchingJobInfoOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetMatchingJobInfoOptions.Builder to create a GetMatchingJobInfoOptions object that contains the parameter values for the getMatchingJobInfo method.

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.

GetMatchingJobInfoOptions

The getMatchingJobInfo options.

Retrieve information for a job

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/matching_jobs/95364?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetMatchingJobInfoOptions getMatchingJobInfoOptions = new GetMatchingJobInfoOptions.Builder()
  .jobId("95364")
  .build();

Response<GetMatchingJobs> response = mdmService.getMatchingJobInfo(getMatchingJobInfoOptions).execute();
GetMatchingJobs getMatchingJobs = response.getResult();

System.out.println(getMatchingJobs);

Response

Response Body

GetMatchingJobs

Response object for get matching job

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

Status 200

{
  "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"
}
Copy to clipboard

Success example

{
  "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"
}
Copy to clipboard

This service adds or updates a collection of manual link/unlink rules.

This service adds or updates a collection of manual link/unlink rules.

PUT /mdm/v1/linkage_rules

ServiceCall<Map<String, List<RulesEntityRule>>> replaceMatchingRule(ReplaceMatchingRuleOptions replaceMatchingRuleOptions)

Authorization

To call this method, 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

Use the ReplaceMatchingRuleOptions.Builder to create a ReplaceMatchingRuleOptions object that contains the parameter values for the replaceMatchingRule method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

RulesRequest

The wrapper object of linkage rules

ReplaceMatchingRuleOptions

The replaceMatchingRule options.

Add or update manual link/unlink

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/linkage_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"entity_type":"person_entity","{"rules":[{"record_numbers":["32995408531474430"],"rule_type":"unlink","description":"test"}]}}" 
Copy to clipboard

Example request

RulesRequestRule rulesRequestRuleModel = new RulesRequestRule.Builder()
  .ruleType("testString")
  .recordNumbers(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .description("testString")
  .build();
ReplaceMatchingRuleOptions replaceMatchingRuleOptions = new ReplaceMatchingRuleOptions.Builder()
  .rules(new java.util.ArrayList<RulesRequestRule>(java.util.Arrays.asList(rulesRequestRuleModel)))
  .entityType("testString")
  .build();

Response<Map<String, List<RulesEntityRule>>> response = mdmService.replaceMatchingRule(replaceMatchingRuleOptions).execute();
Map<String, List<RulesEntityRule>> mapStringListRulesEntityRule = response.getResult();

System.out.println(mapStringListRulesEntityRule);
Copy to clipboard

Response

Response type: Map<String, List<RulesEntityRule>>

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

Status 200

{
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}
Copy to clipboard

Success example

{
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}
Copy to clipboard

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.

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

ServiceCall<BatchComparePairsResponse> batchCompareMatchingIndex(BatchCompareMatchingIndexOptions batchCompareMatchingIndexOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the BatchCompareMatchingIndexOptions.Builder to create a BatchCompareMatchingIndexOptions object that contains the parameter values for the batchCompareMatchingIndex method.

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:

BatchCompareMatchingIndexOptions

The batchCompareMatchingIndex options.

Example request

BatchComparePairsRequestPair batchComparePairsRequestPairModel = new BatchComparePairsRequestPair.Builder()
  .recordNumber1("123")
  .recordNumber2("456")
  .build();
BatchCompareMatchingIndexOptions batchCompareMatchingIndexOptions = new BatchCompareMatchingIndexOptions.Builder()
  .pairs(new java.util.ArrayList<BatchComparePairsRequestPair>(java.util.Arrays.asList(batchComparePairsRequestPairModel)))
  .entityType("person_entity")
  .recordType("person")
  .build();

Response<BatchComparePairsResponse> response = mdmService.batchCompareMatchingIndex(batchCompareMatchingIndexOptions).execute();
BatchComparePairsResponse batchComparePairsResponse = response.getResult();

System.out.println(batchComparePairsResponse);
Copy to clipboard

Response

Response Body

BatchComparePairsResponse

The wrapper object for the comparison details of the pairs compared

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

Status 200

{
  "comparison_details": [
    {
      "score": 238,
      "score_category": "matched",
      "record_number1": 168071492364660740,
      "record_number2": 168071476032040960
    }
  ]
}
Copy to clipboard

Success example

{
  "comparison_details": [
    {
      "score": 238,
      "score_category": "matched",
      "record_number1": 168071492364660740,
      "record_number2": 168071476032040960
    }
  ]
}
Copy to clipboard

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

Status 200

{
  "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": {}
  }
}
Copy to clipboard

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

Status 200

{
  "self_scores": {
    "person_entity": 344
  },
  "record_number": 35676912450780160,
  "buckets": [],
  "standardized_values": " "
}
Copy to clipboard

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:

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

Status 200

{
  "impacted_records": {
    "person_entity": [
      {
        "record_id": "1",
        "record_number": "35676431109307390",
        "entity_id": "35676431109307390",
        "record_source": "MDM"
      }
    ]
  }
}
Copy to clipboard

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

Status 200

{
  "impacted_records": {
    "person_entity": []
  }
}

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:

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

Status 200

{
  "index_response": [
    {
      "record_id": "1",
      "record_type": "person",
      "record_source": "MDM",
      "algorithm_name": "person",
      "standardized_values": {},
      "buckets": []
    }
  ]
}
Copy to clipboard

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

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

POST /mdm/v1/linkage_rules_preview

ServiceCall<Map<String, Map<String, List<String>>>> createMatchingEntityPreview(CreateMatchingEntityPreviewOptions createMatchingEntityPreviewOptions)

Authorization

To call this method, 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

Use the CreateMatchingEntityPreviewOptions.Builder to create a CreateMatchingEntityPreviewOptions object that contains the parameter values for the createMatchingEntityPreview method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

RulesRequest

The wrapper object of linkage rules

CreateMatchingEntityPreviewOptions

The createMatchingEntityPreview options.

Preview entity composition

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/linkage_rules_preview?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"entity_type":"person_entity","{"rules":[{"record_numbers":["32995408531474430"],"rule_type":"unlink","description":"test"}]}}" 
Copy to clipboard

Example request

RulesRequestRule rulesRequestRuleModel = new RulesRequestRule.Builder()
  .ruleType("testString")
  .recordNumbers(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .description("testString")
  .build();
CreateMatchingEntityPreviewOptions createMatchingEntityPreviewOptions = new CreateMatchingEntityPreviewOptions.Builder()
  .rules(new java.util.ArrayList<RulesRequestRule>(java.util.Arrays.asList(rulesRequestRuleModel)))
  .entityType("testString")
  .build();

Response<Map<String, Map<String, List<String>>>> response = mdmService.createMatchingEntityPreview(createMatchingEntityPreviewOptions).execute();
Map<String, Map<String, List<String>>> mapStringMapStringListString = response.getResult();

System.out.println(mapStringMapStringListString);
Copy to clipboard

Response

Response type: Map<String, Map<String, List<String>>>

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

Status 200

{
  "person_entity": {
    "35678330629897216": [],
    "35678327655087104": [
      "35678330629897216",
      "35678327655087104"
    ]
  }
}
Copy to clipboard

Success example

{
  "person_entity": {
    "35678330629897216": [],
    "35678327655087104": [
      "35678330629897216",
      "35678327655087104"
    ]
  }
}
Copy to clipboard

This service retrieves all record_ids that are assigned with the same entity_id.

This service retrieves all record_ids that are assigned with the same entity_id.

GET /mdm/v1/entity_ids/{entity_id}

ServiceCall<GetRecordKeys> getMatchingRecords(GetMatchingRecordsOptions getMatchingRecordsOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetMatchingRecordsOptions.Builder to create a GetMatchingRecordsOptions object that contains the parameter values for the getMatchingRecords method.

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.

GetMatchingRecordsOptions

The getMatchingRecords options.

Retrieve record ids

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entity_ids/entity_type-123456789?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetMatchingRecordsOptions getMatchingRecordsOptions = new GetMatchingRecordsOptions.Builder()
  .entityId("entity_type-123456789")
  .build();

Response<GetRecordKeys> response = mdmService.getMatchingRecords(getMatchingRecordsOptions).execute();
GetRecordKeys getRecordKeys = response.getResult();

System.out.println(getRecordKeys);

Response

Response Body

GetRecordKeys

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

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

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.

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

ServiceCall<PostSearch> searchMatchingIndex(SearchMatchingIndexOptions searchMatchingIndexOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the SearchMatchingIndexOptions.Builder to create a SearchMatchingIndexOptions object that contains the parameter values for the searchMatchingIndex method.

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:

SearchMatchingIndexOptions

The searchMatchingIndex options.

Search records by matching algorithm

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/probabilistic_search?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"record_type":"person","attributes":{"record_source":"PERSONLIST","record_id":"101","birth_date":[{"value":"2007-01-02"}],"gender":[{"value":"F"}],"primary_residence":[{"address_line1":"232 S RICHELIEU ST.E","city":"PORT NORRIS","zip_postal_code":"8349","province_state":"NJ"}],"business_address":[{"address_line1":"9852 WEST DORSET STREET","city":"SHADE GAP","zip_postal_code":"17255","province_state":"PA"}],"home_telephone":[{"phone_number":"248-0677"}],"social_security_number":[{"identification_number":"117-85-3320"}],"health_card":[{"identification_number":"788-71-4075"}],"legal_name":[{"given_name":"MARGUERITE","last_name":"NICKLES"}]}}" 
Copy to clipboard

Example request

SingleRecordRequestAttributes singleRecordRequestAttributesModel = new SingleRecordRequestAttributes.Builder()
  .recordLastUpdated(Long.valueOf("1506982103000"))
  .recordId("2")
  .recordSource("MDM")
  .add("birth_date", "[{\"value\":\"1964-08-21 00:00:00\"}]")
  .add("gender", "[{\"value\":\"mALe\"}]")
  .add("legal_name", "[{\"record_start\":\"017-10-02 18:08:23.689\",\"generation\":\"NEWBORN\",\"given_name\":[\"GIRL1\",\"GIRL1\",\"GIRL2\",\"GIRL3\",\"GIRL4\"],\"middle_name\":\"BABYGIRL\"}]")
  .build();
SearchMatchingIndexOptions searchMatchingIndexOptions = new SearchMatchingIndexOptions.Builder()
  .recordType("person")
  .attributes(singleRecordRequestAttributesModel)
  .build();

Response<PostSearch> response = mdmService.searchMatchingIndex(searchMatchingIndexOptions).execute();
PostSearch postSearch = response.getResult();

System.out.println(postSearch);
Copy to clipboard

Response

Response Body

PostSearch

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

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

Status 200

{
  "records": [
    {
      "record_id": "101",
      "score": 238,
      "record_source": "PERSONLIST"
    },
    {
      "record_id": "1",
      "score": 238,
      "record_source": "PERSONLIST"
    }
  ]
}
Copy to clipboard

Success example

{
  "records": [
    {
      "record_id": "101",
      "score": 238,
      "record_source": "PERSONLIST"
    },
    {
      "record_id": "1",
      "score": 238,
      "record_source": "PERSONLIST"
    }
  ]
}
Copy to clipboard

This service retrieves all manual link/unlink rules for specified entity.

This service retrieves all manual link/unlink rules for specified entity.

GET /mdm/v1/entities/{entity_id}/linkage_rules

ServiceCall<Map<String, List<RulesEntityRule>>> listMatchingRules(ListMatchingRulesOptions listMatchingRulesOptions)

Authorization

To call this method, 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

Use the ListMatchingRulesOptions.Builder to create a ListMatchingRulesOptions object that contains the parameter values for the listMatchingRules method.

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.

ListMatchingRulesOptions

The listMatchingRules options.

Retrieve an entity's manual links/unlinks

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entities/{entity_id}/linkage_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&entity_id=person_entity-1234" 
Copy to clipboard

Example request

ListMatchingRulesOptions listMatchingRulesOptions = new ListMatchingRulesOptions.Builder()
  .entityId("person_entity-1234")
  .build();

Response<Map<String, List<RulesEntityRule>>> response = mdmService.listMatchingRules(listMatchingRulesOptions).execute();
Map<String, List<RulesEntityRule>> mapStringListRulesEntityRule = response.getResult();

System.out.println(mapStringListRulesEntityRule);

Response

Response type: Map<String, List<RulesEntityRule>>

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

Status 200

{
  "person_entity": [
    {
      "last_updated": "1611866992413",
      "rule_type": "UNLINK",
      "src_recno": "42690607485214720",
      "description": "string",
      "target_recno": "42690601550274560",
      "user": "admin"
    }
  ]
}
Copy to clipboard

Success example

{
  "person_entity": [
    {
      "last_updated": "1611866992413",
      "rule_type": "UNLINK",
      "src_recno": "42690607485214720",
      "description": "string",
      "target_recno": "42690601550274560",
      "user": "admin"
    }
  ]
}
Copy to clipboard

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

Status 200

[
  {
    "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"
  }
]
Copy to clipboard

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

Status 200

{
  "entities": [
    {
      "entity_type": "person_entity",
      "entity_id": 32995408531474430
    }
  ]
}
Copy to clipboard

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

Status 200

{
  "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
}
Copy to clipboard

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

Status 200

{
"total_records": 100,
"unique_source_count": 1,
"total_entities": 27,
"stats_and_entities": {
"entity_size_stats": {},
}
}
Copy to clipboard

This service retrieves all manual link/unlink rules for given record and entity type.

This service retrieves all manual link/unlink rules for given record and entity type.

GET /mdm/v1/records/{record_number}/linkage_rules

ServiceCall<Map<String, List<RulesEntityRule>>> getMatchingRecordRules(GetMatchingRecordRulesOptions getMatchingRecordRulesOptions)

Authorization

To call this method, 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

Use the GetMatchingRecordRulesOptions.Builder to create a GetMatchingRecordRulesOptions object that contains the parameter values for the getMatchingRecordRules method.

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

GetMatchingRecordRulesOptions

The getMatchingRecordRules options.

Retrieve an record's manual links/unlinks

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records/{record_number}/linkage_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&record_number=123456789&entity_type=person_entity" 
Copy to clipboard

Example request

GetMatchingRecordRulesOptions getMatchingRecordRulesOptions = new GetMatchingRecordRulesOptions.Builder()
  .recordNumber(Long.valueOf("123456789"))
  .entityType("entity-type")
  .build();

Response<Map<String, List<RulesEntityRule>>> response = mdmService.getMatchingRecordRules(getMatchingRecordRulesOptions).execute();
Map<String, List<RulesEntityRule>> mapStringListRulesEntityRule = response.getResult();

System.out.println(mapStringListRulesEntityRule);
Copy to clipboard

Response

Response type: Map<String, List<RulesEntityRule>>

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

Status 200

{
  "person_entity": [
    {
      "src_recno": "35677335438998529",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user2",
      "last_updated": "1605178647781"
    }
  ]
}
Copy to clipboard

Success example

{
  "person_entity": [
    {
      "src_recno": "35677335438998529",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user2",
      "last_updated": "1605178647781"
    }
  ]
}
Copy to clipboard

This service removes one or more manual link/unlink rules supplied by user.

This service removes one or more manual link/unlink rules supplied by user.

POST /mdm/v1/delete_linkage_rules

ServiceCall<Map<String, List<RulesEntityRule>>> deleteMatchingRule(DeleteMatchingRuleOptions deleteMatchingRuleOptions)

Authorization

To call this method, 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

Use the DeleteMatchingRuleOptions.Builder to create a DeleteMatchingRuleOptions object that contains the parameter values for the deleteMatchingRule method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

RulesRequest

The wrapper object of linkage rules

DeleteMatchingRuleOptions

The deleteMatchingRule options.

Remove manual link/unlink

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/delete_linkage_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"entity_type":"person_entity","{"rules":[{"record_numbers":["32995408531474430"],"rule_type":"unlink","description":"test"}]}}" 
Copy to clipboard

Example request

RulesRequestRule rulesRequestRuleModel = new RulesRequestRule.Builder()
  .ruleType("testString")
  .recordNumbers(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .description("testString")
  .build();
DeleteMatchingRuleOptions deleteMatchingRuleOptions = new DeleteMatchingRuleOptions.Builder()
  .rules(new java.util.ArrayList<RulesRequestRule>(java.util.Arrays.asList(rulesRequestRuleModel)))
  .entityType("testString")
  .build();

Response<Map<String, List<RulesEntityRule>>> response = mdmService.deleteMatchingRule(deleteMatchingRuleOptions).execute();
Map<String, List<RulesEntityRule>> mapStringListRulesEntityRule = response.getResult();

System.out.println(mapStringListRulesEntityRule);
Copy to clipboard

Response

Response type: Map<String, List<RulesEntityRule>>

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

Status 200

{
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}
Copy to clipboard

Success example

{
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}
Copy to clipboard

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

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

Status 200

{
  "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"
            ]
          }
        ]
      }
    }
  }
}
Copy to clipboard

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

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

Status 200

{"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"]}]}}}
Copy to clipboard

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

Status 200

{
  "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": {}
  }
}
Copy to clipboard

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

Status 200

{
  "job_id": "",
  "exit_code": 0,
  "arguments": "runImportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}
Copy to clipboard

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

Status 200

{
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExportData.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}
Copy to clipboard

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

Status 200

{
  "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
  }
}
Copy to clipboard

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

Status 200

{
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}
Copy to clipboard

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

Status 200

{
  "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": {}
}
Copy to clipboard

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

Status 200

{
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExport.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}
Copy to clipboard

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.

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.

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

Status 200

{
  "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
    }
  }
}
Copy to clipboard

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

Status 200

{
  "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": {}
      }
    }
  }
}
Copy to clipboard

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

Status 200

{
  "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
  }
}
Copy to clipboard

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.

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.

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

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.

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

ServiceCall<AlgorithmNames> listModelAlgorithms(ListModelAlgorithmsOptions listModelAlgorithmsOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListModelAlgorithmsOptions.Builder to create a ListModelAlgorithmsOptions object that contains the parameter values for the listModelAlgorithms method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Retrieve record types of all the matching algorithms

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/algorithms?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListModelAlgorithmsOptions listModelAlgorithmsOptions = new ListModelAlgorithmsOptions();

Response<AlgorithmNames> response = mdmService.listModelAlgorithms(listModelAlgorithmsOptions).execute();
AlgorithmNames algorithmNames = response.getResult();

System.out.println(algorithmNames);

Response

Response Body

AlgorithmNames

Response wrapper object for all algorithm names

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

Status 200

{
  "algorithm_names": [
    "organization",
    "person"
  ]
}
Copy to clipboard

Success example

{
  "algorithm_names": [
    "organization",
    "person"
  ]
}
Copy to clipboard

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.

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}

ServiceCall<Algorithm> getModelAlgorithm(GetModelAlgorithmOptions getModelAlgorithmOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetModelAlgorithmOptions.Builder to create a GetModelAlgorithmOptions object that contains the parameter values for the getModelAlgorithm method.

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

GetModelAlgorithmOptions

The getModelAlgorithm options.

Retrieve the matching algorithm

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/algorithms/person?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetModelAlgorithmOptions getModelAlgorithmOptions = new GetModelAlgorithmOptions.Builder()
  .recordType("testString")
  .build();

Response<Algorithm> response = mdmService.getModelAlgorithm(getModelAlgorithmOptions).execute();
Algorithm algorithm = response.getResult();

System.out.println(algorithm);

Response

Response Body

Algorithm

The matching algorithm for a given record type (i.e. person)

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

Status 200

{
  "locale": "en_us",
  "encryption": {},
  "standardizers": {},
  "entity_types": {}
}
Copy to clipboard

Success example

{
  "locale": "en_us",
  "encryption": {},
  "standardizers": {},
  "entity_types": {}
}
Copy to clipboard

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.

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}

ServiceCall<PutAlgorithm> replaceModelAlgorithm(ReplaceModelAlgorithmOptions replaceModelAlgorithmOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceModelAlgorithmOptions.Builder to create a ReplaceModelAlgorithmOptions object that contains the parameter values for the replaceModelAlgorithm method.

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)

ReplaceModelAlgorithmOptions

The replaceModelAlgorithm options.

Overwrite the matching algorithm

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/algorithm/person?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"locale":"en_us","encryption":{"enabled":true,"type":"RSA","sub_type":"Deterministic","pub_key":["59268009512619467129490841773957547832260510507986184641685362733218475996133","15532435938367556669"]},"standardizers":{"name_standardizer":{"label":"Person Name Standardizer","inputs":[{"fields":["last_name","full_name","given_name","middle_name","prefix","suffix","generation"], "attributes":["legal_name","previous_name"]}],"standardizer_recipe":[{"method":"Standardizer.UpperCase","label":"Uppercase","inputs":[1]},{"method":"Standardizer.MapCharacter","label":"Map equivalent Character","map_resource":"person_map_character_general","inputs":[1]},{"method":"Standardizer.Tokenizer","delimiters":[" ","-","/",",","."],"label":"Tokenization","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["given_name","full_name","middle_name","last_name","prefix","suffix","generation"],"drop_unparsed_values":false,"label":"Parse Token","map_resource":"person_map_name_alignments","inputs":[1]},{"method":"Standardizer.Length","min_length":2,"max_length":100,"fields":["last_name"],"label":"Remove single characters from last name","inputs":[1]},{"method":"Standardizer.StopToken","fields":["last_name","given_name","middle_name","prefix","suffix","generation","full_name"],"label":"Stop anonymous token","set_resource":"person_set_name_aname","inputs":[1]},{"method":"Standardizer.PickToken","fields":["last_name","given_name","middle_name","prefix","suffix","generation","full_name"],"unique_tokens":true,"label":"Pick Token","inputs":[1]}]},"birthdate_standardizer":{"label":"BirthDate Standardizer","inputs":[{"fields":["value"],"attributes":["birth_date"]}],"standardizer_recipe":[{"method":"Standardizer.MapCharacter","label":"Convert separators to dashes","map_resource":"person_map_character_date_separators","inputs":[1]},{"method":"Standardizer.Date","input_formats":["d-M-yyyy","yyyy-M-d","M-d-yyyy","yy-M-d","d-M","M-yyyy","MMM d, yyyy","yyyy-M-d'T'HH:mm:ss","yyyy-M-d HH:mm:ss","MMM d","M-yy","yyyy","yy"],"label":"Date Stanardization","inputs":[1]},{"method":"Standardizer.StopToken","label":"Remove filler dates","set_resource":"person_set_date_date","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["value"],"drop_unparsed_values":true,"label":"Parse year, month, day","map_resource":"person_map_date_tokens_year_month_day","inputs":[1]},{"method":"Standardizer.PickToken","fields":["birth_year","birth_month","birth_day"],"count":3,"unique_tokens":true,"label":"Pick Token","inputs":[1]}]},"gender_standardizer":{"label":"Gender Standardizer","inputs":[{"fields":["value"],"attributes":["gender"]}],"standardizer_recipe":[{"method":"Standardizer.MapCharacter","label":"Map equivalent Character","map_resource":"person_map_character_general","inputs":[1]},{"method":"Standardizer.UpperCase","label":"Uppercase","inputs":[1]},{"method":"Standardizer.StopToken","label":"Stop anonymous Token","set_resource":"person_set_gender_anon_gender","inputs":[1]},{"method":"Standardizer.MapToken","label":"Map equivalent Token","map_resource":"person_map_gender_gender","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["value"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_gender_tokens_gender","inputs":[1]},{"method":"Standardizer.PickToken","fields":["gender"],"count":1,"unique_tokens":true,"label":"Pick Token","inputs":[1]}]},"address_standardizer":{"label":"Address Standardizer","inputs":[{"fields":["residence_number","address_line1","address_line2","address_line3","city","province_state","zip_postal_code","country","latitude_degrees","longitude_degrees"],"attributes":["primary_residence","mailing_address"]}],"standardizer_recipe":[{"method":"Standardizer.UpperCase","label":"Uppercase","inputs":[1]},{"method":"Standardizer.MapCharacter","label":"Map equivalent Character","map_resource":"person_map_character_general","inputs":[1]},{"method":"Standardizer.MapToken","fields":["country"],"label":"Map equivalent Token","map_resource":"person_map_address_country","inputs":[1]},{"method":"Standardizer.MapToken","fields":["province_state"],"label":"Map equivalent Token","map_resource":"person_map_address_province_state","inputs":[1]},{"method":"Standardizer.MapToken","label":"Map equivalent Token","map_resource":"person_map_address_delimiter_removal","inputs":[1]},{"method":"Standardizer.Tokenizer","delimiters":[" "],"label":"Tokenization","inputs":[1]},{"method":"Standardizer.MapToken","label":"Map equivalent Token","map_resource":"person_map_address_addr_tok","inputs":[1]},{"method":"Standardizer.StopToken","fields":["zip_postal_code"],"label":"Stop anonymous Word in ZipPostalCode","set_resource":"person_set_address_postal_code","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["residence_number"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_unit_type_and_number","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["address_line1"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_unit_type_and_number","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["address_line2"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_sub_division","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["address_line3"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_pobox_type_and_number","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["city"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_city","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["province_state"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_province","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["zip_postal_code"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_postal_code","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["country"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_country","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["latitude_degrees"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_latitude","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["longitude_degrees"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_address_tokens_longtitude","inputs":[1]},{"method":"Standardizer.PickToken","fields":["unit_number","street_number","street_name","direction","street_type","pobox","postal_code","city","province","sub_division","country"],"count":16,"unique_tokens":true,"label":"Pick Token","inputs":[1]},{"method":"Standardizer.PickToken","fields":["latitude","longtitude"],"count":2,"unique_tokens":true,"label":"Pick Token","inputs":[1]}]},"phone_standardizer":{"label":"Phone Standardizer","inputs":[{"fields":["phone_number"],"attributes":["home_telephone","mobile_telephone"]}],"standardizer_recipe":[{"method":"Standardizer.StopCharacter","label":"Replace all characters except alphanumeric","set_resource":"person_set_character_phone","inputs":[1]},{"method":"Standardizer.StopToken","label":"Ignore anonymous phones","set_resource":"person_set_phone_anon_phone","inputs":[1]},{"method":"Standardizer.Phone","locales":["US","CN","GB","CA"],"drop_country_code":true,"drop_area_code":true,"drop_local_number":false,"label":"Parse phone number","digits_retained":7,"inputs":[1]},{"method":"Standardizer.ParseToken","fields":["phone_number"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_phone_tokens_phone","inputs":[1]},{"method":"Standardizer.PickToken","fields":["phone"],"count":1,"unique_tokens":true,"label":"Pick Token","inputs":[1]}]},"identification_standardizer":{"label":"Identification Standardizer","inputs":[{"fields":["identification_number"],"attributes":["drivers_licence","passport","social_insurance_number","credit_card"]}],"standardizer_recipe":[{"method":"Standardizer.MapCharacter","label":"Map equivalent Character","map_resource":"person_map_character_general","inputs":[1]},{"method":"Standardizer.UpperCase","label":"Uppercase","inputs":[1]},{"method":"Standardizer.StopToken","label":"Stop anonymous Token","set_resource":"person_set_identifier_anonymous","inputs":[1]},{"method":"Standardizer.MapToken","label":"Map equivalent Token","map_resource":"person_map_identifier_equi_identifier","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["identification_number"],"drop_unparsed_values":false,"label":"Parse token","map_resource":"person_map_identifier_tokens_identification_number","inputs":[1]},{"method":"Standardizer.PickToken","fields":["identification_number"],"count":1,"unique_tokens":true,"label":"Pick Token","inputs":[1]}]},"email_standardizer":{"label":"Non-Phone Contact Method Standardizer","inputs":[{"fields":["email_id"],"attributes":["personal_email"]}],"standardizer_recipe":[{"method":"Standardizer.MapCharacter","label":"Map equivalent Character","map_resource":"person_map_character_general","inputs":[1]},{"method":"Standardizer.UpperCase","label":"Uppercase","inputs":[1]},{"method":"Standardizer.StopToken","label":"Stop anonymous Token","set_resource":"person_set_non_phone_anon_non_phone","inputs":[1]},{"method":"Standardizer.MapToken","label":"Map equivalent Token","map_resource":"person_map_non_phone_equi_non_phone","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["email_id"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_non_phone_tokens_non_phone","inputs":[1]},{"method":"Standardizer.PickToken","fields":["email_local_part","email_domain"],"count":2,"unique_tokens":true,"label":"Pick Token","inputs":[1]}]},"social_media_standardizer":{"label":"Social media Standardizer","inputs":[{"fields":["social_media_handle"],"attributes":["twitter"]}],"standardizer_recipe":[{"method":"Standardizer.MapCharacter","label":"Map equivalent Character","map_resource":"person_map_character_general","inputs":[1]},{"method":"Standardizer.UpperCase","label":"Uppercase","inputs":[1]},{"method":"Standardizer.StopToken","label":"Stop anonymous Token","set_resource":"person_set_non_phone_anon_non_phone","inputs":[1]},{"method":"Standardizer.MapToken","label":"Map equivalent Token","map_resource":"person_map_non_phone_equi_non_phone","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["social_media_handle"],"drop_unparsed_values":true,"label":"Parse token","map_resource":"person_map_non_phone_tokens_non_phone","inputs":[1]},{"method":"Standardizer.PickToken","fields":["social_media_id"],"count":2,"unique_tokens":true,"label":"Pick Token","inputs":[1]}]}},"entity_types":{"person_entity":{"bucket_generators":{"name_phone_id_zip_dob_flat_buckets":{"label":"PersonName+Phone/Id/Zip/DOB Flat Buckets","maximum_bucket_size":1000,"inputs":[{"fields":["last_name","given_name","full_name"],"attributes":["legal_name","previous_name"]},{"fields":["phone"],"attributes":["home_telephone","mobile_telephone"]},{"fields":["identification_number"],"attributes":["drivers_licence","social_insurance_number"]},{"fields":["postal_code"],"attributes":["primary_residence","mailing_address"]},{"fields":["birth_day","birth_month","birth_year"],"attributes":["birth_date"]}],"bucket_recipe":[{"method":"BucketGenerator.StopToken","inputs":[1],"fields":["given_name","full_name"],"label":"Exclude Anonymous Name","set_resource":"person_set_name_bkt_anon"},{"method":"BucketGenerator.MapToken","inputs":[1],"fields":["given_name","full_name"],"label":"Nickname convesion","map_resource":"person_map_name_nickname"},{"method":"BucketGenerator.Normphone","inputs":[1],"fields":["last_name","given_name","full_name"],"output_fields":["last_name.normphone","given_name.normphone","full_name.normphone"],"label":"Name Phonetics"},{"inputs":[2],"method":"BucketGenerator.NGram","count":5,"output_fields":["phone.5gram"],"label":"Telephone 5 Grams"},{"inputs":[3],"method":"BucketGenerator.NGram","count":5,"output_fields":["identification_number.5gram"],"label":"Identifier 5 Grams"},{"method":"BucketGenerator.StopToken","inputs":[5],"label":"Exclude Anonymous BirthDate","set_resource":"person_set_date_date"}],"bucket_group_recipe":[{"method":"BucketGenerator.PickToken","inputs":[1,2],"fields":[["given_name.normphone","last_name.normphone","full_name.normphone"],["phone.5gram"]],"min_tokens":[1,1],"max_tokens":[1,1],"count":100,"bucket_group":1,"order":true,"maximum_bucket_size":1000,"label":"Bucket: Normphone Name + 5GramPhone "},{"method":"BucketGenerator.PickToken","inputs":[1,3],"fields":[["last_name.normphone","given_name.normphone","full_name.normphone"],["identification_number.5gram"]],"min_tokens":[1,1],"max_tokens":[1,1],"count":100,"bucket_group":2,"order":true,"maximum_bucket_size":1000,"label":"Bucket: Normphone Name + 5GramIds"},{"method":"BucketGenerator.PickToken","inputs":[1,4],"fields":[["last_name.normphone","given_name.normphone","full_name.normphone"],["postal_code"]],"min_tokens":[1,1],"max_tokens":[2,1],"count":100,"bucket_group":3,"order":true,"maximum_bucket_size":1000,"label":"Bucket: Normphone Name + PostCode AsIs"},{"method":"BucketGenerator.PickToken","inputs":[1,5],"fields":[["last_name.normphone","given_name.normphone","full_name.normphone"],["birth_day","birth_month","birth_year"]],"min_tokens":[1,1],"max_tokens":[2,1],"count":100,"bucket_group":4,"order":true,"maximum_bucket_size":1000,"label":"Bucket: Normphone Name + BirthDate"}]},"identifiers_flat_buckets":{"label":"Identifiers Flat Buckets","maximum_bucket_size":1000,"inputs":[{"fields":["identification_number"],"attributes":["passport","credit_card"]}],"bucket_recipe":[{"method":"BucketGenerator.PickToken","inputs":[1],"fields":["identification_number"],"min_tokens":[1],"max_tokens":[1],"count":100,"bucket_group":5,"order":false,"maximum_bucket_size":1000,"label":"Bucket: Id"}]},"email_flat_buckets":{"label":"Email Flat Buckets","maximum_bucket_size":1000,"inputs":[{"fields":["email_local_part","email_domain"],"attributes":["personal_email"]}],"bucket_recipe":[{"method":"BucketGenerator.PickToken","inputs":[1],"fields":["email_local_part"],"min_tokens":[1],"max_tokens":[1],"count":100,"bucket_group":6,"order":false,"maximum_bucket_size":1000,"label":"Bucket: Email"}]},"social_media_flat_buckets":{"label":"SocialMedia Flat Buckets","maximum_bucket_size":1000,"inputs":[{"fields":["social_media_id"],"attributes":["twitter"]}],"bucket_recipe":[{"method":"BucketGenerator.PickToken","inputs":[1],"fields":["social_media_id"],"min_tokens":[1],"max_tokens":[1],"count":100,"bucket_group":7,"order":false,"maximum_bucket_size":1000,"label":"Bucket: SocialMedaiId"}]}},"clerical_review_threshold":130,"auto_link_threshold":150,"compare_methods":{"name_compare":{"label":"Person Name Compare","methods":[{"inputs":[{"fields":["last_name","given_name","middle_name","prefix","suffix","generation","full_name"],"attributes":["legal_name","previous_name"]}],"compare_recipe":[{"fields":["last_name","given_name","middle_name","prefix","suffix","generation","full_name"],"method":"CompareMethod.NameCompare","label":"Name Match","comparison_resource":"person_compare_spec_name","inputs":[1]}]}],"weights":[65,60,55,50,35,20,10,0,-5,-15,-20]},"birth_date_compare":{"label":"Birth Date Compare","methods":[{"inputs":[{"fields":["birth_year","birth_month","birth_day"],"attributes":["birth_date"]}],"compare_recipe":[{"fields":["birth_year","birth_month","birth_day"],"method":"CompareMethod.DateCompare","label":"Year, Month and Day Match","comparison_resource":"person_compare_spec_date","inputs":[1]}]}],"weights":[12,11,10,9,5,4,2,1,0,0,0]},"gender_compare":{"label":"Gender Compare","methods":[{"inputs":[{"fields":["gender"],"attributes":["gender"]}],"compare_recipe":[{"fields":["gender"],"method":"CompareMethod.SingleTokenCompare","label":"Gender Match","comparison_resource":"person_compare_spec_gender","inputs":[1]}]}],"weights":[3,0,-5,-10,-15,-20,-25,-32,-40,-48,-54]},"email_and_social_media_compare":{"label":"Email and Social Media Compare","methods":[{"inputs":[{"fields":["email_local_part","email_domain"],"attributes":["personal_email"]}],"compare_recipe":[{"fields":["email_local_part","email_domain"],"method":"CompareMethod.EmailCompare","label":"Email Match","comparison_resource":"person_compare_spec_email","inputs":[1]}]},{"inputs":[{"fields":["social_media_id"],"attributes":["twitter"]}],"compare_recipe":[{"fields":["social_media_id"],"method":"CompareMethod.SingleTokenCompare","label":"Social Media Id Match","comparison_resource":"person_compare_spec_non_phone","inputs":[1]}]}],"weights":[52,45,40,35,30,25,15,5,0,-10,-20]},"identifiers_compare":{"label":"Identifiers Compare","methods":[{"inputs":[{"fields":["identification_number"],"attributes":["social_insurance_number"]}],"compare_recipe":[{"fields":["identification_number"],"method":"CompareMethod.SingleTokenCompare","label":"Social Insurance Number Match","comparison_resource":"person_compare_spec_identifier","inputs":[1]}]}],"weights":[54,50,40,35,30,25,15,5,0,-10,-20]},"other_identifiers_compare":{"label":"Other Identifiers Compare","methods":[{"inputs":[{"fields":["identification_number"],"attributes":["drivers_licence"]}],"compare_recipe":[{"fields":["identification_number"],"method":"CompareMethod.SingleTokenCompare","label":"Drivers Licence Match","comparison_resource":"person_compare_spec_identifier","inputs":[1]}]},{"inputs":[{"fields":["identification_number"],"attributes":["passport"]}],"compare_recipe":[{"fields":["identification_number"],"method":"CompareMethod.SingleTokenCompare","label":"Passport Match","comparison_resource":"person_compare_spec_identifier","inputs":[1]}]}],"weights":[54,50,40,35,30,25,15,5,0,-10,-20]},"credit_card_compare":{"label":"Credit Card Compare","methods":[{"inputs":[{"fields":["identification_number"],"attributes":["credit_card"]}],"compare_recipe":[{"fields":["identification_number"],"method":"CompareMethod.SingleTokenCompare","label":"Credit Card Match","comparison_resource":"person_compare_spec_identifier","inputs":[1]}]}],"weights":[54,50,40,35,30,25,15,5,0,-10,-20]},"phone_compare":{"label":"Phone Compare","methods":[{"inputs":[{"fields":["phone"],"attributes":["home_telephone","mobile_telephone"]}],"compare_recipe":[{"fields":["phone"],"method":"CompareMethod.SingleTokenCompare","label":"Phone Match","comparison_resource":"person_compare_spec_phone","inputs":[1]}]}],"weights":[52,50,47,44,40,35,30,26,23,23,22]},"address_compare":{"label":"Address Compare","methods":[{"inputs":[{"fields":["unit_number","street_number","street_name","direction","street_type","pobox","postal_code","city","province","sub_division","country","latitude","longtitude"],"attributes":["primary_residence","mailing_address"]}],"compare_recipe":[{"fields":["unit_number","street_number","street_name","direction","street_type","pobox","postal_code","city","province","sub_division","country","latitude","longtitude"],"method":"CompareMethod.AddressCompare","label":"Address Match","comparison_resource":"person_compare_spec_address","inputs":[1]}]}],"weights":[52,47,42,37,30,25,20,15,10,5,1]}}}}}" 
Copy to clipboard

Example request

AlgorithmStandardizerStep algorithmStandardizerStepModel = new AlgorithmStandardizerStep.Builder()
  .label("testString")
  .method("testString")
  .build();
AlgorithmInput algorithmInputModel = new AlgorithmInput.Builder()
  .attributes(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .fields(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .build();
AlgorithmStandardizer algorithmStandardizerModel = new AlgorithmStandardizer.Builder()
  .label("testString")
  .standardizerRecipe(new java.util.ArrayList<AlgorithmStandardizerStep>(java.util.Arrays.asList(algorithmStandardizerStepModel)))
  .inputs(new java.util.ArrayList<AlgorithmInput>(java.util.Arrays.asList(algorithmInputModel)))
  .build();
AlgorithmEncryption algorithmEncryptionModel = new AlgorithmEncryption.Builder()
  .subType("testString")
  .pubKey(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .enabled(true)
  .type("testString")
  .build();
AlgorithmEntityType algorithmEntityTypeModel = new AlgorithmEntityType.Builder()
  .autoLinkThreshold(Float.valueOf("36.0"))
  .build();
ReplaceModelAlgorithmOptions replaceModelAlgorithmOptions = new ReplaceModelAlgorithmOptions.Builder()
  .recordType("testString")
  .standardizers(new java.util.HashMap<String, AlgorithmStandardizer>() { { put("foo", algorithmStandardizerModel); } })
  .encryption(algorithmEncryptionModel)
  .entityTypes(new java.util.HashMap<String, AlgorithmEntityType>() { { put("foo", algorithmEntityTypeModel); } })
  .locale("testString")
  .build();

Response<PutAlgorithm> response = mdmService.replaceModelAlgorithm(replaceModelAlgorithmOptions).execute();
PutAlgorithm putAlgorithm = response.getResult();

System.out.println(putAlgorithm);
Copy to clipboard

Response

Response Body

PutAlgorithm

Response wrapper object for overwriting matching algorithm

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

Status 200

{
  "flow_state": "published",
  "flow_id": "41017488",
  "algorithm": {}
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_id": "41017488",
  "algorithm": {}
}
Copy to clipboard

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.

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}

ServiceCall<PutAlgorithm> generateModelAlgorithm(GenerateModelAlgorithmOptions generateModelAlgorithmOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GenerateModelAlgorithmOptions.Builder to create a GenerateModelAlgorithmOptions object that contains the parameter values for the generateModelAlgorithm method.

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)

GenerateModelAlgorithmOptions

The generateModelAlgorithm options.

Example request

AlgorithmGenerationAttributeItem algorithmGenerationAttributeItemModel = new AlgorithmGenerationAttributeItem.Builder()
  .attributes(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .build();
AlgorithmGenerationEntityType algorithmGenerationEntityTypeModel = new AlgorithmGenerationEntityType.Builder()
  .matchingAttributes(new java.util.ArrayList<AlgorithmGenerationAttributeItem>(java.util.Arrays.asList(algorithmGenerationAttributeItemModel)))
  .build();
GenerateModelAlgorithmOptions generateModelAlgorithmOptions = new GenerateModelAlgorithmOptions.Builder()
  .recordType("testString")
  .requestBody(new java.util.HashMap<String, AlgorithmGenerationEntityType>() { { put("foo", algorithmGenerationEntityTypeModel); } })
  .build();

Response<PutAlgorithm> response = mdmService.generateModelAlgorithm(generateModelAlgorithmOptions).execute();
PutAlgorithm putAlgorithm = response.getResult();

System.out.println(putAlgorithm);
Copy to clipboard

Response

Response Body

PutAlgorithm

Response wrapper object for overwriting matching algorithm

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

Status 200

{
  "flow_state": "published",
  "flow_id": "41017488",
  "algorithm": {}
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_id": "41017488",
  "algorithm": {}
}
Copy to clipboard

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.

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}

ServiceCall<PutAlgorithm> updateModelAlgorithm(UpdateModelAlgorithmOptions updateModelAlgorithmOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the UpdateModelAlgorithmOptions.Builder to create a UpdateModelAlgorithmOptions object that contains the parameter values for the updateModelAlgorithm method.

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)

UpdateModelAlgorithmOptions

The updateModelAlgorithm options.

Partially modify matching algorithm

curl -X PATCH --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/algorithm/person?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"standardizers":{"name_standardizer":{"label":"Person Name Standardizer","inputs":[{"fields":["last_name","full_name","given_name","middle_name","prefix","suffix","generation"],"attributes":["legal_name","previous_name"]}],"standardizer_recipe":[{"method":"Standardizer.UpperCase","label":"Uppercase","inputs":[1]},{"method":"Standardizer.MapCharacter","label":"Map equivalent Character","map_resource":"person_map_character_general","inputs":[1]},{"method":"Standardizer.Tokenizer","delimiters":[" ","-","/",",","."],"label":"Tokenization","inputs":[1]},{"method":"Standardizer.ParseToken","fields":["given_name","full_name","middle_name","last_name","prefix","suffix","generation"],"drop_unparsed_values":false,"label":"Parse Token","map_resource":"person_map_name_alignments","inputs":[1]},{"method":"Standardizer.Length","min_length":2,"max_length":100,"fields":["last_name"],"label":"Remove single characters from last name","inputs":[1]},{"method":"Standardizer.StopToken","fields":["last_name","given_name","middle_name","prefix","suffix","generation","full_name"],"label":"Stop anonymous token","set_resource":"person_set_name_aname","inputs":[1]},{"method":"Standardizer.PickToken","fields":["last_name","given_name","middle_name","prefix","suffix","generation","full_name"],"unique_tokens":true,"label":"Pick Token","inputs":[1]}]}}}" 
Copy to clipboard

Example request

AlgorithmStandardizerStep algorithmStandardizerStepModel = new AlgorithmStandardizerStep.Builder()
  .label("testString")
  .method("testString")
  .build();
AlgorithmInput algorithmInputModel = new AlgorithmInput.Builder()
  .attributes(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .fields(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .build();
AlgorithmStandardizer algorithmStandardizerModel = new AlgorithmStandardizer.Builder()
  .label("testString")
  .standardizerRecipe(new java.util.ArrayList<AlgorithmStandardizerStep>(java.util.Arrays.asList(algorithmStandardizerStepModel)))
  .inputs(new java.util.ArrayList<AlgorithmInput>(java.util.Arrays.asList(algorithmInputModel)))
  .build();
AlgorithmEncryption algorithmEncryptionModel = new AlgorithmEncryption.Builder()
  .subType("testString")
  .pubKey(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .enabled(true)
  .type("testString")
  .build();
AlgorithmEntityType algorithmEntityTypeModel = new AlgorithmEntityType.Builder()
  .autoLinkThreshold(Float.valueOf("36.0"))
  .build();
UpdateModelAlgorithmOptions updateModelAlgorithmOptions = new UpdateModelAlgorithmOptions.Builder()
  .recordType("testString")
  .standardizers(new java.util.HashMap<String, AlgorithmStandardizer>() { { put("foo", algorithmStandardizerModel); } })
  .encryption(algorithmEncryptionModel)
  .entityTypes(new java.util.HashMap<String, AlgorithmEntityType>() { { put("foo", algorithmEntityTypeModel); } })
  .locale("testString")
  .build();

Response<PutAlgorithm> response = mdmService.updateModelAlgorithm(updateModelAlgorithmOptions).execute();
PutAlgorithm putAlgorithm = response.getResult();

System.out.println(putAlgorithm);
Copy to clipboard

Response

Response Body

PutAlgorithm

Response wrapper object for overwriting matching algorithm

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

Status 200

{
  "flow_state": "published",
  "flow_id": "135208",
  "algorithm": {}
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_id": "135208",
  "algorithm": {}
}
Copy to clipboard

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.

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}

ServiceCall<CompareSpecResource> getModelComparespecResource(GetModelComparespecResourceOptions getModelComparespecResourceOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetModelComparespecResourceOptions.Builder to create a GetModelComparespecResourceOptions object that contains the parameter values for the getModelComparespecResource method.

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.

GetModelComparespecResourceOptions

The getModelComparespecResource options.

Retrieve details of comparison parameters

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/compare_spec_resources/person_compare_spec_email?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetModelComparespecResourceOptions getModelComparespecResourceOptions = new GetModelComparespecResourceOptions.Builder()
  .resourceName("testString")
  .build();

Response<CompareSpecResource> response = mdmService.getModelComparespecResource(getModelComparespecResourceOptions).execute();
CompareSpecResource compareSpecResource = response.getResult();

System.out.println(compareSpecResource);

Response

Response Body

CompareSpecResource

A single comparison resource used to customize comparison logic of a matching algorithm

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

Status 200

{
  "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
  }
}
Copy to clipboard

Success example

{
  "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
  }
}
Copy to clipboard

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.

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}

ServiceCall<PutCompareSpecResources> replaceModelComparespecResource(ReplaceModelComparespecResourceOptions replaceModelComparespecResourceOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceModelComparespecResourceOptions.Builder to create a ReplaceModelComparespecResourceOptions object that contains the parameter values for the replaceModelComparespecResource method.

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

ReplaceModelComparespecResourceOptions

The replaceModelComparespecResource options.

Overwrite the comparison parameters

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/compare_spec_resources/person_compare_spec_email?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"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}}" 
Copy to clipboard

Example request

CompareSpecResourceFeatureCategory compareSpecResourceFeatureCategoryModel = new CompareSpecResourceFeatureCategory.Builder()
  .build();
ReplaceModelComparespecResourceOptions replaceModelComparespecResourceOptions = new ReplaceModelComparespecResourceOptions.Builder()
  .resourceName("testString")
  .featureCategories(new java.util.HashMap<String, CompareSpecResourceFeatureCategory>() { { put("foo", compareSpecResourceFeatureCategoryModel); } })
  .typoDistance(Float.valueOf("36.0"))
  .featureCoefficients(new java.util.HashMap<String, Float>() { { put("foo", Float.valueOf("36.0")); } })
  .build();

Response<PutCompareSpecResources> response = mdmService.replaceModelComparespecResource(replaceModelComparespecResourceOptions).execute();
PutCompareSpecResources putCompareSpecResources = response.getResult();

System.out.println(putCompareSpecResources);
Copy to clipboard

Response

Response Body

PutCompareSpecResources

Response wrapper object for overwriting comparison resource

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

Status 200

{
  "flow_state": "published",
  "compare_spec_resources": {}
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "compare_spec_resources": {}
}
Copy to clipboard

This service retrieves the list of specification names for the existing comparison parameters.

This service retrieves the list of specification names for the existing comparison parameters.

GET /mdm/v1/compare_spec_resources

ServiceCall<CompareSpecResourceNames> listModelComparespecResoures(ListModelComparespecResouresOptions listModelComparespecResouresOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListModelComparespecResouresOptions.Builder to create a ListModelComparespecResouresOptions object that contains the parameter values for the listModelComparespecResoures method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Retrieve a summary of all comparison parameters

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/model/v1/compare_spec_resources?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListModelComparespecResouresOptions listModelComparespecResouresOptions = new ListModelComparespecResouresOptions();

Response<CompareSpecResourceNames> response = mdmService.listModelComparespecResoures(listModelComparespecResouresOptions).execute();
CompareSpecResourceNames compareSpecResourceNames = response.getResult();

System.out.println(compareSpecResourceNames);

Response

Response Body

CompareSpecResourceNames

Response wrapper object for all comparison resource names

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

Status 200

{
  "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"
  ]
}
Copy to clipboard

Success example

{
  "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"
  ]
}
Copy to clipboard

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.

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}

ServiceCall<Map<String, List<MapResourceEntry>>> getModelMapResource(GetModelMapResourceOptions getModelMapResourceOptions)

Authorization

To call this method, 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

Use the GetModelMapResourceOptions.Builder to create a GetModelMapResourceOptions object that contains the parameter values for the getModelMapResource method.

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.

GetModelMapResourceOptions

The getModelMapResource options.

Retrieve details of equivalency criteria

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/map_resources/person_map_address_country?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetModelMapResourceOptions getModelMapResourceOptions = new GetModelMapResourceOptions.Builder()
  .resourceName("testString")
  .build();

Response<Map<String, List<MapResourceEntry>>> response = mdmService.getModelMapResource(getModelMapResourceOptions).execute();
Map<String, List<MapResourceEntry>> mapStringListMapResourceEntry = response.getResult();

System.out.println(mapStringListMapResourceEntry);

Response

Response type: Map<String, List<MapResourceEntry>>

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

Status 200

{
  "country": [
    {
      "category": "",
      "key": "USA",
      "values": [
        "UNITED STATES",
        "UNITED STATES OF AMERICA",
        "US"
      ],
      "regex": []
    },
    {
      "category": "",
      "key": "UK",
      "values": [
        "GREAT BRITAIN",
        "UNITED KINGDOM"
      ],
      "regex": []
    }
  ]
}
Copy to clipboard

Success example

{
  "country": [
    {
      "category": "",
      "key": "USA",
      "values": [
        "UNITED STATES",
        "UNITED STATES OF AMERICA",
        "US"
      ],
      "regex": []
    },
    {
      "category": "",
      "key": "UK",
      "values": [
        "GREAT BRITAIN",
        "UNITED KINGDOM"
      ],
      "regex": []
    }
  ]
}
Copy to clipboard

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.

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}

ServiceCall<PutMapResources> replaceModelMapResource(ReplaceModelMapResourceOptions replaceModelMapResourceOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceModelMapResourceOptions.Builder to create a ReplaceModelMapResourceOptions object that contains the parameter values for the replaceModelMapResource method.

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)

ReplaceModelMapResourceOptions

The replaceModelMapResource options.

Overwrite equivalency criteria

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/map_resources/person_map_address_country?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"country":[{"category":"","key":"USA","values":["UNITED STATES","UNITED STATES OF AMERICA","US"],"regex":[]},{"category":"","key":"UK","values":["GREAT BRITAIN","UNITED KINGDOM"],"regex":[]}]}" 
Copy to clipboard

Example request

MapResourceEntry mapResourceEntryModel = new MapResourceEntry.Builder()
  .regex(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .values(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .build();
ReplaceModelMapResourceOptions replaceModelMapResourceOptions = new ReplaceModelMapResourceOptions.Builder()
  .resourceName("testString")
  .requestBody(new java.util.HashMap<String, List<MapResourceEntry>>() { { put("foo", new java.util.ArrayList<MapResourceEntry>(java.util.Arrays.asList(mapResourceEntryModel))); } })
  .build();

Response<PutMapResources> response = mdmService.replaceModelMapResource(replaceModelMapResourceOptions).execute();
PutMapResources putMapResources = response.getResult();

System.out.println(putMapResources);
Copy to clipboard

Response

Response Body

PutMapResources

Response wrapper object for overwriting map resource

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

Status 200

{
  "flow_state": "published",
  "flow_id": "172056",
  "map_resources": {}
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_id": "172056",
  "map_resources": {}
}
Copy to clipboard

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.

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

ServiceCall<MapResourceNames> listModelMapResources(ListModelMapResourcesOptions listModelMapResourcesOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListModelMapResourcesOptions.Builder to create a ListModelMapResourcesOptions object that contains the parameter values for the listModelMapResources method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Retrieve a summary of all equivalency criteria

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/map_resources?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListModelMapResourcesOptions listModelMapResourcesOptions = new ListModelMapResourcesOptions();

Response<MapResourceNames> response = mdmService.listModelMapResources(listModelMapResourcesOptions).execute();
MapResourceNames mapResourceNames = response.getResult();

System.out.println(mapResourceNames);

Response

Response Body

MapResourceNames

Response wrapper object for all map resource names

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

Status 200

{
  "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"
  ]
}
Copy to clipboard

Success example

{
  "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"
  ]
}
Copy to clipboard

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.

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

ServiceCall<SetResourceNames> listModelSetResources(ListModelSetResourcesOptions listModelSetResourcesOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ListModelSetResourcesOptions.Builder to create a ListModelSetResourcesOptions object that contains the parameter values for the listModelSetResources method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Retrieve a summary of all anonymous words

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/set_resources?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListModelSetResourcesOptions listModelSetResourcesOptions = new ListModelSetResourcesOptions();

Response<SetResourceNames> response = mdmService.listModelSetResources(listModelSetResourcesOptions).execute();
SetResourceNames setResourceNames = response.getResult();

System.out.println(setResourceNames);

Response

Response Body

SetResourceNames

Response object wrapper for all set resource names

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

Status 200

{
  "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"
  ]
}
Copy to clipboard

Success example

{
  "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"
  ]
}
Copy to clipboard

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.

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}

ServiceCall<Map<String, SetResourceEntry>> getModelSetResource(GetModelSetResourceOptions getModelSetResourceOptions)

Authorization

To call this method, 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

Use the GetModelSetResourceOptions.Builder to create a GetModelSetResourceOptions object that contains the parameter values for the getModelSetResource method.

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.

GetModelSetResourceOptions

The getModelSetResource options.

Retrieve details of anonymous words

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/set_resources/person_set_character_date?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetModelSetResourceOptions getModelSetResourceOptions = new GetModelSetResourceOptions.Builder()
  .resourceName("testString")
  .build();

Response<Map<String, SetResourceEntry>> response = mdmService.getModelSetResource(getModelSetResourceOptions).execute();
Map<String, SetResourceEntry> mapStringSetResourceEntry = response.getResult();

System.out.println(mapStringSetResourceEntry);

Response

Response type: Map<String, SetResourceEntry>

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

Status 200

{
  "date": {
    "values": [
      "-"
    ],
    "regex": []
  }
}
Copy to clipboard

Success example

{
  "date": {
    "values": [
      "-"
    ],
    "regex": []
  }
}
Copy to clipboard

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.

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}

ServiceCall<PutSetResources> replaceModelSetResource(ReplaceModelSetResourceOptions replaceModelSetResourceOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceModelSetResourceOptions.Builder to create a ReplaceModelSetResourceOptions object that contains the parameter values for the replaceModelSetResource method.

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)

ReplaceModelSetResourceOptions

The replaceModelSetResource options.

Overwrite anonymous words

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/set_resources/person_set_character_date?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&resource_name=test" --data "{"date":{"values":["-"],"regex":[]}}" 
Copy to clipboard

Example request

SetResourceEntry setResourceEntryModel = new SetResourceEntry.Builder()
  .regex(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .values(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .build();
ReplaceModelSetResourceOptions replaceModelSetResourceOptions = new ReplaceModelSetResourceOptions.Builder()
  .resourceName("testString")
  .requestBody(new java.util.HashMap<String, SetResourceEntry>() { { put("foo", setResourceEntryModel); } })
  .build();

Response<PutSetResources> response = mdmService.replaceModelSetResource(replaceModelSetResourceOptions).execute();
PutSetResources putSetResources = response.getResult();

System.out.println(putSetResources);
Copy to clipboard

Response

Response Body

PutSetResources

Response wrapper object for overwriting set resource

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

Status 200

{
  "flow_state": "published",
  "flow_id": "172056",
  "set_resources": {
    "date": {
      "regex": [],
      "values": [
        "-"
      ]
    }
  }
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_id": "172056",
  "set_resources": {
    "date": {
      "regex": [],
      "values": [
        "-"
      ]
    }
  }
}
Copy to clipboard

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.

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

ServiceCall<CompositeRules> getModelCompositeRules(GetModelCompositeRulesOptions getModelCompositeRulesOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetModelCompositeRulesOptions.Builder to create a GetModelCompositeRulesOptions object that contains the parameter values for the getModelCompositeRules method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Retrieve the survivorship composite rules

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/composite_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetModelCompositeRulesOptions getModelCompositeRulesOptions = new GetModelCompositeRulesOptions();

Response<CompositeRules> response = mdmService.getModelCompositeRules(getModelCompositeRulesOptions).execute();
CompositeRules compositeRules = response.getResult();

System.out.println(compositeRules);

Response

Response Body

CompositeRules

The wrapper object of composite rules

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

Status 200

{
  "locale": "en_us",
  "rules": {
    "global": {
      "choices": [
        "mca",
        "mfa"
      ],
      "sources": []
    }
  }
}
Copy to clipboard

Success example

{
  "locale": "en_us",
  "rules": {
    "global": {
      "choices": [
        "mca",
        "mfa"
      ],
      "sources": []
    }
  }
}
Copy to clipboard

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.

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

ServiceCall<PutCompositeRules> replaceModelCompositeRules(ReplaceModelCompositeRulesOptions replaceModelCompositeRulesOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceModelCompositeRulesOptions.Builder to create a ReplaceModelCompositeRulesOptions object that contains the parameter values for the replaceModelCompositeRules method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

CompositeRules

The wrapper object of composite rules

ReplaceModelCompositeRulesOptions

The replaceModelCompositeRules options.

Overwrite the survivorship composite rules

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/composite_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"locale":"en_us","rules":{"global":{"choices":["mca","source"],"sources":["src1","src5","src2"]}}}" 
Copy to clipboard

Example request

CompositeRulesRule compositeRulesRuleModel = new CompositeRulesRule.Builder()
  .sources(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .choices(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .build();
CompositeRulesRules compositeRulesRulesModel = new CompositeRulesRules.Builder()
  .global(compositeRulesRuleModel)
  .build();
ReplaceModelCompositeRulesOptions replaceModelCompositeRulesOptions = new ReplaceModelCompositeRulesOptions.Builder()
  .rules(compositeRulesRulesModel)
  .locale("testString")
  .build();

Response<PutCompositeRules> response = mdmService.replaceModelCompositeRules(replaceModelCompositeRulesOptions).execute();
PutCompositeRules putCompositeRules = response.getResult();

System.out.println(putCompositeRules);
Copy to clipboard

Response

Response Body

PutCompositeRules

Response wrapper object for overwriting composite rules

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

Status 200

{
  "flow_state": "published",
  "flow_id": "172056",
  "composite_rules": {}
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_id": "172056",
  "composite_rules": {}
}
Copy to clipboard

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

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

ServiceCall<DataModel> getModelDataModel(GetModelDataModelOptions getModelDataModelOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetModelDataModelOptions.Builder to create a GetModelDataModelOptions object that contains the parameter values for the getModelDataModel method.

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

GetModelDataModelOptions

The getModelDataModel options.

Retrieve the data model

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/data_model?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&version=current" 
Copy to clipboard

Example request

GetModelDataModelOptions getModelDataModelOptions = new GetModelDataModelOptions.Builder()
  .build();

Response<DataModel> response = mdmService.getModelDataModel(getModelDataModelOptions).execute();
DataModel dataModel = response.getResult();

System.out.println(dataModel);

Response

Response Body

DataModel

Collection of record and relationship types definition

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

Status 200

{
  "locale": "en_us",
  "system_properties": {},
  "record_types": {},
  "attribute_types": {},
  "relationship_types": {}
}
Copy to clipboard

Success example

{
  "locale": "en_us",
  "system_properties": {},
  "record_types": {},
  "attribute_types": {},
  "relationship_types": {}
}
Copy to clipboard

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

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

ServiceCall<PutDataModel> replaceModelDataModel(ReplaceModelDataModelOptions replaceModelDataModelOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceModelDataModelOptions.Builder to create a ReplaceModelDataModelOptions object that contains the parameter values for the replaceModelDataModel method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

DataModel

Collection of record and relationship types definition

ReplaceModelDataModelOptions

The replaceModelDataModel options.

Overwrite the data model

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/data_model?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"locale":"en_us","system_properties":{"record_types":{"collection_id":{"label":"Collection ID","description":"Optional identifier for identifying a collection of records","data_type":"String","editable":true,"indexed":true},"record_source":{"label":"Record source","description":"A user provided record source.","data_type":"String","editable":true,"indexed":true},"record_id":{"label":"Record identifier","description":"User provided or autogenerated record identifier","data_type":"String","editable":true,"indexed":true},"record_number":{"label":"System record number","description":"System generated record number","data_type":"String","editable":false,"indexed":true},"record_last_updated":{"label":"Record last updated","description":"System generated record last updated","data_type":"Long","editable":false,"indexed":true}},"entity_types":{"entity_id":{"label":"Entity identifier","data_type":"String","editable":false,"indexed":true},"entity_last_updated":{"label":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}},"attribute_types":{"attribute_last_updated":{"label":"Attribute last updated date","description":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}},"relationship_types":{"relationship_last_updated":{"label":"Relationship last updated date","description":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}}},"record_types":{"person":{"label":"Person","description":"The record type for person records.","entity_types":{"person_entity":{"label":"Person Entity","description":"The entity type for person records."}},"attributes":{"birth_date":{"label":"Birth Date","description":"The birth date associated with this person record.","attribute_type":"string","classification":"","cardinality":"LIST","indexed":true,"matching_type":"DATE"},"gender":{"label":"Gender","description":"The gender of the the person associated with this record.","attribute_type":"string","classification":"","cardinality":"LIST","indexed":true,"matching_type":"GENDER"},"primary_residence":{"label":"Primary Residence","description":"Indicates that this address is a primary residence.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"mailing_address":{"label":"Mailing Address","description":"Indicates that this address is a mailing address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"home_telephone":{"label":"Home Telephone","description":"Indicates that this phone number is for a home telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"mobile_telephone":{"label":"Mobile Telephone","description":"Indicates that this phone number is for a mobile telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"personal_email":{"label":"Personal Email","description":"Indicates that this email address is a personal email address.","attribute_type":"email","classification":"","cardinality":"LIST","indexed":true},"twitter":{"label":"twitter","description":"Indicates that this social media type is Twitter.","attribute_type":"social_media","classification":"","cardinality":"LIST","indexed":true},"drivers_licence":{"label":"Driver''s Licence","description":"Indicates that this identifier is a driver's license.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"passport":{"label":"passport","description":"Indicates that this identifier is a passport.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"credit_card":{"label":"Credit Card","description":"Indicates that this identifier is a credit card.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"PAYMENTCARDNUMBER"},"social_insurance_number":{"label":"Social Insurance Number","description":"Indicates that this identifier is a social insurance number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"legal_name":{"label":"Legal Name","description":"Indicates that this name is a legal name.","attribute_type":"person_name","classification":"","cardinality":"LIST","indexed":true},"previous_name":{"label":"Previous Name","description":"Indicates that this name is a previous name.","attribute_type":"person_name","classification":"","cardinality":"LIST","indexed":true}}},"organization":{"label":"Organization","description":"The record type for organization records.","entity_types":{},"attributes":{"business_name":{"label":"Business Name","description":"Indicates that this name is a business name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"doing_business_as":{"label":"Doing Business As","description":"Indicates that this name is a Doing Business As name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"abbreviated_name":{"label":"Abbreviated Name","description":"Indicates that this name is an abbreviated name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"business_address":{"label":"Business Address","description":"Indicates that this address is a business address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"mailing_address":{"label":"Mailing Address","description":"Indicates that this address is a mailing address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"business_telephone":{"label":"Business Telephone","description":"Indicates that this phone number is for a business telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"business_email":{"label":"Business Email","description":"Indicates that this email address is a business email.","attribute_type":"email","classification":"","cardinality":"LIST","indexed":true},"business_tax_identification":{"label":"Business Tax Identification","description":"Indicates that this identifier is a business tax identification number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"duns":{"label":"DUNS","description":"Indicates that this identifier is a D-U-N-S Number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"}}}},"attribute_types":{"address":{"label":"Party Address","description":"The address locations associated with a record. Only one address per usage value is allowed. For example, there can only be one mailing address for a contact.","classification":"","matching_types":["ADDRESS"],"fields":{"residence":{"label":"Residence Value","description":"The type of residence for this address, such as home, apartment, or suite.","classification":"","indexed":true},"address_line1":{"label":"Address Line 1","description":"The first line of this address.","classification":"","indexed":true},"address_line2":{"label":"Address Line 2","description":"The second line of this address.","classification":"","indexed":true},"address_line3":{"label":"Address Line 3","description":"The third line of this address.","classification":"","indexed":true},"city":{"label":"City","description":"The city of this address.","classification":"","indexed":true},"zip_postal_code":{"label":"Postal Code","description":"The postal code of this address.","classification":"","indexed":true},"residence_number":{"label":"Residence Number","description":"The residence number of this address.","classification":"","indexed":true},"province_state":{"label":"State/Province Value","description":"The state or province of this address.","classification":"","indexed":true},"county":{"label":"County","description":"The county of this address.","classification":"","indexed":true},"country":{"label":"Country Value","description":"The country of this address.","classification":"","indexed":true},"latitude_degrees":{"label":"Latitude Degrees","description":"The latitude of this address.","classification":"","indexed":true},"longitude_degrees":{"label":"Longitude Degrees","description":"The longitude of this address.","classification":"","indexed":true}}},"telephone":{"label":"Party Contact Method","description":"The ways that an entity can be reached. Some examples include email addresses, phone numbers, and social media. ","classification":"","matching_types":["PHONE"],"fields":{"phone_number":{"label":"Phone Number","description":"The text or number string provided for this contact method. For example, if the contact method type is telephone, then this column contains the digits for the phone number.","classification":"","indexed":true}}},"email":{"label":"Party Email","description":"The ways that an entity can be reached. Some examples include email addresses, phone numbers, and social media. ","classification":"","matching_types":["EMAIL"],"fields":{"email_id":{"label":"Email Id","description":"The text or number string provided for this contact method. For example, if the contact method type is telephone, then this column contains the digits for the phone number.","classification":"","indexed":true}}},"social_media":{"label":"Party Social Media","description":"The ways that an entity can be reached. Some examples include email addresses, phone numbers, and social media. ","classification":"","matching_types":["SOCIALMEDIA"],"fields":{"social_media_handle":{"label":"Social Media Handle","description":"The text or number string provided for this contact method. For example, if the contact method type is telephone, then this column contains the digits for the phone number.","classification":"","indexed":true}}},"identification":{"label":"identification","description":"A unique identifier that can be used to distinguish a party from others.","classification":"","matching_types":["NATIONALIDENTIFIER","PAYMENTCARDNUMBER","OTHERIDENTIFIER"],"fields":{"identification_number":{"label":"Identification Number","description":"The actual alphanumeric identifier. For example, if the identification type indicates a social security number, then this value contains the 9 characters of the social security number.","classification":"","indexed":true}}},"person_name":{"label":"Person Name","description":"Information about a name associated with a person record.","classification":"","matching_types":["PERSONNAME"],"fields":{"generation":{"label":"Generation Value","description":"Identifies familial generational information in the form of a generation type. Examples include The First, The Second, Junior or Senior.","classification":"","indexed":true},"prefix":{"label":"Prefix Value","description":"The name prefix, such as Mr, Mrs, Miss, Dr, and others.","classification":"","indexed":true},"given_name":{"label":"Given Name","description":"The first given name of a person. Commonly known as the first name.","classification":"","indexed":true},"middle_name":{"label":"Middle Name","description":"The second given name of a person. Commonly known as the middle name.","classification":"","indexed":true},"last_name":{"label":"Last Name","description":"The surname or family name of a person. Commonly known as the last name.","classification":"","indexed":true},"suffix":{"label":"suffix","description":"The name suffix, such as Jr, MD, Esq, PhD, and others.","classification":"","indexed":true},"full_name":{"label":"Full name","description":"","classification":"","indexed":true}}},"organization_name":{"label":"Organization Name","description":"Information about a name associated with an organization record.","classification":"","matching_types":["ORGNAME"],"fields":{"name":{"label":"name","description":"The organization name.","classification":"","indexed":true}}},"string":{"label":"Simple attribute","description":"A single field primitive attribute","classification":"","fields":{"value":{"label":"Value","description":"","classification":"","indexed":true}}}},"relationship_types":{"linkage":{"label":"Linkage","label_from_source":"Linked into","label_from_target":"Linked from","description":"This is the built in linkage relationship type the matching engine creates between records and their resolved entities","cardinality":"ONE2MANY","directional":true}}}" 
Copy to clipboard

Example request

DataModelRelationshipType dataModelRelationshipTypeModel = new DataModelRelationshipType.Builder()
  .label("testString")
  .build();
DataModelField dataModelFieldModel = new DataModelField.Builder()
  .label("testString")
  .build();
DataModelAttributeType dataModelAttributeTypeModel = new DataModelAttributeType.Builder()
  .label("testString")
  .fields(new java.util.HashMap<String, DataModelField>() { { put("foo", dataModelFieldModel); } })
  .build();
DataModelAttribute dataModelAttributeModel = new DataModelAttribute.Builder()
  .label("testString")
  .attributeType("testString")
  .build();
DataModelRecordType dataModelRecordTypeModel = new DataModelRecordType.Builder()
  .label("testString")
  .attributes(new java.util.HashMap<String, DataModelAttribute>() { { put("foo", dataModelAttributeModel); } })
  .build();
DataModelSystemProperty dataModelSystemPropertyModel = new DataModelSystemProperty.Builder()
  .label("testString")
  .dataType("testString")
  .build();
DataModelRelationshipTypeSystemProperties dataModelRelationshipTypeSystemPropertiesModel = new DataModelRelationshipTypeSystemProperties.Builder()
  .relationshipLastUpdated(dataModelSystemPropertyModel)
  .build();
DataModelAttributeTypeSystemProperties dataModelAttributeTypeSystemPropertiesModel = new DataModelAttributeTypeSystemProperties.Builder()
  .attributeLastUpdated(dataModelSystemPropertyModel)
  .build();
DataModelRecordTypeSystemProperties dataModelRecordTypeSystemPropertiesModel = new DataModelRecordTypeSystemProperties.Builder()
  .recordId(dataModelSystemPropertyModel)
  .collectionId(dataModelSystemPropertyModel)
  .recordSource(dataModelSystemPropertyModel)
  .recordLastUpdated(dataModelSystemPropertyModel)
  .recordNumber(dataModelSystemPropertyModel)
  .build();
DataModelEntityTypeSystemProperties dataModelEntityTypeSystemPropertiesModel = new DataModelEntityTypeSystemProperties.Builder()
  .entityId(dataModelSystemPropertyModel)
  .entityLastUpdated(dataModelSystemPropertyModel)
  .build();
DataModelSystemProperties dataModelSystemPropertiesModel = new DataModelSystemProperties.Builder()
  .relationshipTypes(dataModelRelationshipTypeSystemPropertiesModel)
  .attributeTypes(dataModelAttributeTypeSystemPropertiesModel)
  .recordTypes(dataModelRecordTypeSystemPropertiesModel)
  .entityTypes(dataModelEntityTypeSystemPropertiesModel)
  .build();
ReplaceModelDataModelOptions replaceModelDataModelOptions = new ReplaceModelDataModelOptions.Builder()
  .relationshipTypes(new java.util.HashMap<String, DataModelRelationshipType>() { { put("foo", dataModelRelationshipTypeModel); } })
  .attributeTypes(new java.util.HashMap<String, DataModelAttributeType>() { { put("foo", dataModelAttributeTypeModel); } })
  .recordTypes(new java.util.HashMap<String, DataModelRecordType>() { { put("foo", dataModelRecordTypeModel); } })
  .systemProperties(dataModelSystemPropertiesModel)
  .locale("testString")
  .build();

Response<PutDataModel> response = mdmService.replaceModelDataModel(replaceModelDataModelOptions).execute();
PutDataModel putDataModel = response.getResult();

System.out.println(putDataModel);
Copy to clipboard

Response

Response Body

PutDataModel

Response wrapper object for overwritting data model

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

Status 200

{
  "flow_state": "draft",
  "flow_id": "41017488",
  "data_model": {
    "locale": "en_us",
    "system_properties": {},
    "record_types": {},
    "attribute_types": {},
    "relationship_types": {}
  }
}
Copy to clipboard

Success example

{
  "flow_state": "draft",
  "flow_id": "41017488",
  "data_model": {
    "locale": "en_us",
    "system_properties": {},
    "record_types": {},
    "attribute_types": {},
    "relationship_types": {}
  }
}
Copy to clipboard

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

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

ServiceCall<PutDataModel> updateModelDataModel(UpdateModelDataModelOptions updateModelDataModelOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the UpdateModelDataModelOptions.Builder to create a UpdateModelDataModelOptions object that contains the parameter values for the updateModelDataModel method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

DataModel

Collection of record and relationship types definition

UpdateModelDataModelOptions

The updateModelDataModel options.

Partially modify the data model

curl -X PATCH --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/data_model?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"attribute_types":{"third_string":{"label":"Second complex attribute","description":"A single field complex attribute","classification":"","fields":{"value":{"label":"Value","description":"","classification":"","indexed":true}}}}}" 
Copy to clipboard

Example request

DataModelRelationshipType dataModelRelationshipTypeModel = new DataModelRelationshipType.Builder()
  .label("testString")
  .build();
DataModelField dataModelFieldModel = new DataModelField.Builder()
  .label("testString")
  .build();
DataModelAttributeType dataModelAttributeTypeModel = new DataModelAttributeType.Builder()
  .label("testString")
  .fields(new java.util.HashMap<String, DataModelField>() { { put("foo", dataModelFieldModel); } })
  .build();
DataModelAttribute dataModelAttributeModel = new DataModelAttribute.Builder()
  .label("testString")
  .attributeType("testString")
  .build();
DataModelRecordType dataModelRecordTypeModel = new DataModelRecordType.Builder()
  .label("testString")
  .attributes(new java.util.HashMap<String, DataModelAttribute>() { { put("foo", dataModelAttributeModel); } })
  .build();
DataModelSystemProperty dataModelSystemPropertyModel = new DataModelSystemProperty.Builder()
  .label("testString")
  .dataType("testString")
  .build();
DataModelRelationshipTypeSystemProperties dataModelRelationshipTypeSystemPropertiesModel = new DataModelRelationshipTypeSystemProperties.Builder()
  .relationshipLastUpdated(dataModelSystemPropertyModel)
  .build();
DataModelAttributeTypeSystemProperties dataModelAttributeTypeSystemPropertiesModel = new DataModelAttributeTypeSystemProperties.Builder()
  .attributeLastUpdated(dataModelSystemPropertyModel)
  .build();
DataModelRecordTypeSystemProperties dataModelRecordTypeSystemPropertiesModel = new DataModelRecordTypeSystemProperties.Builder()
  .recordId(dataModelSystemPropertyModel)
  .collectionId(dataModelSystemPropertyModel)
  .recordSource(dataModelSystemPropertyModel)
  .recordLastUpdated(dataModelSystemPropertyModel)
  .recordNumber(dataModelSystemPropertyModel)
  .build();
DataModelEntityTypeSystemProperties dataModelEntityTypeSystemPropertiesModel = new DataModelEntityTypeSystemProperties.Builder()
  .entityId(dataModelSystemPropertyModel)
  .entityLastUpdated(dataModelSystemPropertyModel)
  .build();
DataModelSystemProperties dataModelSystemPropertiesModel = new DataModelSystemProperties.Builder()
  .relationshipTypes(dataModelRelationshipTypeSystemPropertiesModel)
  .attributeTypes(dataModelAttributeTypeSystemPropertiesModel)
  .recordTypes(dataModelRecordTypeSystemPropertiesModel)
  .entityTypes(dataModelEntityTypeSystemPropertiesModel)
  .build();
UpdateModelDataModelOptions updateModelDataModelOptions = new UpdateModelDataModelOptions.Builder()
  .relationshipTypes(new java.util.HashMap<String, DataModelRelationshipType>() { { put("foo", dataModelRelationshipTypeModel); } })
  .attributeTypes(new java.util.HashMap<String, DataModelAttributeType>() { { put("foo", dataModelAttributeTypeModel); } })
  .recordTypes(new java.util.HashMap<String, DataModelRecordType>() { { put("foo", dataModelRecordTypeModel); } })
  .systemProperties(dataModelSystemPropertiesModel)
  .locale("testString")
  .build();

Response<PutDataModel> response = mdmService.updateModelDataModel(updateModelDataModelOptions).execute();
PutDataModel putDataModel = response.getResult();

System.out.println(putDataModel);
Copy to clipboard

Response

Response Body

PutDataModel

Response wrapper object for overwritting data model

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

Status 200

{
  "flow_state": "published",
  "flow_id": "135208",
  "data_model": {}
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_id": "135208",
  "data_model": {}
}
Copy to clipboard

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

Status 200

{
  "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
    }
  ]
}
Copy to clipboard

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

Status 200

{
  "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"
}
Copy to clipboard

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

{}

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.

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

Status 200

{
  "flows": [
    {
      "flow_state": "draft",
      "flow_type": "data_model",
      "rejections": [],
      "flow_id": "327733440",
      "approvals": [],
      "active": true
    }
  ]
}
Copy to clipboard

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.

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}

ServiceCall<Flow> getModelFlow(GetModelFlowOptions getModelFlowOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetModelFlowOptions.Builder to create a GetModelFlowOptions object that contains the parameter values for the getModelFlow method.

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.

GetModelFlowOptions

The getModelFlow options.

Example request

GetModelFlowOptions getModelFlowOptions = new GetModelFlowOptions.Builder()
  .flowId("testString")
  .build();

Response<Flow> response = mdmService.getModelFlow(getModelFlowOptions).execute();
Flow flow = response.getResult();

System.out.println(flow);

Response

Response Body

Flow

Response wrapper object for retrieving a flow

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

Status 200

{
  "flow_state": "published",
  "flow_type": "data_model",
  "rejections": [],
  "flow_id": "192696",
  "approvals": [],
  "active": false
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_type": "data_model",
  "rejections": [],
  "flow_id": "192696",
  "approvals": [],
  "active": false
}
Copy to clipboard

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

{}

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.

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}

ServiceCall<Flow> updateModelFlow(UpdateModelFlowOptions updateModelFlowOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the UpdateModelFlowOptions.Builder to create a UpdateModelFlowOptions object that contains the parameter values for the updateModelFlow method.

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

UpdateModelFlowOptions

The updateModelFlow options.

Example request

UpdateModelFlowOptions updateModelFlowOptions = new UpdateModelFlowOptions.Builder()
  .flowId("testString")
  .approverName("testString")
  .action("testString")
  .build();

Response<Flow> response = mdmService.updateModelFlow(updateModelFlowOptions).execute();
Flow flow = response.getResult();

System.out.println(flow);
Copy to clipboard

Response

Response Body

Flow

Response wrapper object for retrieving a flow

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

Status 200

{
  "flow_state": "published",
  "flow_type": "data_model",
  "rejections": [],
  "flow_id": "192696",
  "approvals": [],
  "active": false
}
Copy to clipboard

Success example

{
  "flow_state": "published",
  "flow_type": "data_model",
  "rejections": [],
  "flow_id": "192696",
  "approvals": [],
  "active": false
}
Copy to clipboard

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

Status 200

{
  "masked_columns": [
    {
      "masked_type": "obfuscate",
      "masked_column": "drivers_licence.identification_number"
    },
    {
      "masked_type": "substitute",
      "masked_column": "legal_name.last_nam"
    }
  ]
}
Copy to clipboard

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

Status 200

{
  "entity_types": {
    "person_entity": {
      "asset_id": "723383939"
    }
  },
  "record_types": {
    "person": {
      "asset_id": "1262727272"
    }
  }
}
Copy to clipboard

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.

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

ServiceCall<InstanceMetadataResponse> getModelInstanceMetadata(GetModelInstanceMetadataOptions getModelInstanceMetadataOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the GetModelInstanceMetadataOptions.Builder to create a GetModelInstanceMetadataOptions object that contains the parameter values for the getModelInstanceMetadata method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Retrieve the configured metadata

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/instance_metadata?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetModelInstanceMetadataOptions getModelInstanceMetadataOptions = new GetModelInstanceMetadataOptions();

Response<InstanceMetadataResponse> response = mdmService.getModelInstanceMetadata(getModelInstanceMetadataOptions).execute();
InstanceMetadataResponse instanceMetadataResponse = response.getResult();

System.out.println(instanceMetadataResponse);

Response

Response Body

InstanceMetadataResponse

Wrapper object for instance metadata response

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

Status 200

{
  "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"
}
Copy to clipboard

Success example

{
  "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"
}
Copy to clipboard

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.

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

ServiceCall<InstanceMetadataResponse> replaceModelInstanceMetadata(ReplaceModelInstanceMetadataOptions replaceModelInstanceMetadataOptions)
Copy to clipboard

Authorization

To call this method, 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

Use the ReplaceModelInstanceMetadataOptions.Builder to create a ReplaceModelInstanceMetadataOptions object that contains the parameter values for the replaceModelInstanceMetadata method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

InstanceMetadata

Wrapper object for instance metadata

ReplaceModelInstanceMetadataOptions

The replaceModelInstanceMetadata options.

Overwrite the configured metadata

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/instance_metadata?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"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"}]}" 
Copy to clipboard

Example request

ReplaceModelInstanceMetadataOptions replaceModelInstanceMetadataOptions = new ReplaceModelInstanceMetadataOptions.Builder()
  .build();

Response<InstanceMetadataResponse> response = mdmService.replaceModelInstanceMetadata(replaceModelInstanceMetadataOptions).execute();
InstanceMetadataResponse instanceMetadataResponse = response.getResult();

System.out.println(instanceMetadataResponse);

Response

Response Body

InstanceMetadataResponse

Wrapper object for instance metadata response

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

Status 200

{
  "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"
}
Copy to clipboard

Success example

{
  "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"
}
Copy to clipboard

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

Status 200

{
  "workflow_configuration_id": "f37fed77-5d2a-4ca5-9914-7d5b3b4dcf62",
  "workflow_type_id": "d24cfe5e-35aa-4085-b688-24b2bd984e15"
}
Copy to clipboard

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

Status 200

{
  "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": {}
  }
}
Copy to clipboard

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

Status 200

{
  "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": {}
  }
}
Copy to clipboard

Introduction

Endpoint URLs

Error handling

Authentication

Methods

Get Config Data Model Type Attributes

Authorization

Request

Query Parameters

crn

type_category

type_name

GetConfiguratorConfigDataModelAttributesOptions

typeCategory

typeName

Response

Response Body

attributes

ConfigDataModelAttributes

attributes

dataType

defaultDisplayName

designation

name

Status Code

200

401

403

500

Get config data model

Authorization

Request

Query Parameters

crn

Response

Response Body

system_properties

attribute_types

any property

relationship_types

any property

locale

record_types

any property

hierarchy_types

any property

node_types

any property

group_types

any property

is_model_published

ConfigDataModel

recordTypes

label

attributes

classification

indexed

label

description

attributeType

cardinality

description

entityTypes

description

label

relationshipTypes

rules

source

recordTypes

entityTypes

target

recordTypes

entityTypes

labelFromSource

labelFromTarget

directional

label

cardinality

description

attributes