--- updatedAt: 2026-06-03T16:27:31.000Z agentTools: projectIndex: https://developer.markaaz.com/llms.txt --- # Markaaz Advanced Match Markaaz Advanced Match # 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/advanced-match": { "post": { "operationId": "v2.0_business_advanced-match_create", "summary": "Markaaz Advanced Match", "description": "Markaaz Advanced Match", "parameters": [ { "name": "x-partner-id", "in": "header", "description": "Partner Id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkaazAdvanceMatchRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkaazAdvanceMatchResponse" } } } }, "207": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiStatusResponse" } } } }, "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 } } }, "BizInfoRequest": { "required": [ "legalName", "address", "locality", "postalCode", "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, "minLength": 1 }, "address": { "title": "Address", "type": "string", "maxLength": 500, "minLength": 1 }, "locality": { "title": "Locality", "type": "string", "maxLength": 500, "minLength": 1 }, "region": { "title": "Region", "type": "string", "maxLength": 500, "nullable": true }, "postalCode": { "title": "Postalcode", "type": "string", "maxLength": 200, "minLength": 1 }, "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" }, "maxItems": 1, "description": "An array containing a single name object used to match against the Primary Contact of the business." } } }, "MarkaazAdvanceMatchRequest": { "required": [ "bizInfo" ], "type": "object", "properties": { "matchCount": { "title": "Matchcount", "type": "integer", "default": 1, "maximum": 10, "minimum": 1, "nullable": true }, "showNonMatches": { "title": "Shownonmatches", "type": "boolean", "default": false, "nullable": true }, "showGrades": { "title": "Showgrades", "type": "boolean", "default": false, "nullable": true }, "bizInfo": { "$ref": "#/components/schemas/BizInfoRequest" }, "matchConfidenceThresholdOverride": { "title": "Matchconfidencethresholdoverride", "type": "string", "nullable": true, "description": "Per-request override of the Markaaz Match Confidence Score Threshold configured in the Settings of the Markaaz Enterprise Portal. Valid values in .1 increments: 1.0 to 10.0. Does not change the configured default.", "minimum": 1, "maximum": 10 } } }, "MarkaazAdvanceMatchResponse": { "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" }, "matchResults": { "title": "matchResults", "description": "Markaaz results", "type": "array", "items": { "type": "object", "properties": { "markaazId": { "title": "markaazId", "description": "Markaaz ID", "type": "string" }, "markaazMatchConfidenceScore": { "title": "markaazMatchConfidenceScore", "description": "The match confidence score is an analysis of the match confidence level on a 10 to 1 scale. Match 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" }, "matchConfidenceThreshold": { "title": "matchConfidenceThreshold", "description": "The Markaaz Match Confidence Threshold is used in matching where API inputs are compared against the business entities in the Markaaz Directory of over 300 million businesses. The lower the threshold setting, the less confident we will be in providing a good match to your inputs. The current recommended setting is a value of 8.3 to achieve a high-confidence match.", "type": "number" }, "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": 500 }, "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" }, "MultiStatusResponse": { "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" }, "markaazMatchConfidenceScore": { "title": "markaazMatchConfidenceScore", "description": "Markaaz Match Confidence Score", "type": "number" }, "messageId": { "title": "messageId", "description": "Message Id", "type": "number" } } } }, "title": "No Content Response", "description": "No Content Response Data" }, "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" } } } } ```