# Search - AI Powered
source: https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/search-with-ai/index.md

Enrich merchant information from **flexible, real-world inputs** using AI-driven semantic matching.

This endpoint goes beyond traditional string matching. You can provide structured merchant details across multiple fields, **or**
submit a raw, unstructured string in a single field -- and the AI interprets the contextual signals within your input to find the
right merchant. The result is **higher match rates and better enrichment quality**, even when your data is messy: truncated,
noisy, or inconsistently formatted.
Alert: This endpoint currently searches for merchants located in the **USA** only. Other geographies coming soon.

## Why AI-powered matching? {#why-ai-powered-matching}

Traditional matching breaks down when input data doesn't line up character-for-character. Semantic matching understands *intent and context* instead.

#### Traditional string matching {#traditional-string-matching}

* Relies on close, **character-level similarity**
* Struggles with truncated or reordered text
* Misses matches when formatting is inconsistent

#### AI semantic matching {#ai-semantic-matching}

* Interprets **contextual signals** within the input
* Resilient to noisy, incomplete, or messy data
* Maximizes match coverage and enrichment quality
Tip: Curious how Mastercard handles your data? See [Responsible AI and Data Governance](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/search-with-ai/index.md#responsible-ai-and-data-governance) below.

## Endpoint {#endpoint}

**RESTful POST Request**

API Reference: `POST /merchants/searches`

## Request: Choose your input mode {#request-choose-your-input-mode}

This endpoint supports **both structured and unstructured** merchant inputs. Pick whichever fits the data you already have.

Populate the `merchantName` field with the merchant name, then provide additional attributes such as address, city, state,
country, phone number, or URL in their respective fields. These fields are interpreted as structured merchant attributes and used **collectively** to improve match accuracy.

```json
{
  "merchants": [
    {
      "merchantName": "JOHN DOE RETAIL #1847",
      "streetAddress": "123 Acme Street",
      "cityName": "NEW YORK",
      "stateProvinceCode": "NY",
      "countryCode": "USA",
      "postalCode": "10001",
      "phoneNumber": "(212) 555-0184",
      "url": "www.johndoeretail.com"
    }
  ]
}
```

Provide all available merchant details as a single, **space-delimited string** in the `merchantName` field -- preferably in this
order: `merchant_name, street, city, state, zipcode, country, website, phone`. Any fields you don't have can be omitted. In this mode, all other input fields are optional and may be left empty.

```json
{
  "merchants": [
    {
      "merchantName": "JOHN DOE RETAIL NEWYORK NY"
    }
  ]
}
```

## Response {#response}

The response returns standardized, enriched merchant details. Note the AI-specific **`matchProbability`** field -- a value between `0` and `1` indicating the model's confidence in the match.

```json
{
  "merchants": [
    {
      "merchantName": "JOHN DOE RETAIL",
      "matchProbability": 0.81,
      "streetAddress": "STREET 67899",
      "cityName": "NEW YORK",
      "postalCode": "12345",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "brandName": "JOHN DOE RETAILERS",
      "phoneNumber": "7149628500",
      "merchantCategory": "5411 - GROCERY STORE AND SUPERMARKET",
      "legalCorporateName": "JOHN DOE LLC",
      "locationId": 1174012564,
      "isBrickAndMortar": true,
      "isEcommerce": false,
      "url": "WWW.JOHNDOERETAIL.COM"
    }
  ]
}
```

Tip: The `locationId` returned here can be used to pull additional merchant information from the [Mastercard Places API](https://developer.mastercard.com/places/documentation/).

## Responsible AI and Data Governance {#responsible-ai-and-data-governance}

This endpoint has been designed and deployed in accordance with Mastercard's enterprise standards for **Responsible AI, Data Privacy, and Security**.

#### Your data is never used to train AI models {#your-data-is-never-used-to-train-ai-models}

Client data is processed **solely** for merchant matching and enrichment.

#### No data is fabricated {#no-data-is-fabricated}

The returned payload is pulled by matching to **verified records** in Mastercard's merchant database. Where a confident match
cannot be made, the endpoint returns a lower probability score or no match -- it will **never** generate data to fill gaps.

#### No data is retained beyond processing {#no-data-is-retained-beyond-processing}

Client input data is **not stored** or repurposed for any means beyond the execution and operation of this API service.