Integration

API Architecture

There are two flavors of API in each suite, POST and GET. The POST APIs require 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 GET APIs have a required parameter markaazid. This is the identifier in the Markaaz Business Directory unique for each entity. With a Markaaz ID, Firmographic Data is not required with one exception which is the API request for Get Markaaz ID. This API would be used to get a markaazid and all subsequent calls to any GET API would then use that id and thus eliminate the necessity to provide firmographic data for each API GET request.

📘

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

Each API request will subsequently receive one of the following response codes: 200, 207, 400, 403, or 500. A 200 response indicates that Markaaz found the information requested and will be delivered in the documented response format in the API Reference section.

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 match confidence score. The format of 207 responses will always include a traceId, a message, a matchConfidenceScore, and a messageID. The message will provide insight into why a 200 response was not returned.

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

Possible 207 response messages

The 400 and 500 series codes are fairly self explanatory in nature but also provide specifics when possible.

Sample 400 Response - Bad Request

{
  "trace_id": "68a1eead-69d5-46b9-9a1c-4c42ae90a495",
  "response_status": 400,
  "response_msg": "failed",
  "errors": {
    "markaazId": [
      "This field is required."
    ]
  }
}

Sample 403 Response - Authentication Issue

Message indicating a bad api key.

{
  "message": "Forbidden"
}

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 Suite

These API's enable enterprises to build on the Business Verification APIs and apply a set of preconfigured rules across 12 metrics in real-time to supply an application decision and the details behind that decision based on metrics 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.