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 examples of the data fields Markaaz will expect when calling the Business Verification APIs. Please refer to the API Reference to fully understand the entire structure of each API input / response.

{
  "markaazId": "AZ0000055945770"
}

📘

Some Test Markaaz IDs:

• Markaaz ID AZ0000017866926 - Google
• Markaaz ID AZ0004011901661 - Loop 1 Photography, LLC.
• Markaaz ID AZ0004010591485 - Saunderstown Yacht Club
• Markaaz ID AZ0003100128078 CSM CORPORATION BERHAD
• Markaaz ID AZ0003072719974 NEW HOONG FATT HOLDINGS BERHAD
• Markaaz ID AZ0003081136605 LBS BINA GROUP BERHAD
• Markaaz ID AZ0003118635493 Hunter Douglas Holding GmbH & Co. KG
• Markaaz ID AZ0003113715998 Newsfactory GmbH
• Markaaz ID AZ0003114013902 PROXIA Software AG
• Markaaz ID AZ0003068750437 ONCODESIGN SERVICES
• Markaaz ID AZ0003084008342 NATIXIS
• Markaaz ID AZ0003109027762 INSTALLUX SA
• Markaaz ID AZ0003008320893 T H KENYON HOLDINGS LIMITED
• Markaaz ID AZ0003003087659 FALLOWS PRINT LIMITED
• Markaaz ID AZ0003002467799 S.J.BARGH LIMITED
• Markaaz ID AZ0000107193330 AMSOIL,INC.
• Markaaz ID AZ0000067210687 FIRMIN PRINTING & OFFICE EQUIPMENT COMPANY
• Markaaz ID AZ0000112269101 Welsh Facilities Services, LLC

The input payload above works for all of the Business Verification API's except for the P2B Name Match API, which also requires inputs for namesToMatch in the form of an array. You may pass in a full name, or firstName, lastName, etc. Please refer to the API reference for more details.

{
  "data": {
    "markaazId": "<markaaz id>",
    "namesToMatch": [
      {
        "fullName": "<full name 1>"
      },
      {
        "fullName": "<full name 2>"
      },
      {
        "firstName": "John",
        "lastName": "Doe",
        "suffix": "Jr"
      }
    ]
  }
}

Business Verification 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 all API responses, where applicable, including the Matching and Search APIs.

   "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

Sample Markaaz ID's: AZ0000005951279, AZ0004012702409, AZ0004005310087, AZ0004005878923, AZ0000015902871, AZ0002000942854, AZ0000040601317, AZ0004008176944, AZ0004007381937

    "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": ""
      }
    ],
  }
}