Advanced Match

Use of this API is governed by your contract terms. Please consult with your Markaaz Account Manager if clarification is required.

The Advanced Match API is an entry point for business verification workflows, using a set of required request fields, and returning one or more matching businesses with associated match scoring and grading. Capture a returned markaazId to pass into subsequent Verification API requests.

This API provides 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 this option, your integration code can easily examine the input data and determine how well it aligns or does not align with our system of record.

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 per API request. 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.3 to achieve a high-confidence match. This threshold may be modified via the EPP Settings by a user with Administrator privileges.

Typical Advanced Match Request

{
  "bizInfo": {
    "legalName": "Markaaz, Inc.",
    "address": "310 Comal St Ste 258",
    "locality": "Austin",
    "postalCode": "78702",
    "country": "US",
    "epInternalId": "123456"
  },
  "matchCount": 1,
  "showNonMatches": false,
  "showGrades": true,
  "matchConfidenceThresholdOverride": ""
}

Key behaviors

Results are sorted by markaazMatchConfidenceScore descending; matchCount caps the number of returned matches at/above your threshold.
In some cases, a business match will return multiple high-confidence matches that appear nearly identical, sometimes with the same markaazMatchConfidenceScore. This is most common for large commercial brands with complex legal structures, where a single brand may be supported by one primary entity and several closely associated entities. In these cases, the relative ordering of the top results should not be interpreted as a quality signal. Multiple records can be equally valid, depending on the intended use.
showNonMatches ignores your configured match confidence score threshold. Results are sorted by markaazMatchConfidenceScore descending and capped by matchCount.
showGrades=true returns A/B/C/F/Z grades for matched fields to explain the score and power rule-based decisions.

Typical Advanced Match Response (incl. field-level grades)

{
  "markaaz": {
    "traceId": "ca3b2f29-8067-4fbe-a32f-408ecbe02f1c",
    "matchResults": [
      {
        "markaazId": "1020000028206755",
        "markaazMatchConfidenceScore": 9.83,
        "matchConfidenceThreshold": 8.3,
        "epInternalId": "",
        "bizInfo": {
          "dba": "MARKAAZ",
          "legalName": "MARKAAZ, INC.",
          "taxId": null,
          "nationalId": "4652009",
          "website": "www.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.261169",
              "longitude": "-97.728013",
              "geoprecision": "9",
              "businessIndicator": "Y",
              "residentialIndicator": null,
              "sohoIndicator": null
            },
            {
              "type": "Registered",
              "line1": "310 COMAL ST SUITE 258",
              "line2": null,
              "locality": "AUSTIN",
              "region": "TX",
              "country": "US",
              "postalCode": "78702",
              "latitude": null,
              "longitude": null,
              "geoprecision": null,
              "businessIndicator": null,
              "residentialIndicator": null,
              "sohoIndicator": null
            }
          ]
        },
        "primaryContact": {
          "fullName": "HANY FAM",
          "titleCode": "C",
          "title": "Chief Executive Officer",
          "firstName": "HANY",
          "lastName": "FAM",
          "email": "[email protected]"
        },
        "metaData": {
          "dba": { "grade": "Z" },
          "companyLegalName": { "grade": "A" },
          "address": { "grade": "B" },
          "locality": { "grade": "A" },
          "region": { "grade": "Z" },
          "postalCode": { "grade": "A" },
          "nationalId": { "grade": "Z" },
          "taxId": { "grade": "Z" },
          "phoneNumber": { "grade": "Z" },
          "website": { "grade": "Z" },
          "contactName": { "grade": "Z" }
        }
      }
    ]
  }
}

Field Grade Legend

Grade	Definition
A	Exact match: The request and response values match exactly.
B	Similar: At least one word within a multi-word string matches (aka "common token").
C	Partial: One or no words within a multi-word string match exactly. Fuzzy matching has been used to account for typos and spelling anomalies.
F	No match: The request and response fields do not match, or the request field is not present or populated in the response record.
Z	The field was not provided in the request. Note: This may be the result of the field name being spelled incorrectly in the request JSON, thus ignored in processing.

Field grades compare the API request value to the aligned response field.
In the case of address-related field grades, Markaaz compares the request address against three possible response address types (registered, primary, secondary) using line1 in the response (street address) to determine the overall best matching address. All address-related field grades are then associated with that address.

Fields to Persist

Capture and save these response values for downstream use.

Field	Purpose
`markaazId`	Persistent business identifier for subsequent enrichment & reuse via Verification APIs.
`traceId`	Support troubleshooting.
`epInternalId`	Capture this along with the `epInternalId` sent in the request and link to the customer's platform.

Search

Use of this API is governed by your contract terms. Please consult with your Markaaz Account Manager if clarification is required.

The Search API is an entry point for business discovery and pre-fill workflows, using multiple optional request fields to cast a wider net than Advanced Match, and returning one or more matching businesses. Once a desired markaazId is identified, the related business data can be used to pre-fill forms in user-facing UIs, or passed into markaaz Verification APIs to retrieve additional business data.

If we are able to successfully find records that match your Search inputs we will return at most ten records which most closely align with the values provided. The results are sorted by companyStatus (active businesses first), markaazSearchConfidenceScore, companyLegalName Field Grade, and address Field Grade (if address is provided as an input).

Typical Search Request

{
  "bizInfo": {
    "epInternalId": "123456",
    "dba": "Markaaz Inc.",
    "country": "US"
  }
}

Key behaviors

Results are sorted by markaazSearchConfidenceScore descending; Search returns up to 10 results.
Search accepts fewer fields; include as many as you have (especially country) to improve results.

Typical Search Response

Search results are structured very similarly to Advanced Match results. In the below example, only companyLegalName and country were included in the request.

{
  "markaaz": {
    "traceId": "c6669bdc-ec05-45d1-9bca-470bf593ac78",
    "searchResults": [
      {
        "markaazId": "1020000028206755",
        "markaazSearchConfidenceScore": 10.0,
        "companyStatus": "Active",
        "epInternalId": "",
        "bizInfo": {
          "dba": "MARKAAZ",
          "legalName": "MARKAAZ, INC.",
          "taxId": null,
          "nationalId": "4652009",
          "website": "www.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.261169",
              "longitude": "-97.728013",
              "geoprecision": "9",
              "businessIndicator": "Y",
              "residentialIndicator": null,
              "sohoIndicator": null
            },
            {
              "type": "Registered",
              "line1": "310 COMAL ST SUITE 258",
              "line2": null,
              "locality": "AUSTIN",
              "region": "TX",
              "country": "US",
              "postalCode": "78702",
              "latitude": null,
              "longitude": null,
              "geoprecision": null,
              "businessIndicator": null,
              "residentialIndicator": null,
              "sohoIndicator": null
            }
          ]
        },
        "primaryContact": {
          "fullName": "HANY FAM",
          "titleCode": "C",
          "title": "Chief Executive Officer",
          "firstName": "HANY",
          "lastName": "FAM",
          "email": "[email protected]"
        },
        "metaData": {
          "dba": { "grade": "Z" },
          "companyLegalName": { "grade": "A" },
          "address": { "grade": "Z" },
          "locality": { "grade": "Z" },
          "region": { "grade": "Z" },
          "postalCode": { "grade": "Z" },
          "nationalId": { "grade": "Z" },
          "taxId": { "grade": "Z" },
          "phoneNumber": { "grade": "Z" },
          "website": { "grade": "Z" },
          "contactName": { "grade": "Z" }
        }
      }
    ]
  }
}

Advanced Match: Request Parameter Reference & Defaults

Parameter	Default / Required	What it Does	Recommendations & Context
`matchCount`	Default: 1	Max number of matches returned at/above threshold (sorted by score desc).	Use 1 for best-match only; increase (≤10) to review more. More results are not guaranteed if below threshold.
`showNonMatches`	Default: false (null → false)	If true, returns up to `matchCount` results ignoring threshold (may all be below).	Set with `matchCount>1` for agent review or low-signal small businesses.
`showGrades`	Default: false (null → false)	Adds grades (A/B/C/F/Z) per field to explain the score.	Enable during tuning and for rules weighting (e.g., prioritize `legalName` over `address`). Grades not returned in 207 no-match responses.
`epInternalId`	Optional	Echoed through responses for correlation; not enforced unique.	Use to tie to your application/case IDs; note it applies to the request/response pair (not specific `markaazId` when multiple results).
`legalName`, `address`, `locality`, `postalCode`, `country`	Required	Improve upstream address collection (validation, split components such as street address, locality, postal code; consider address lookup services) to boost scores.	—
`matchConfidenceThresholdOverride`	Optional	Per-request override; does not change configured default.	Use to apply low/med/high risk profiles.

Search: Request Parameter Reference & Defaults

Parameter	Default / Required	What it Does	Recommendations & Context
`nationalId`, `taxId`	Optional (identifiers)	Exact match first; if fails, falls back to name + address.	Validate formats upstream; values are treated as strings (no cleansing to jurisdiction formats).
`names`	Optional array	First array item compared to Primary Contact `fullName`.	For initial workflows include a name; for later checks use P2B.
`epInternalId`	Optional	Echoed through responses for correlation; not enforced unique.	Use to tie to your application/case IDs; note it applies to the request/response pair (not specific `markaazId` when multiple results).
`legalName`, `address`, `locality`, `postalCode`, `country`	All optional, but include `country` for best results	Fewer required fields than Advanced Match.	Use Search when you can't supply required match fields; transition to Advanced Match post-selection. Expect slightly longer response times than Advanced Match.
`matchConfidenceThresholdOverride`	Optional	Per-request override; does not change configured default.	Use to apply low/med/high risk profiles.

Note on source content: In the original PDF, the matchConfidenceThresholdOverride, nationalId/taxId, and names rows appear a second time directly under the "Advanced Match and Search: Response Parameter Guidance" heading, before the traceID field. This looks like a table/page-break duplication artifact from the Confluence PDF export rather than intentional repeated content. I've consolidated them once here under Search; please verify against the source Confluence page that no distinct content was lost in the duplicated rows.

Advanced Match and Search: Response Parameter Guidance

Field	Values	Definition	Recommendation and Business Context
`traceID`	string	Unique identifier for the API request/response pair used by Markaaz for support purposes.	Capture and include this number in any support requests to Markaaz.
`markaazID`	string	Unique identifier for the business in the Markaaz Global Directory.	Capture this number to pass to subsequent Verification API requests for further business data. The `markaazId` does not change, so it can be stored long-term on the customer's platform and used again later to re-verify and see the most up-to-date data for a business.
`markaazMatchConfidenceScore` (Advanced Match response only)	1 (weakest) – 10 (strongest)	The match confidence score is an analysis of the match confidence level on a 10 to 1 scale. Match Confidence is strongest at 10 (representing a very high level of the match on all data elements present) and weakest at 1 (representing a match on Name only).	See guidance above in the Request section.
`matchConfidenceThreshold` (Advanced Match response only)	1–10	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.3 to achieve a high-confidence match.	This is echoed back from the customer's request. See guidance above in the Request section.
`markaazSearchConfidenceScore` (Search response only)	1 (weakest) – 10 (strongest)	The Search Confidence Score is an analysis of the search confidence level on a 10 to 1 scale. Search Confidence is strongest at 10 (representing a very high level of the match on all data elements present) and weakest at 1 (representing a match on Name only).	See guidance above in the Request section.
`companyStatus`(Search response only)	active, inactive	As reported to Markaaz via external registry data.	—
`epInternalId`	string	A unique business identifier in the partner's backend system. This can be provided for easier traceability between a partner system and a Markaaz ID. Matching does not store the `epInternalId`.	This is echoed back from the customer's request. See guidance above in the Request section.
`dba`, `legalName`, `taxID`, `nationalID`, `website`, `phone number`	strings	Business information on DBA (Doing Business As), legal name, tax ID, national ID, website, and phone number.	A matching `taxId` does not imply hierarchy. `taxId` should be treated as a matching aid to improve entity resolution, not as an authoritative indicator of legal structure or hierarchy.
Address `type` (applies to primary address, secondary address, registered address)	Primary, secondary, or registered	The type of address. A `markaazId` may have one or more associated address types. For the purpose of matching and address field grades, Markaaz determines the best overall matching address based on the address input and `line1` of the response.	Address types reflect Markaaz data and do not imply address match result quality. For example, "primary" does not imply the best match.
`line1`, `line2`, `locality`, `region`, `postalCode`, `country` (applies to primary address, secondary address, registered address)	strings	The address lines 1 and 2, locality or city, region/state, postal code, and country the business is based in. These are returned from the Markaaz business record, not parsed from the address input.	`line1` most closely aligns with Markaaz address matching and grading.
`latitude`, `longitude`, `geoprecision` (applies to primary address, secondary address, registered address)	strings	The latitude, longitude, geoprecision of this address.	—
`businessIndicator`, `residentialIndicator`, `sohoIndicator` (applies to primary address, secondary address, registered address)	"Y" or empty string	Indicates this business is located at an address identified by the US Postal Service (USPS) as commercial/business or residential. The SOHO flag indicates if this location qualifies as a small office/home office business.	—
`primaryContact.fullName`, `primaryContact.firstName`, `primaryContact.lastName`	strings	Information on the primary contact: full name, first name, last name.	—
`primaryContact.title`, `primaryContact.email`	strings	Information on the primary contact: title, email address when available.	—
`primaryContact.titleCode`	string	The title code of the primary contact for the business.	—