Business Verification API Suite

Overview

Business Verification APIs are used to retrieve and verify KYB information in the Markaaz Directory. The verification process begins with a call to a matching or to a search API as an entry point. AbizInfo object is returned that holds the business identity information. In addition to the bizInfo object, a Markaaz ID is also returned which is required by other verification APIs to retrieve additional verification Data Groups. The verification APIs provide Data Groups for firmographics, business health, compliance, company hierarchy and diversity. Markaaz also provides person-to-business name matching to allow verification of a specific name as an officer or primary contact for the business.

For each match request, a Match Confidence Score calculated based on an evaluation of how well the API inputs align with entities in the Directory. The Match Confidence Threshold is a Client configurable setting that defines the minimum score required to be evaluated as a "match" based on the Score achieved. The Match Confidence Threshold is configurable via the Enterprise Partner Portal. Markaaz will setup your account with the recommended setting. Scores falling below the threshold are considered to be non-matches.

The new Markaaz Search API relies on fewer required inputs thus is less exact when compared to a matching API with more input data points. Search is configured to return a maximum of 10 business entities and there is no threshold to be used as a filter on the search score. Active businesses will be returned first. You may notice Inactive businesses have a higher search score in some circumstances based on the comparison of inputs.

Tip: If you can provide input values for optional fields, you should; this gives the algorithm additional data for comparison.

Listed below are all of the response data fields Markaaz will return from the Business Verification APIs. Please refer to the API Reference to fully understand the entire structure of each API response.

API Responses

Each API call returns a Markaaz ID and basic business identity information, the bizInfo object, as shown below. Markaaz ID is the unique identifier for a business entry in the Markaaz Directory. The bizInfo response object is the distinctly identifying data for a business entity. Each Verification API will also return the object requested, e.g. firmographic, business health, compliance, diversity or P2B.

Biz Info Object

This object is common to most API responses where applicable, including the Match API.

FieldValuesDesc.
businessIndicator"Y' or empty stringBusiness indicator: Indicates this business is located at an address identified by the US Postal Service (USPS) as commercial/business. This field is either a 'Y or blank'.
residentialIndicator"Y' or empty stringResidential indicator: Indicates this business is located at an address identified by the US Postal Service (USPS) as residential. This field is either a 'Y or blank'.
sohoIndicator"Y' or empty stringSOHO indicator: Indicates this location qualifies as a small office/home office business. Eligibility based on residential address indicator, primary industry, number of employees, etc. This field is either a 'Y or blank'.
geoprecision255: Rooftop,
9: Full Zip+4,
7: Zip+2,
5: Zip only
Geo-precision refers to the level of precision in longitude and latitude:
   "bizInfo": {  
      "dba": "",  
      "legalName": "",  
      "taxId": "",  
      "nationalId": "",  
      "addresses": [  
        {  
          "type": "",  
          "line1": "",  
          "line2": "",  
          "locality": "",  
          "region": "",  
          "country": "",  
          "postalCode": "",  
          "latitude": "",  
          "longitude": "",  
          "geoprecision":"",  
          "businessIndicator": "",  
          "residentialIndicator":"",  
          "sohoIndicator": ""  
        }  
      ]  
    }
    

Firmographic

businessSizeDescription
S (small)Indicates all the attributes required for the computation were available and the business qualifies as small. The computation uses US SBA rules for determining small. If it is not calculated as small it gets assigned as large.
L (large)Indicates all the attributes required for the computation were available and the business does not qualify as small.
X (unknown)Indicates one or more attributes required for the computation were missing.
salesVolumePrecision / salesVolumeLocPrecisionDescription
ACTUALActual - Audited figures.
ESTEstimated - in the absence of audited figures, estimates are otherwise provided by the company.
MDLModeled - Based on the industry type and number of employees, we can model the revenue. Trends of the industry are factored into the model.

    "firmographic": {
      "legalStructure": "",
      "yearEstablished": 0,
      "noOfEmployees": 0,
      "noOfEmployeesLoc": 0,
      "salesVolume": 0,
      "salesVolumePrecision": "",
      "salesVolumeLoc": 0,
      "salesVolumeLocPrecision": ""
      "primaryNaics": "",
      "secondaryNaics1": "",
      "secondaryNaics2": "",
      "secondaryNaics3": "",
      "secondaryNaics4": "",
      "businessSize": "",
      "contact": {
        "website": "",
        "countryCallingCode": "",
        "phone": "",
        "fax": ""
      },
      "officers": [
      {
        "officerid": null,
        "fullName": "",
        "title": "",
        "position": "",
        "currentStatus": ""
      }
      ],
      "PrimaryContact": {
        "FullName": "",
        "TitleCode": "",
        "Title": "",
        "FirstName": "",
        "LastName": "",
        "Email": ""
      },
      "metadata": {
        "hasCompanyHierarchy": ""
      }
    }

Business Health

FieldValuesDescription
bankruptcy"Y" or nullIndicates a history of bankruptcy.
markaazBusinessFailureRiskScore10-1, 0 or nullIndicates the risk of failure. A zero (0) indicates bankruptcy. Otherwise, the higher the score the greater the risk of failure.
markaazCreditRiskScore103-600 or nullA USA business credit risk score. The lower the value the greater the risk.
markaazGlobalCreditRiskScore1-5 or nullA normalized credit risk score. The lower the value the greater the risk.
   "businessHealth": {
      "bankruptcy": "",
      "markaazFailureRiskScore": 0,
      "markaazCreditRiskScore": 0,
      "markaazGlobalCreditRiskScore": 0
    }

Compliance

    "complianceSummary": {
      "activeSanctions": 0,
      "activeInsolvency": 0,
      "activePoliticallyExposedPersons": 0,
      "activeAdverseMedia": 0,
      "activeLawEnforcement": 0
    },
    "complianceDetails": {
      "evidences": [],
      "pep": [],
      "adverseMedia": [],
      "lawEnforcement": [],
      "insolvency": [],
      "sanctions": {}
    }

Company Hierarchy

In the Markaaz Firmographic API response there is a metadata field, hasCompanyHierarchy. If this is returned as Yes then there is some structure to the business. If it is returned as "No" you should not call the hierarchy API. The hierarchy API response will have a parentTypeCode to indicate the nature of the other associated entities as indicated by the code. The parentTypeCode information is shown in the following table.

parentTypeCodeDescriptionDefinition
9000Subsidiary Parent (Immediate)A site that is registered on its own and files its taxes separately and has its own financial and legal responsibility, but is currently owned by another commercial legal entity.
9001Domestic ParentHighest level parent for a specific country, not always the Global Ultimate. It is calculated at the time of delivery to a customer based on the following rule: report the highest parent in the family tree within the same country as the site location.
9002Global ParentThe top site within a Corporate Family Tree; typically the company headquarters
9003Affiliate Global ParentThis is designed to represent non-ownership relationships for a limited number of family trees. An example of this would be a Allstate Insurance single site, single owner franchisee. From a legal perspective this is simply a small business, Allstate Insurance corporate has no equity in the business nor legal responsibility for the debts of this firm. This is the traditional “risk” view of the business that is appropriate when it comes to extending credit. However, there is a business relationship in place between the franchise store and the franchisor – Allstate Insurance . In some cases it is helpful for marketing purposes to “link” all of the Allstate Insurance locations together as a brand family.
    "companyHierarchy": [
      {
        "parentMarkaazId": "",
        "markaazId": "",
        "companyLegalName": "",
        "contact": {
          "phoneNumber": "",
          "countryCallingCode": "",
          "website": ""
        },
        "parentTypeCode": "9xxx",
        "companyName": "",
        "addresses": [
          {
            "type": "",
            "line1": "",
            "line2": "",
            "locality": "",
            "region": "",
            "regionAbbreviation": "",
            "country": "",
            "postalCode": ""
          }
        ]
      }
    ]
  }

Diversity

    "diversity": {
      "minorityIndicator": "",
      "veteranOwnedIndicator": "",
      "womenOwnedIndicator": ""
    }

P2B Name Match

Parameters for P2B Matching

P2B verification relies on a similarity-based name matching algorithm that compares input names to officers and contacts listed in business records. Using the Enterprise Portal, we set two thresholds to classify the matching results. You may change the similarity threshold values from within the Markaaz Enterprise Portal, but we recommend you choose the thresholds wisely based on your business rules. Our recommendation is that you should not change the Upper value. A value of 89 gives the best result for confirmed matches.

  • Results with similarity greater than, or equal to the upper threshold are catalogued as "matches"
  • Results with similarity between the lower and upper thresholds are considered "potential matches" and worthy of further review however, the match result is still a No. The match grade in the response should be used to determine if any additional review is warranted.
  • Results with similarity less than the lower threshold are considered "non-matches"
Similarity ThresholdDefault value
Upper89 or higher
Lower75 or lower
FieldValuesDescription
matched"Y" or "N"This indicates whether the name provided matches a name found in the list of officers or the primary contact.
messagestringThis is a message indicating the name is a match, is not a match, or is a potential match. The latter will indicate that additional due diligence or examination may be required based on your business rules & processes. A potential match will be shown as a "N" in the matched field.
officerIdnullThis is for future use.
matchGrade0-100An indication of the quality of the match. It is this match grade, in conjunction with the P2B thresholds that determine whether there is a match, a possible match or no match.
    "nameMatchResults": [
      {
        "matched": "",
        "message": "",
        "nameMatchRequested": "",
        "nameMatched": "",
        "officerid": null,
        "matchGrade": 0
      }
    ],
    "primaryContact": {
      "fullName": "",
      "titleCode": "",
      "title": "",
      "firstName": "",
      "lastName": "",
      "cmail": ""
    },
    "officers": [
      {
        "officerid": null,
        "fullName": "",
        "title": "",
        "position": "",
        "currentStatus": ""
      }
    ],
  }
}