Markaaz Advanced Match API
The advanced API provides more flexibility in the match results and additional detail regarding the quality of the match for individual fields.
Use of this API is governed by your contract terms. Please consult with your Markaaz Account Manager if clarification is required.
Calling a Match API is the entry point for utilizing the Markaaz API Services. Each process will begin with matching your inputs to a record in the Markaaz Directory. If we are able to successfully match your inputs with a record we will return a response with the matched record(s). The API returns sufficient information to identify the business entity. Along with business-specific data we also return the Markaaz ID. This ID is the unique identifier in the Directory and will be needed to call other APIs that return specific business information, such as firmographic or compliance data.
This API provides the calling routine with an option to discover how the input data fields are graded for their match quality with the data existing in the Markaaz Directory. If you choose to utilize the options below, your integration code can easily examine the input data and determine how well it aligns or does not align with our system of record. If the default values are used for this API it behaves exactly as the standard Markaaz Match API, albeit with a slightly different structure to the response since it handles the possibility of multiple entities in the response. Individual field names do not change.
Other options provide the ability to receive more than one entity in the response payload along with the ability to ignore the Match Confidence Threshold at the API level. The Markaaz Match Confidence Threshold is used in matching where API inputs are compared against the business entities in the Markaaz Directory of over 300 million businesses. The lower the threshold setting, the less confident we will be in providing a good match to your inputs. The current recommended setting is a value of 8.4 to achieve a high-confidence match. This threshold may be modified via the EPP Settings by a user with Administrator privileges.
There are myriad use cases for these options and while Markaaz can provide some guidance, how the additional information or additional entity records shall be used will be your decision.
Input Payload Options
- matchCount - Allow control of the number of match results returned. Note: if the value is > 1 it does not guarantee that more than one result will be returned. Only more than one result is returned if results 2-N are above the match confidence threshold setting or if showNonMatches is set to true. If matchCount is not provided in the payload the default is 1.
- showNonMatches - Allow showing non-matches. This removes the influence of the Markaaz Match Confidence Threshold if set to true and the API will return the top N (matchCount) matches sorted by matchConfidenceScore. A value of “true” will show non-matches. For example, if true and the match confidence score was below the threshold it would still show a result. If showNonMatches is not provided in the payload, the default is set to false.
- showGrades - Allow for showing field match grades for all matching parameters, including the P2B match grade if a name was used in matching. If showGrades = false no field grade information is provided. If showGrades is not provided in the payload the default is set to false.
- epInternalId - This field may be provided to allow for easier traceability to your back end systems. epInternalId is just a pass-through data element. Markaaz does not use this field in matching it is simply returned back in the API response for your convenience. It’s there merely to allow the caller to have their internal ID tied to the record(s) that we have returned. If matchCount > 1, all entities returned will contain the same epInternalId. We assume that only one entity will be "the match” and therefore have a corresponding entry in the customer’s system.
- The "names" array - Currently we only use the 1st name in the array to compare the name provided to the Primary Contact for the entity. It does not compare a list or array of names to the Primary Contact and list of Officers. Please use the P2B Name Match API for that purpose.
- Required Fields - legalName, address, locality(city), postalCode, and countryCode are required fields for matching.
Field Grade Definitions:
- Grade A - the grade A means exact match.
- Grade B - the grade of B is a similar match with at least one common token.
- Grade C - the grade of C is a partial match with zero or one common token.
- Grade F - the grade of F means no match.
- Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match.
- Grade Z - If field value is not provided in the input payload, we return the grade as Z.
Grades are provided for the following fields: dba, companyLegalName, address, locality, region, postalCode, nationalId, taxId, phoneNumber, website, contactName
Sample Data
Please refer to the API Reference section for the full specification. It is worth looking at the grades shown in the response below as compared to the inputs for a further understanding of field grades. In this example, matchCount = 2 however, there is only one entity returned because that is the only record found to exceed the matchConfidenceThreshold setting which can be seen in the response payload.
{
"matchCount": 2,
"showNonMatches": false,
"showGrades": true,
"bizInfo": {
"epInternalId": "1234",
"legalName": "Markaaz, Inc.",
"address": "310 Comal St.",
"locality": "Austin",
"region": "TX",
"postalCode": "78702",
"country": "US",
"dba": "Marka",
"phoneNo": "",
"website": "www.markaaz.com",
"taxId": "",
"nationalId": "",
"names": [
{
"fullName": "Hany Fam"
}
]
}
}
{
"markaaz": {
"traceId": "5aae88c0-c382-48a9-bfb3-686d69ca561e",
"matchResults": [
{
"markaazId": "AZ0000055945770",
"markaazMatchConfidenceScore": 10.0,
"matchConfidenceThreshold": 8.4,
"epInternalId": "1234",
"bizInfo": {
"dba": "MARKAAZ",
"legalName": "MARKAAZ, INC.",
"taxId": null,
"nationalId": null,
"website": "https://markaaz.com/",
"phoneNumber": "3236389797",
"addresses": [
{
"type": "Primary",
"line1": "310 COMAL ST STE 258",
"line2": null,
"locality": "AUSTIN",
"region": "TX",
"country": "US",
"postalCode": "78702",
"latitude": "30.265000",
"longitude": "-97.717100",
"geoprecision": "5",
"businessIndicator": null,
"residentialIndicator": "48",
"sohoIndicator": null
}
]
},
"primaryContact": {
"fullName": "",
"titleCode": "",
"title": "",
"firstName": "",
"lastName": "",
"email": ""
},
"metaData": {
"dba": {
"grade": "C"
},
"companyLegalName": {
"grade": "A"
},
"address": {
"grade": "B"
},
"locality": {
"grade": "A"
},
"region": {
"grade": "A"
},
"postalCode": {
"grade": "A"
},
"nationalId": {
"grade": "Z"
},
"taxId": {
"grade": "Z"
},
"phoneNumber": {
"grade": "Z"
},
"website": {
"grade": "A"
},
"contactName": {
"grade": "Z"
}
}
}
]
}
}
Updated about 2 months ago