--- updatedAt: 2026-06-03T16:27:31.000Z agentTools: projectIndex: https://developer.markaaz.com/llms.txt --- # Markaaz Search API Markaaz Search API # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Markaaz API Services 2.0", "description": "Markaaz API Services 2.0", "termsOfService": "https://markaaz.com/terms-and-conditions/", "contact": { "email": "support@markaaz.com" }, "license": { "name": "Copyright ©2023 Markaaz Inc. All rights reserved." }, "version": "v2.0" }, "security": [ { "Partner_API_Key": [] } ], "paths": { "/v2.0/business/search": { "post": { "operationId": "v2.0_business_search_create", "summary": "Markaaz Search API", "description": "Markaaz Search API", "parameters": [ { "name": "x-partner-id", "in": "header", "description": "Partner Id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkaazSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkaazSearchResponse" } } } }, "207": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiStatusResponseForSearchAPI" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnAuthorizedBizResponse" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundResponse" } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorBizResponse" } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayTimeoutResponse" } } } } }, "tags": [ "Markaaz Business Match" ] }, "parameters": [] } }, "servers": [ { "url": "https://api-partner-sandbox.app.markaaz.com" }, { "url": "http://api-partner-sandbox.app.markaaz.com" } ], "components": { "securitySchemes": { "Partner_API_Key": { "type": "apiKey", "description": "Partner API Key", "name": "x-api-key", "in": "header" } }, "schemas": { "Names": { "type": "object", "properties": { "fullName": { "title": "Fullname", "type": "string", "maxLength": 200, "nullable": true } } }, "BadRequestResponse": { "required": [ "markaaz" ], "type": "object", "properties": { "markaaz": { "title": "markaaz", "description": "Markaaz Root", "type": "object", "properties": { "traceId": { "title": "traceId", "description": "Trace ID (UUID)", "type": "string" }, "message": { "title": "message", "description": "Message", "type": "string" }, "messageId": { "title": "messageId", "description": "Message Id", "type": "integer" }, "errors": { "title": "errors", "description": "errors", "type": "object" } } } }, "title": "Bad Request Response", "description": "Bad Request Response Data" }, "UnAuthorizedBizResponse": { "required": [ "markaaz" ], "type": "object", "properties": { "markaaz": { "title": "markaaz", "description": "Markaaz Root", "type": "object", "properties": { "traceId": { "title": "traceId", "description": "Trace ID (UUID)", "type": "string" }, "message": { "title": "message", "description": "Message", "type": "string" }, "messageId": { "title": "messageId", "description": "Message Id", "type": "integer" } } } }, "title": "UnAuthorized Response", "description": "UnAuthorized Response Data" }, "ResourceNotFoundResponse": { "required": [ "markaaz" ], "type": "object", "properties": { "markaaz": { "title": "markaaz", "description": "Markaaz Root", "type": "object", "properties": { "traceId": { "title": "traceId", "description": "Trace ID (UUID)", "type": "string" }, "message": { "title": "message", "description": "Message", "type": "string" }, "messageId": { "title": "messageId", "description": "Message Id", "type": "number" } } } }, "title": "Resource Not Found", "description": "Resource Not Found or bad URL" }, "TooManyRequestsResponse": { "required": [ "markaaz" ], "type": "object", "properties": { "markaaz": { "title": "markaaz", "description": "Markaaz Root", "type": "object", "properties": { "traceId": { "title": "traceId", "description": "Trace ID (UUID)", "type": "string" }, "message": { "title": "message", "description": "Message", "type": "string" }, "messageId": { "title": "messageId", "description": "Message Id", "type": "number" } } } }, "title": "Too Many Requests", "description": "Too many requests. Please try again later." }, "ServerErrorBizResponse": { "required": [ "markaaz" ], "type": "object", "properties": { "markaaz": { "title": "markaaz", "description": "Markaaz Root", "type": "object", "properties": { "traceId": { "title": "traceId", "description": "Trace ID (UUID)", "type": "string" }, "message": { "title": "message", "description": "Message", "type": "string" }, "messageId": { "title": "messageId", "description": "Message Id", "type": "number" }, "errors": { "title": "errors", "description": "Errors", "type": "string" } } } }, "title": "Server Error Response", "description": "Server Error Response Data" }, "GatewayTimeoutResponse": { "required": [ "markaaz" ], "type": "object", "properties": { "markaaz": { "title": "markaaz", "description": "Markaaz Root", "type": "object", "properties": { "traceId": { "title": "traceId", "description": "Trace ID (UUID)", "type": "string" }, "message": { "title": "message", "description": "Message", "type": "string" }, "messageId": { "title": "messageId", "description": "Message Id", "type": "integer" } } } }, "title": "Gateway Timeout Error Response", "description": "Gateway Timeout Error Response Data" }, "SearchApiRequestFields": { "required": [ "country" ], "type": "object", "properties": { "epInternalId": { "title": "Epinternalid", "type": "string", "maxLength": 250, "nullable": true, "description": "A unique business identifier in the partners backend system. This can be provided for easier traceability between a partner system and a Markaaz ID." }, "dba": { "title": "Dba", "type": "string", "maxLength": 1000, "nullable": true }, "legalName": { "title": "Legalname", "type": "string", "maxLength": 1000, "nullable": true }, "address": { "title": "Address", "type": "string", "maxLength": 500, "nullable": true }, "locality": { "title": "Locality", "type": "string", "maxLength": 500, "nullable": true }, "region": { "title": "Region", "type": "string", "maxLength": 500, "nullable": true }, "postalCode": { "title": "Postalcode", "type": "string", "maxLength": 200, "nullable": true }, "country": { "title": "Country", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW", "AX", "XK" ] }, "phoneNo": { "title": "Phoneno", "type": "string", "maxLength": 500, "nullable": true }, "website": { "title": "Website", "type": "string", "maxLength": 500, "nullable": true }, "taxId": { "title": "Taxid", "type": "string", "maxLength": 100, "nullable": true }, "nationalId": { "title": "Nationalid", "type": "string", "maxLength": 500, "nullable": true }, "names": { "type": "array", "items": { "$ref": "#/components/schemas/Names" } } } }, "MarkaazSearchRequest": { "required": [ "bizInfo" ], "type": "object", "properties": { "bizInfo": { "$ref": "#/components/schemas/SearchApiRequestFields" } } }, "MarkaazSearchResponse": { "type": "object", "properties": { "markaaz": { "title": "markaaz", "description": "Markaaz root", "type": "object", "properties": { "traceId": { "title": "traceId", "description": "Trace ID (UUID)", "type": "string" }, "searchResults": { "title": "searchResults", "description": "Search results", "type": "array", "items": { "type": "object", "properties": { "markaazId": { "title": "markaazId", "description": "Markaaz ID", "type": "string" }, "markaazSearchConfidenceScore": { "title": "markaazSearchConfidenceScore", "description": "The search confidence score is an analysis of the search confidence level on a 10 to 1 scale. Search Confidence is strongest at 10 (representing a very high level of the match on all data elements present) and weakest at 1 (representing a match on Name only).", "type": "number" }, "companyStatus": { "title": "companyStatus", "description": "Company Status", "type": "string" }, "epInternalId": { "title": "epInternalId", "description": "A unique business identifier in the partners backend system. This can be provided for easier traceability between a partner system and a Markaaz ID. Matching does not store the epInternalId.", "type": "string", "maxLength": 250 }, "bizInfo": { "title": "bizInfo", "description": "Biz Info Response", "type": "object", "properties": { "dba": { "title": "DBA", "description": "Doing Business As", "type": "string", "maxLength": 1000 }, "legalName": { "title": "legalName", "description": "Business Legal Name", "type": "string", "maxLength": 1000 }, "taxId": { "title": "taxId", "description": "Business Tax Id", "type": "string", "maxLength": 100 }, "nationalId": { "title": "nationalId", "description": "National Id", "type": "string", "maxLength": 500 }, "website": { "title": "website", "description": "Website", "type": "string", "maxLength": 500 }, "phoneNumber": { "title": "phoneNumber", "description": "Phone Number", "type": "string", "maxLength": 500 }, "addresses": { "title": "addresses", "description": "Addresses", "type": "array", "items": { "title": "AddressesItem", "description": "Addresses", "type": "object", "properties": { "type": { "title": "type", "description": "Indicates the type of address such as Primary, Registered or Secondary.", "type": "string" }, "line1": { "title": "line1", "description": "The first line of the address.", "type": "string" }, "line2": { "title": "line2", "description": "The second line of the address", "type": "string" }, "locality": { "title": "locality", "description": "The locality or city in which the business is based in.", "type": "string" }, "region": { "title": "region", "description": "The region or state in which the business is based in.", "type": "string" }, "postalCode": { "title": "postalCode", "description": "The postal code of the area in which the business is based in.", "type": "string" }, "country": { "title": "country", "description": "The country where the business is based in.", "type": "string" }, "latitude": { "title": "latitude", "description": "The latitude of the location of the business.", "type": "string" }, "longitude": { "title": "longitude", "description": "The longitude of the location of the business.", "type": "string" }, "geoprecision": { "title": "geoprecision", "description": "The geoprecision field.", "type": "string" }, "businessIndicator": { "title": "businessIndicator", "description": "The businessIndicator field.", "type": "string" }, "residentialIndicator": { "title": "residentialIndicator", "description": "The residentialIndicator field.", "type": "string" }, "sohoIndicator": { "title": "sohoIndicator", "description": "The small office home office inidcator.", "type": "string" } } } } } }, "primaryContact": { "title": "primaryContact", "description": "Primary contact", "type": "object", "properties": { "fullName": { "title": "fullName", "description": "First Name", "type": "string" }, "titleCode": { "title": "titleCode", "description": "Title code", "type": "string" }, "title": { "title": "title", "description": "Tite", "type": "string" }, "firstName": { "title": "firstName", "description": "First name", "type": "string" }, "lastName": { "title": "lastName", "description": "Last name", "type": "string" }, "email": { "title": "email", "description": "Email", "type": "string" } } }, "metaData": { "title": "metaData", "description": "This section shows matching grade on each input parameter", "type": "object", "properties": { "dba": { "title": "dba", "description": "DBA", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "companyLegalName": { "title": "companyLegalName", "description": "Company Legal Name", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "address": { "title": "address", "description": "Address", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "locality": { "title": "locality", "description": "Locality", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "region": { "title": "region", "description": "Region", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "postalCode": { "title": "postalCode", "description": "Postal Code", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "nationalId": { "title": "nationalId", "description": "National ID", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "taxId": { "title": "taxId", "description": "Tax ID", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "phoneNumber": { "title": "phoneNumber", "description": "Phone Number", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "website": { "title": "website", "description": "Website", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } }, "contactName": { "title": "contactName", "description": "Contact Name", "type": "object", "properties": { "grade": { "title": "grade", "description": "Grade A - the grade A means exact match, Grade B - the grade of B is a similar match with at least one common token, Grade C - the grade of C is a partial match with zero or one common token, Grade F - the grade of F means no match, Grade F - If a value for the field is provided in the input payload but not available in our Directory (i.e. no value in the response payload), we return grade as F – No Match, Grade Z - If field value is not provided in the input payload, we return the grade as Z.", "type": "string" } } } } } } } } } } }, "title": "markaaz", "description": "Markaaz root" }, "MultiStatusResponseForSearchAPI": { "required": [ "markaaz" ], "type": "object", "properties": { "markaaz": { "title": "markaaz", "description": "Markaaz Root", "type": "object", "properties": { "traceId": { "title": "traceId", "description": "Trace ID (UUID)", "type": "string" }, "message": { "title": "message", "description": "Message", "type": "string" }, "markaazSearchConfidenceScore": { "title": "markaazSearchConfidenceScore", "description": "Markaaz Search Confidence Score", "type": "number" }, "messageId": { "title": "messageId", "description": "Message Id", "type": "number" } } } }, "title": "No Content Response", "description": "No Content Response Data" } } } } ```