IBM Cloud API Docs

Introduction

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

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

The IBM Match 360 APIs support:

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

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

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

Service endpoint

The IBM Match 360 service endpoint is based on your Cloud Pak for Data deployment URL: https://{cpd_cluster_host}/mdm/model/

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

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

Example

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

Error handling

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

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

ErrorResponse

Name Description
code

integer
HTTP error code.
error

string
Human-readable error string, like 'Invalid image file'.

ErrorAuthentication

Name Description
status

string
The status of error.
statusInfo

string
Information about the error.

ErrorHTML

Name Description
Error

string
HTML description of the error.
statusInfo

string
Information about the error.

ErrorInfo

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

Name Description
code

integer
HTTP status code.
description

string
Human-readable error description. For example, File size limit exceeded.
error_id

string
Codified error string. For example, limit_exceeded.

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

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

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

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

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

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

Example error handling

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

Granting users access to IBM Match 360

After you install IBM Match 360 on Cloud Pak for Data, you must give users access to the service by creating user groups and adding users to them.

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

To access IBM Match 360, a Cloud Pak for Data user must belong to one of the following specialized groups:

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

For information about creating the necessary IBM Match 360 user groups and granting users access to IBM Match 360, see Giving users access to IBM Match 360 in the IBM Cloud Pak for Data documentation.

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

Authentication

To authenticate to the IBM Match 360 API, you must first authenticate to Cloud Pak for Data APIs to obtain a service instance ID and token. You can then use the service instance token in the authorization header of calls to the IBM Match 360 API.

Authenticating to the platform API

Generate an authorization token or API key to authenticate to the Cloud Pak for Data platform API.

For details about authenticating to the Cloud Pak for Data API, see Generating an authorization token or API key in the Cloud Pak for Data documentation.

Obtaining a service instance ID and token

After authenticating to the Cloud Pak for Data platform, obtain the service instance ID and token for your IBM Match 360 instance.

Retrieving the service instance ID

You can retrieve a service instance token by viewing the service instance details in the Cloud Pak for Data web interface or by using the the /zen-data/v2/serviceInstance/users API.

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

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

This command produces the following JSON response:

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

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

Obtaining the service instance token

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

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

Service instance tokens expire 20 minutes after creation.

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

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

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

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

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

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

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

Replace the following values in the curl command:

  • <PROVISIONED_INSTANCE_ID> - the instance ID of your provisioned instance.
  • <EXPIRY_TIME> - the token expiry time in minutes.

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

This command produces a JSON response similar to the following example:

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

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

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

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

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

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

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

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

Replace the following values in the command:

  • <PROVISIONED_INSTANCE_ID> - the instance ID of your provisioned instance.
  • <EXPIRY_TIME> - the token expiry time in minutes.

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

Authenticating to the IBM Match 360 API

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

  1. Retrieve the service instance IDs associated with the platform token.
  2. Obtain a service instance token by providing your service instance ID.
  3. Use the service instance token to authorize your IBM Match 360 API calls.

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

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

  • Using the Authorize feature of the API Explorer user interface.
  • In the Authorization header of an API request.
Providing the service instance token by using the Authorize feature of API Explorer

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

Replace <MDM_INSTANCE_ID> with your service instance ID number.

In the API Explorer, complete the following steps:

  1. Click Authorize at the top of the page
  2. Enter the service instance token.
  3. Click Authorize and then click Close.

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

Providing the service instance token by using the Authorization header of an API request

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

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

Replace the following values in the curl command:

  • <API_PATH> - the path of your desired API (Such as /mdm/model/v1/jobs).
  • {token} - the platform bearer authentication token.

To authenticate to a IBM Match 360 service instance by using the Authorization header, run the following curl command:

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

Replace the following values in the curl command:

  • <API_PATH> - the path of your desired API (Such as /mdm/model/v1/jobs).
  • {token} - the platform bearer authentication token.

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.

Methods

Initiate export manual rules job

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

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

  • Wait for job finish, default is false

    Default: false

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • The number of partitions to be used by spark

    Example: 2

The wrapper object for export manual rules request body

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Initiate match job

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

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

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

    Example: person

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

    Example: person_entity

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

    Default: false

  • Deduplicate pairs, default is false

    Default: false

  • collect analysis report, default is false

    Default: false

  • Replicate entity id, default is true

    Default: true

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • The number of partitions to be used by spark

    Example: 2

  • IBM COS end point for job log storage.

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

  • IBM COS bucket for job log storage.

    Example: mdmdata

  • IBM COS access key for spark log storage

    Example: b33037e4e8954207a434cc032c1139d1

  • IBM COS secret key for spark log storage

    Example: <hex string>

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully created.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Initiate import manual rules job

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

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

  • Wait for job finish, default is false

    Default: false

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • The number of partitions to be used by spark

    Example: 2

The wrapper object for import manual rules request body

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Initiate data derivation job

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

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

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

    Example: person

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

    Default: false

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

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

  • comma separated column names in the data file

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

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

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

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

    Example: mdmdata

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

    Example: b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret

  • The unique secret code to access IBM COS

    Example: <hex string>

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • The number of partitions to be used by spark

    Example: 2

  • IBM COS end point for job log storage.

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

  • IBM COS bucket for job log storage.

    Example: mdmdata

  • IBM COS access key for spark log storage

    Example: b33037e4e8954207a434cc032c1139d1

  • IBM COS secret key for spark log storage

    Example: <hex string>

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully created.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Initiate report job

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

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

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

    Example: person

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

    Example: person_entity

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • The number of partitions to be used by spark

    Example: 2

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

    Default: entity_summary,bucket_summary

    Example: entity_summary,bucket_summary

  • collect analysis report, default is false

    Default: false

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully created.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Initiate generate pairs job

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

Authorization

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

  • mdm-oc.matching.manage

Request

Query Parameters

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

    Example: person_entity

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

    Example: person

  • Wait for job finish, default is false

    Default: false

  • The maximum number of pairs to return

    Default: 500

    Example: 500

  • The number of spark executors

    Example: 1

  • Amount of memory to use per executor process

    Example: 8g

  • The number of cores to use on each executor

    Example: 1

  • The number of partitions to be used by spark

    Example: 2

  • Exclude reviewd pairs. Default is false

    Default: false

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Retrieve list of issues for given entities

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

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

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

    Example: person_entity

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

    Examples:
    View
  • The number of issues to be retrieved for the given entities

    Default: 1

    Example: 1

  • The number of issues to skip before returning the result

    Default: 0

Response

The wrapper object for getting data quality issues

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

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

Start matching remediation workflow

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

Authorization

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

  • mdm-oc.matching.write

Request

The wrapper object for remediation workflow start request

Examples:
StartMatchingWorkflowExample

Response

The wrapper object for post start workflow response

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

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

Starts matching bulk remediation workflows

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

Authorization

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

  • mdm-oc.matching.write

Request

The wrapper object for starting bulk remediation workflow request

Examples:
StartBulkMatchingRemediationWorkflowExample

Response

Response object for asynchronous processing of a job

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

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

Compare records

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

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

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

    Example: person_entity

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

    Default: low

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

    Example: 123456789

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

    Example: 123456789

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

    Default: person

    Example: person

The wrapper object for collection of records

Examples:
compareRequestExample

Response

Response object for comparing records

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

Example responses
  • {
      "score": 230.32,
      "score_category": "matched"
    }

Get entity detail

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

Authorization

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

  • mdm-oc.matching.read

Request

The wrapper object of entity and record numbers

Response

Response object for entity details

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Retrieve information for a job

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

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

  • The unique identifier of the job.

    Example: 95364

Response

Response object for get matching job

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Add or update manual link/unlink

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

Authorization

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

  • mdm-oc.matching.write

Request

The wrapper object of linkage rules

Response

Response wrapper object for linkage rules

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Compare pairs of records

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

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

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

    Example: person_entity

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

    Example: person

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

    Default: low

The wrapper Object for pairs of record numbers

Examples:
batchCompareRequestExample

Response

The wrapper object for the comparison details of the pairs compared

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

Example responses
  • {
      "comparison_scores": [
        {
          "score": 331.33,
          "score_category": "matched"
        },
        {
          "score": 80,
          "score_category": "unmatched"
        }
      ]
    }

Retrieve derived data for a record

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

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

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

    Example: 1234567890

  • The source system name of the record

    Example: MDM

  • The record identifier of the record

    Example: 123456

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

    Example: person

Response

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

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to authentication error.

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

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

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

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

Preview derived data

  • This service computes and returns a preview of the derived data for the input records.
  • Data derivation is the process to standardize and generate buckets for the input records.
POST /mdm/v1/derive

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

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

    Default: low

The wrapper object for collection of records

Examples:
deriveRequestExample

Response

Response object for previewing the derived matching data for given records

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Preview entity composition

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

Authorization

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

  • mdm-oc.matching.read

Request

The wrapper object of linkage rules

Response

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

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Retrieve record ids

  • This service retrieves all record_ids that are assigned with the same entity_id.
GET /mdm/v1/entity_ids/{entity_id}

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

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

    Example: entity_type-123456789

Response

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

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to authentication error.

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

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

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

Example responses
  • {
      "records": []
    }

Search records by matching algorithm

  • This service searches for the supplied payload and returns record_ids of potential matches.
  • The order of record_ids in the response is determined by matching algorithms.
POST /mdm/v1/probabilistic_search

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

  • To include logical keys in the response, default is true

    Default: true

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

    Default: low

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

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

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

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

    Default: person_entity

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

The wrapper Object for a single record

Examples:
searchRequestExample

Response

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

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Retrieve an entity's manual links/unlinks

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

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

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

    Example: person_entity-1234

Response

Response wrapper object for linkage rules

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to authentication error.

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

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

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

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

Retrieve sample pairs of records

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

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

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

    Example: person

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

    Example: person_entity

  • The number of pairs to be retrieved from the generated pairs

    Default: 1

    Example: 1

  • The number of pairs to skip before returning the result

    Default: 0

Response

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

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Retrieve all entity ids

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

Authorization

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

  • mdm-oc.matching.read

Request

Query Parameters

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

    Example: 1234567890

  • The source system name of the record

    Example: MDM

  • The record identifier of the record

    Example: 123

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

    Example: person

Response

Response wrapper object for getting entity ids

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to authentication error.

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

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

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

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

Retrieve a record's manual links/unlinks

  • This service retrieves all manual link/unlink rules for given record and entity type.
GET /mdm/v1/records/{record_number}/linkage_rules

Authorization

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

  • mdm-oc.matching.read

Request

Path Parameters

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

    Example: 123456789

Query Parameters

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

    Example: entity-type

Response

Response wrapper object for linkage rules

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to authentication error.

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

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

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

Example responses
  • {
      "person_entity": [
        {
          "src_recno": "35677335438998529",
          "target_recno": "35677332186315776",
          "rule_type": "LINK",
          "description": "string",
          "user": "user2",
          "last_updated": "1605178647781"
        }
      ]
    }

Remove manual link/unlink

  • This service removes one or more manual link/unlink rules supplied by user.
POST /mdm/v1/delete_linkage_rules

Authorization

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

  • mdm-oc.matching.write

Request

The wrapper object of linkage rules

Response

Response wrapper object for linkage rules

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to user error.

  • The request cannot be processed due to authentication error.

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

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

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

Check the existence of linkage rules

  • This service checks for the existence of linkage rules for specified entity type.*
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

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

    Example: person

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

    Example: person_entity

  • To check if invalid manual linkage rules exist, default is false

    Default: false

Response

Response wrapper object of checking existence of linkage rules

Status Code

  • The request has been successfully finished.

  • The request cannot be processed due to authentication error.

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

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

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

Example responses
  • {
        "linkage_rules_exist": "true",
    }

Retrieve record types of all the matching algorithms

  • This service retrieves the record types of all the matching algorithms present.
  • A matching algorithm contains the matching metadata for a given record type and is comprised of standardization, bucket generation and comparison sections.
GET /mdm/v1/algorithms

Authorization

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

  • mdm-oc.model.read

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response wrapper object for all algorithm names

Status Code

  • The algorithms' record types has been successfully retrieved.

  • The request cannot be processed due to authentication error.

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

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

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

Example responses
  • {
      "algorithm_names": [
        "organization",
        "person"
      ]
    }

Retrieve the matching algorithm

  • This service retrieves the matching algorithm for a given record type.
  • A matching algorithm contains the matching metadata for a given record type and is comprised of standardization, bucket generation and comparison sections.
GET /mdm/v1/algorithms/{record_type}

Authorization

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

  • mdm-oc.model.read

Request

Path Parameters

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

Query Parameters

  • response will return the default template algorithm when set to true

    Default: false

Response

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

Status Code

  • The algorithm has been successfully retrieved.

  • The request cannot be processed due to authentication error.

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

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

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

Example responses
  • {
      "locale": "en_us",
      "encryption": {},
      "standardizers": {},
      "entity_types": {}
    }

Overwrite the matching algorithm

  • This service completely overwrites the matching algorithm for a given record type.
  • A matching algorithm defines how two records of a given type are compared.
  • A matching algorithm contains the matching metadata for a given record type and is comprised of standardization, bucket generation and comparison sections.
PUT /mdm/v1/algorithms/{record_type}

Authorization

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