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.
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:
- Log into the Cloud Pak for Data web interface.
- Navigate to My Instances, then select the appropriate IBM Match 360 instance.
- Click View details.
The service instance token is displayed in the Access Information section.
Retrieving the service instance token with the Cloud Pak for Data API
To retrieve the service instance token by using the /zen-data/v2/serviceInstance/token
API, run the following curl command:
curl -X POST 'https://{cpd_cluster_host}/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:
- Retrieve the service instance IDs associated with the platform token.
- Obtain a service instance token by providing your service instance ID.
- Use the service instance token to authorize your IBM Match 360 API calls.
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:
- Click Authorize at the top of the page
- Enter the service instance token.
- 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
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
The type of the output rules, ie. ALL, VALID, INVALID
The data type identifier of record, ie. person, organization
The storage bucket for the output file, ie. bucket-27200-lwx4cfvcue
The data type identifier of entity, ie. person_entity, organization_entity, household_entity
The file format used when exporting the output file, ie. json, csv
The storage endpoint for the output file, ie. https://s3.us-east.cloud-object-storage.appdomain.cloud
The access key for your storage, ie. cf4965cebe074720a4929759f57e1214
The type of file compression used when exporting the output file. Required when a partition type of 'executor_count' is specified, ie. null, zip, tar, tgz
The secret key to access your storage
The folder name used when exporting the output file, ie. rulesData. The export file will be named as rulesData_<entity_type>.
The type of partitioning used when exporting the results. ie. null, executor_count
Response
Response object for asynchronous processing of a job
System defined name of a given job e.g. match-bulkderiver
System generated timestamp when a job was last updated
System generated timestamp when a job was created
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
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.
{ "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
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
System defined name of a given job e.g. match-bulkderiver
System generated timestamp when a job was last updated
System generated timestamp when a job was created
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
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.
{ "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
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
The data type identifier of entity, ie. person_entity, organization_entity, household_entity
The data type identifier of record, ie. person, organization
The full path to the input linkage rules CSV file, ie. /rulesData/output.csv. The corresponding header files should be in the same level and named HEADERS.
The storage bucket for the output file, ie. bucket-27200-lwx4cfvcue
The storage endpoint for the output file, ie. https://s3.us-east.cloud-object-storage.appdomain.cloud
The access key for your storage, ie. cf4965cebe074720a4929759f57e1214
The secret key to access your storage
Response
Response object for asynchronous processing of a job
System defined name of a given job e.g. match-bulkderiver
System generated timestamp when a job was last updated
System generated timestamp when a job was created
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
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.
{ "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
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
System defined name of a given job e.g. match-bulkderiver
System generated timestamp when a job was last updated
System generated timestamp when a job was created
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
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.
{ "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
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
System defined name of a given job e.g. match-bulkderiver
System generated timestamp when a job was last updated
System generated timestamp when a job was created
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
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.
{ "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
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
System defined name of a given job e.g. match-bulkderiver
System generated timestamp when a job was last updated
System generated timestamp when a job was created
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
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.
{ "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
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:ViewThe 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
The wrapper object for single data quality issue
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.
{ "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
Request
The wrapper object for remediation workflow start request
Collection of entities
Response
The wrapper object for post start workflow response
Collection of entities
The last updated user
The unique identifier of a workflow
The type of workflow
The last updated date
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.
{ "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
Request
The wrapper object for starting bulk remediation workflow request
The wrapper object for search criteria used for stating bulk remediation workflow request
Response
Response object for asynchronous processing of a job
System defined name of a given job e.g. match-bulkderiver
System generated timestamp when a job was last updated
System generated timestamp when a job was created
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
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.
{ "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
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
Collection of records
Response
Response object for comparing records
The overall comparison score of the record(s)
Collection of post filter methods
The score category of the record(s)
Collection of comparators used for comparing the 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.
{ "score": 230.32, "score_category": "matched" }
Get entity detail
- This service provides entity members, matched pairs, and manual rules.
POST /mdm/v1/entity_detail
Request
The wrapper object of entity and record numbers
The data type identifier of entity, ie. person_entity, organization_entity, household_entity
The data type identifier of record, ie. person, organization
Collection of entity numbers
The minimal score for matched pairs
Collection of record numbers
Response
Response object for entity details
Collection of record details
Collection of sample pairs of 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.
{ "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}
Response
Response object for get matching job
System defined name of a given job e.g. match-bulkderiver
System generated timestamp when a job was last updated
System generated timestamp when a job was created
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
Summary of a job
System defined image for a given job e.g. mdm-spark-job
System generated timestamp when a job was started
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.
{ "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
Request
The wrapper object of linkage rules
The data type identifier of entity, ie. person_entity, organization_entity, household_entity
Collection of linkage rules
Response
Response wrapper object for linkage rules
A single linkage rule for a given entity
System generated timestamp when the linkage rule was last updated
User specified rule type. One Of: link, unlink
One of the record numbers in linkage rule
User defined description for the linkage rule
The other record number in linkage rule
Creator of the linkage rule
any property
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.
{ "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
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
Collection of pairs of record numbers
Response
The wrapper object for the comparison details of the pairs compared
Collection of details of pairs comparisons
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.
{ "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
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
Collection of self comparison scores of the source record for each entity type
The unique identifier of a source record as assigned by the system
Collection of a record's bucket hashes, primarily used for efficient entity resolution
A serialized representation of the standardized values
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.
{ "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
Request
Query Parameters
The level of information detail in response, ie. low, high, debug
Default:
low
The wrapper object for collection of records
Collection of records
Response
Response object for previewing the derived matching data for given records
Collection of 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.
{ "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
Request
The wrapper object of linkage rules
The data type identifier of entity, ie. person_entity, organization_entity, household_entity
Collection of linkage rules
Response
Response wrapper object for previewing the impacted entities by hypothesizing one or more linkage rules
any property
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.
{ "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}
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
Collection of record number, record id and record source
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.
{ "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
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
Details of a single record including external record reference and record attributes
attributes
The data type identifier of the record, ie. person, organization
Response
Response object for searching the potential matches of a given search criteria
Collection of records matching the 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.
{ "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
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
A single linkage rule for a given entity
System generated timestamp when the linkage rule was last updated
User specified rule type. One Of: link, unlink
One of the record numbers in linkage rule
User defined description for the linkage rule
The other record number in linkage rule
Creator of the linkage rule
any property
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.
{ "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
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
Collection of sample pairs of 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.
[ { "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
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
Collection of entity ids and entity types
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.
{ "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
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
A single linkage rule for a given entity
System generated timestamp when the linkage rule was last updated
User specified rule type. One Of: link, unlink
One of the record numbers in linkage rule
User defined description for the linkage rule
The other record number in linkage rule
Creator of the linkage rule
any property
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.
{ "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
Request
The wrapper object of linkage rules
The data type identifier of entity, ie. person_entity, organization_entity, household_entity
Collection of linkage rules
Response
Response wrapper object for linkage rules
A single linkage rule for a given entity
System generated timestamp when the linkage rule was last updated
User specified rule type. One Of: link, unlink
One of the record numbers in linkage rule
User defined description for the linkage rule
The other record number in linkage rule
Creator of the linkage rule
any property
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.
{ "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
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
True when there are any manual linkage rules for the given entity type
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.
{ "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
Response
Response wrapper object for all algorithm names
Collection of 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.
{ "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}
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)
Collection of standardizer definitions
A single standardizer definition
standardizers
Asymmetric encryption configuration
Collection of entity type definitions
A single entity type definition
entity_types
The request language and location (i.e. enUS)
Bit length for bucket group.The default length is 4
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.
{ "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}