---
title: "Search for merchants using AI"
method: POST
path: "/merchants/searches"
tags: ["Merchants"]
---

# Search for merchants using AI

`POST /merchants/searches`

## Request

- Base URL: `https://api.mastercard.com/merchant-identifier`
- URL: `https://api.mastercard.com/merchant-identifier/merchants/searches`
- Auth: none declared
- TypeScript: <https://skmtc.dev/mastercard/apis/merchant-identifier-api/docs/merchants/searches/post.ts> (a function with typed inputs; its response is checked against the schema)

Returns detailed information on merchants based on the provided input data

## Request body

- MerchantSearchList: List of merchants
  - `merchants` MerchantSearch[]: merchants
    - `merchantName` string: The name of merchant being queried
    - `streetAddress` string: The street address of the merchant being queried. Should include the street number and name, but not city, state, or postal code
    - `cityName` string: The city where the merchant being queried is located
    - `postalCode` string: The postal code associated with the merchant’s location
    - `stateProvinceCode` string: The state or province code of the merchant being queried.
    - `countryCode` string: The country code of the merchant being queried.
    - `phoneNumber` string: The phone number for the merchant.
    - `url` string: The merchant’s website or primary online presence URL

## Response `200`

Information for this merchant identifier search

- MerchantBySearchList: List of merchants
  - `merchants` MerchantBySearch[]: merchants
    - `merchantName` string: The business name of the merchant
    - `matchProbability` number, double: Confidence score (%) to help clients understand the quality of the search results
    - `streetAddress` string: The street address of the merchant being queried. Should include the street number and name, but not city, state, or postal code
    - `cityName` string: The city where the merchant is located
    - `postalCode` string: The postal code associated with the merchant’s location
    - `countrySubdivisionCode` string: The state or province code of the merchant.
    - `countrySubdivisionName` string: The state or province name of the merchant.
    - `countryCode` string: The country code of the merchant.
    - `countryName` string: The country Name of the merchant.
    - `brandName` string: The brand name of the merchant
    - `legalCorporateName` string: Corporate legal name of the merchant
    - `locationId` integer: Merchant specific location identifier
    - `merchantCategory` string: Merchant category code and description associated with the merchant category code for the merchant
    - `phoneNumber` string: The phone number of the merchant
    - `isBrickAndMortar` boolean: Indicates whether the input descriptor is used by the merchant for brick-and-mortar (card-present) transactions
    - `isEcommerce` boolean: Indicates whether the input descriptor is used by the merchant for e-commerce (card-not-present) transactions
    - `url` string: The merchant’s website or primary online presence URL

## Other responses

- `400`: Something was wrong with the request.
- `401`: Authentication information was missing or invalid.
- `403`: Insufficient permissions for interacting with the resource.

---

[API](https://skmtc.dev/mastercard/apis/merchant-identifier-api.md) - [All operations](https://skmtc.dev/mastercard/apis/merchant-identifier-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mastercard/apis/merchant-identifier-api/revisions/9cf3031bbd2e?raw)