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.

📘

You may notice that sometimes field values contain the empty string "" and at other times the same fields may be null. This is in part, because we will always respond with all of the objects that you would see if the response payload were 100% populated. If we don't have any data for an object, like primaryContact for example, the fields values will be null. If there is one field populated in primaryContact, then the fields with no data available will be the empty string, "". There are some exceptions to this as with numerical values where zero is valid. For those fields we return null when the value is unknown and zero (0) where it is known and that is the value we have for the record.

Biz Info Object

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

   "bizInfo": {  
      "dba": "",  
      "legalName": "",  
      "taxId": "",  
      "nationalId": "",  
      "addresses": [  
        {  
          "type": "",  
          "line1": "",  
          "line2": "",  
          "locality": "",  
          "region": "",  
          "country": "",  
          "postalCode": "",  
          "latitude": "",  
          "longitude": "",  
          "geoprecision":"",  
          "businessIndicator": "",  
          "residentialIndicator":"",  
          "sohoIndicator": ""  
        }  
      ]  
    }
    

Firmographic

        "firmographic": {
            "legalStructure": "",
            "yearEstablished": 0,
            "noOfEmployees": 0,
            "noOfEmployeesLoc": 0,
            "companyStatus": "",
            "registrationDate": "",
            "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

   "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.

    "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"

    "nameMatchResults": [
      {
        "matched": "",
        "message": "",
        "nameMatchRequested": "",
        "nameMatched": "",
        "officerid": null,
        "matchGrade": 0
      }
    ],
    "primaryContact": {
      "fullName": "",
      "titleCode": "",
      "title": "",
      "firstName": "",
      "lastName": "",
      "cmail": ""
    },
    "officers": [
      {
        "officerid": null,
        "fullName": "",
        "title": "",
        "position": "",
        "currentStatus": ""
      }
    ],
  }
}