Business 360 REST API Reference > Business 360 REST API > Search Match API
  

Search Match API

Use the Search Match API to search for matching records based on the published match model configuration. The required input parameters for the REST API vary based on the business entity and its match model.
The Search Match API searches on the source records, performs matching based on the candidate selection criteria and match rules, and returns the matched records.
For the Search Match API to use a match model configuration, you can use one of the following methods:
Note: Ensure that you have the list of required fields in the declarative rules of the match models published in Business 360 Console.
To search for matching records, submit a POST request with the following URI:
<baseApiUrl>match-ng-pair-gen/public/api/v1/searchmatch/<businessEntity>?[matchmodel=<matchModelId>]&[version=<matchModelVersion>]
The following table describes the parameters that you specify in the POST request:
Parameter
Type
Description
businessEntity
String
Internal ID of the business entity that contains the published match model. You must have a read access to the business entity.
matchmodel
String
Optional. Unique identifier of the published match model that contains the candidate selection criteria and declarative rules required for matching the records.
If you do not specify a match model, the API uses the default match model that you set for the Search Match API in Business 360 Console.
version
Number
Optional. Version number of the match model.
Default is the latest version of the match model.
For more information about finding the identifiers and version numbers, see Finding details for the request.
The response is in the JSON format.

Request body

You can use the following parameters in the Search Match API request body:
Parameter
Type
Description
maxRecordsToReturn
Number
Optional. Maximum number of records to return in the search results.
Default is 100.
searchLevel
String
Optional. Candidate search level that the match model uses to determine how stringently and thoroughly to search for match candidates.
You can configure the following search levels:
  • - Narrow
  • - Typical
  • - Exhaustive
  • - Extreme
If you do not provide this value, the REST API uses the value from the match model.
fileRecordLimit
Number
Optional. Maximum number of match candidates that the REST API can process for a record. You can set the limit to a maximum of 10,000.
If the match candidates exceed the maximum limit, the REST API might return an empty response.
Default is 10,000.
searchRecord
Array
Contains the search values, such as the required match field identifiers and their values, based on which you want to find the matching records.
Enter the internal identifiers for the required match fields. For example, birthDate and fullName. For more information about finding the required match fields and their identifiers, see Finding details for the request.
Ensure that you have read access to the match fields.
Note: To search for records by specifying a date, ensure that you use the YYYY-MM-DD format.
matchPreference
String
Optional. Includes the details of source records based on which the API returns the matched master records.
Each master record in the response includes a source record based on the best match score or the top-ranked declarative match rule that matches the source record with the input data. If multiple source records of a master record are matched based on the same top-ranked declarative match rule or have the same best score, the API includes the source record that has the latest last updated date.
You can use one of the following values:
  • - BEST_SCORE. Includes the details of source records based on the best match score of the source records that match the input data. Default is BEST_SCORE.
  • - FIRST_RULE. Includes the details of source records based on the top-ranked declarative rules that match the source records and input data.
For example, consider a master record named MR1. It has two contributing source records, SRC1 with a match score of 90 based on Rule 1 and SRC2 with a match score of 100 based on Rule 2.
If your match preference is BEST_SCORE, the API returns the master record MR1 and the source record SRC2, which has the best score.
If your match preference is FIRST_RULE, the API returns the master record MR1 and the source record SRC1, which uses the top-ranked rule, Rule 1.

Finding details for the request

You must enter identifier details, such as match field identifier and match model identifier, in the REST API request. To get these details, navigate to the Business 360 Console.

Business entity identifier

To view the identifiers for a business entity, open a business entity from Business 360 Console. Click the Actions menu and view the properties, such as display name and internal ID.
The following image shows the properties of a business entity:
The Business Entity dialog box shows the properties of a business entity with highlighted internal ID.
In the image, the business entity has the internal ID c360.person.

Match model version

To view the version of a match model, click the Match tab of a business entity.
The following image shows the version numbers of the sample match models:
The Match tab displays the match models and their version numbers for a business entity.

Match model identifier

To view the match model identifier, open a match model. The match model identifier appears in the Model Configuration tab
The following image shows the Model Configuration tab that contains the match model identifier:
The business entity shows the match model configuration of a selected match model. The match model identifier is highlighted in the image.

Match fields and identifiers

To view the required match fields in a match model, open a published match model of a business entity. Click the Machine Learning Model tab and view the match fields.
The following image shows the sample match fields for a published match model:
The Machine Learning Model tab shows the participating match fields.
In the image, you can view the match fields that are part of the match model. Some fields are basic fields and some fields are part of a field group. For example, Address Line 1 and Address Line 2 are part of the Address field group. The internal ID of the Address field group is PostalAddress that you can view in the Field Path column.
The Internal ID column displays the internal identifiers of each match field. For example, the internal identifier for the Full Name field is fullName and for the Address Line 1 field is addressLine1.
When you enter the required match fields for a field group in the search match API request body, specify the internal identifiers for the match fields and the field group in the search record. For example, enter the address details in the following format:
"PostalAddress": [
{
"addressLine1": "QUINCE RD"

}
]

Request response

The request response returns the matching records.
The following table lists the response parameters:
Parameter
Type
Description
searchResult
Object
Contains the matching records.
totalRecords
Number
Total number of matching records that the request returns.
records
Array
Contains all the matching records that are filtered and sorted based on the specified criteria.
fileRecordLimit
Number
Maximum number of match candidates that the Search Match API can process for a record.
fileRecordCandidatesCount
Number
Number of match candidates that the Search Match API identifies.
sourceSystem
String
Internal ID of the source system to which the record belongs.
sourcePKey
String
The primary key of the source record.
population
String
Certain characteristics of data in the records that you want to match.
The POST response includes the following _meta parameters:
Parameter
Type
Description
score
Number
The match score of the record.
rank
Number
Ranking of the matching record. Returned if a record is matched using a rank-based rule.
matchRule
String
Threshold value of the match rule. Returned if a record is matched using a threshold-based rule.
businessId
String
Unique business identifier of the master record.
data
Object
Data in the master record.

Sample Request

The following sample request specifies the match fields, such as name, address, and address type, that a published match model uses:
{
"searchControls": {
"maxRecordsToReturn": 20,
"searchLevel": "Typical",
"fileRecordLimit": 1000
},
"data": {
"searchRecord": {
"first_name": "JAMES",
"full_name": "JAMES Gilgen",
"middle_name": "H",
"last_name": "Gilgen",
"Address": [
{
"_id": "add_id2",
"addressLine1": "12012 N MO PAC EXPY",
"addressLine2": "Sound.",
"addressLine3": "Phone leg.",
"addressStatus": {
"Code": "Inactive",
"Name": "Inactive"
},
"addressType": {
"Code": "Office",
"Name": "Office"
},
"coordinateSystem": "Staff.",
"country": {
"Code": "US",
"Name": "United States"
},
"defaultIndicator": true,
"enrichedIndicator": {
"Code": "VALID",
"Name": "Valid"
},
"latitude": "28 N",
"locationCoordinateDesc": "Coordinates",
"longitude": "77 E",
"postalCode": "78758",
"postalCodeExtension": "2241",
"usageType": {
"Code": "Home",
"Name": "Home"
}
}
]
}
}
}
The following sample request specifies only the required fields:

{
"searchControls": {
"maxRecordsToReturn": 10,
"searchLevel": "Typical",
"fileRecordLimit": 1000
},
"data": {
"searchRecord": {
"fullName": "ALEXANDRA NORMAN"
}
}
}

Sample Response

When you make a search request, the response retrieves records based on the configured match rules.
The response contains only the required match fields. To view the other fields of a record, use the Read Master Record by Business ID API.
The following sample response contains two matching master records for the specified search values:
{
"searchResult": {
"totalRecords": 2,
"fileRecordLimit": 1000,
"fileRecordCandidatesCount": 5,
"records": [
{
"_meta": {
"score": 96.0,
"rank": 1,
"businessId": "MDM0000003KLMO"
},
"data": {
"PostalAddress": [
{
"addressLine1": "QUINCE RD STE"
}
],
"birthDate": "2022-03-04",
"fullName": "BETTE Briggs"
}
},

{
"_meta": {
"score": 85.0,
"matchRule": "THD1",
"businessId": "MDM0000003KLMO"
},
"data": {
"PostalAddress": [
{
"addressLine1": "KUINCE RD""
}
],
"birthDate": "2022-03-04",
"fullName": "BETTE Briggs"
}
}
]
}

}
You get the following sample response when you specify only the required fields:

{
"searchResult": {
"totalRecords": 1,
"fileRecordLimit": 1000,
"fileRecordCandidatesCount": 4,
"records": [
{
"_meta": {
"matchModelName": "nir_test",
"matchModelVersion": 1,
"score": 100.0,
"rank": 1,
"businessId": "MDM000000G2PC6",
"xrefSourceSystem": "b360.default.system",
"xrefSourcePKey": "pkey727",
"population": "usa"
},
"data": {
"fullName": "ALEXANDRA NORMAN"
}
}
]
}
}