v2.0 API Integration

API Architecture

Most APIs are called via POST requests. Matching requires some information about the business (name & address) in the body parameters for the Business Info object which is used to match or identify the business entity in the Markaaz directory. The API returns a Markaaz ID, which is the unique identifier in the Markaaz Business Directory for each entity, and basic business identifying information in the bizInfo response object. Armed with a Markaaz ID, the business verification, business decision, P2B and other APIs are able to be called to retrieve more detailed information about the business.

📘

REST

The Markaaz APIs are organized around REST. The API uses predictable, resource-oriented URLs and HTTP status codes to indicate errors. It is important to check the status codes returned and handle any errors accordingly in your implementation.

🚧

HTTPS

The Markaaz APIs require all communications to be secured using TLS 1.2 or greater.

If you are connecting from Windows 7 or equivalent then you may need to upgrade to TLS 1.2.

📘

Request Headers

Clients must send appropriate headers with all requests.

HTTP Response Codes

A 200 response indicates that Markaaz found the information requested and will deliver it following the response format described in the API Reference section. If a response code other than a 200 is received it means we could not successfully deliver the deliver the data you requested. We have strived to provide a meaningful message in the non-200 responses to help you understand why we could not provide the response you were hoping for. Please review the information below and the full list of response codes in the Overview section here HTTP Response Code Details

A 207 response indicates the data you requested cannot be returned for a variety of reasons. For example, if an incorrect city, state and zip are provided as input, it is very unlikely the API will be able to find the correct match in the directory and you may see a message similar to the one below indicating a low Markaaz match confidence score. The format of 207 responses will always include a traceId, a message, and a messageID. The message will provide insight into why a 200 response was not returned. Your integration should check the response codes and handle the exceptions (non 200 responses) appropriately. Your integration code should also check the messageID and apply your business rules for a resolution. In the example below, it would be wise to verify the legal name and address of the business since the data provided resulted in a low markaazMatchConfidenceScore.

📘

Markaaz Match Confidence Threshold

The markaazMatchConfidenceScore is an evaluation on how well the business data you pass into the Markaaz Match API aligns with the data in our Directory. The Markaaz Match Confidence Threshold is a setting in the Enterprise Portal that governs the quality level of that match returned by the API. Generally a threshold of around 8.3 is a good starting point. A default threshold value will be configured for you during implementation.

A traceId is of use to Markaaz support should you experience an error condition that is not able to be otherwise explained based on the response message. If you contact us regarding an API response, providing the traceId will allow us to more quickly troubleshoot any potential issue. Otherwise you don't need to track or maintain the traceId.

{
  "traceId": "f059b365-a8d0-4c66-98ee-68fcd37a889e",
  "message": "Did not meet the high confidence match set",
  "markaazMatchConfidenceScore": 5.33,
  "messageId": 1001
}

A few example response messages

View the full list of responses HTTP Response Codes

The 400 and 500 series codes can be fairly self explanatory in nature but when possible we provide specifics about the error. As a best practice, when practical, your code should write the response out to a log file anytime you receive 400 or 500 series message, including the traceId, if provided.

Sample 400 Response - Bad Request

{
    "markaaz": {
        "traceId": "c32d8b38-2515-4541-9f36-7b240ffd2c40",
        "message": "failed - missing required field.",
        "messageId": 4001,
        "errors": {
            "bizInfo": {
                "legalName": [
                    "This field may not be blank."
                ]
            }
        }
    }
}

{
    "markaaz": {
        "traceId": "c32d8b38-2515-4541-9f36-7b240ffd2c40",
        "message": "Invalid request body",
        "messageId": 4002
    }
}

Sample 403 Response - Authentication Issue

Message indicating a bad or missing api key.

{
  "markaaz": {
    "traceId": "",
    "message": "Forbidden",
    "messageId": 4102
  }
}

Sample 404 Response - Resource not found

Perhaps the endpoint is invalid.

{
    "markaaz": {
        "traceId": "09e5eb9c-b841-408e-9b72-873cd07e6abe",
        "message": "Resource not found",
        "messageId": 4106
    }
}

The Business Verification API Suite

These APIs enable enterprises to tap into the Markaaz Directory in real-time to verify small business applicants. With just a few variables, the Business Verification API searches the Markaaz Directory and delivers Firmographic Data, Compliance AML Data and Business Health Data. This API suite is comprised of multiple API endpoints that are able to return a customized selection of our approximate 200 data points about the business you are attempting to verify based on your unique needs.

The Business Decisioning API

This API's enables enterprises to build on the Business Verification APIs and apply a set of configurable rules across 12 metrics in real-time to supply an application or onboarding decision and the details behind that decision based on thresholds you set. To ensure a standardized set of metrics are used for each API request, the Markaaz Enterprise Portal is used to manage the business rules for these metrics.