Markaaz Search API

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 another entry point for utilizing additional Markaaz API Services; the other entry points are Standard and Advanced Match (recommended). Each verification will begin with searching for a business entity based on your inputs. If we are able to successfully find records that match your inputs we will return at most ten records which most closely align with the values provided. 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. The results are sorted by companyStatus (active businesses first), markaazSearchConfidenceScore, companyLegalName Field Grade, and address Field Grade (if address is provided as an input).

Depending on the common nature of tokens in the legal name, you will likely see records that share those common tokens when only required data is provided. If you wish to reduce the number of responses that simply share common tokens, you will need to provide additional input data to the algorithm so the additional fields can also be evaluated. With more than 450 million records in our directory, better results are achieved with more data points for comparison.

Match vs. Search Comparison

Field Grade Definitions:

Grades are provided for the following fields: dba, companyLegalName, address, locality, region, postalCode, nationalId, taxId, phoneNumber, website, and contactName even if they are not provided in the input payload.

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.

Input Payload:

Required Fields: legalName, locality, country (ISO 2 country code e.g. US, DE, FR)

πŸ“˜

If a full name is provided, it will be compared to the primary contact of the business. Only the 1st name in the array is currently used.

{
  "bizInfo": {
    "dba": "",
    "legalName": "", 
    "address": "",
    "locality": "", 
    "region": "",
    "postalCode": "",
    "country": "", 
    "phoneNo": "",
    "website": "",
    "taxId": "",
    "nationalId": "",     
    "names": [
       "fullName": ""
    ]
  }
}

Response Payload:

The API will respond with a maximum of 10 business records. The number of records found will depend somewhat on the uniqueness of the input tokens. The vast majority of requests will return 10 records.

{
  "markaaz": {
    "traceId": "",
    "searchResults": [
      {
        "markaazId": "",
        "markaazSearchConfidenceScore": 0,
        "companyStatus": "",
        "bizInfo": {
          "dba": "",
          "legalName": "",
          "taxId": "",
          "nationalId": "",
          "website": "",
          "phoneNumber": "",
          "addresses": [
            {
              "type": "",
              "line1": "",
              "line2": "",
              "locality": "",
              "region": "",
              "country": "",
              "postalCode": "",
              "latitude": "",
              "longitude": "",
              "geoprecision": "",
              "businessIndicator": "",
              "residentialIndicator": "",
              "sohoIndicator": ""
            }
          ]
        },
        "primaryContact": {
          "fullName": "",
          "titleCode": "",
          "title": "",
          "firstName": "",
          "lastName": "",
          "email": "",
        },
        "metaData": {
          "dba": {
            "grade": ""
          },
          "companyLegalName": {
            "grade": ""
          },
          "address": {
            "grade": ""
          },
          "locality": {
            "grade": ""
          },
          "region": {
            "grade": ""
          },
          "postalCode": {
            "grade": ""
          },
          "nationalId": {
            "grade": ""
          },
          "taxId": {
            "grade": ""
          },
          "phoneNumber": {
            "grade": ""
          },
          "website": {
            "grade": ""
          },
          "contactName": {
            "grade": ""
          }
        }
      }
    ]
  }
}