# Tutorials and Guides
source: https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/index.md

## Endpoint Overview {#endpoint-overview}

Merchant Identifier enriches client data through a "match and append" methodology. First, using the input criteria provided by
the client, the API finds the matching merchant location within Mastercard's comprehensive merchant reference dataset.
Next, select attributes about that merchant are appended and provided in the API's response payload.

Four matching pathways are available, and should be chosen based on the client's native data
(also see the [Which Endpoint Should I Use?](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/index.md#Which-Endpoint-Should-I-Use?) section below).

## Which Endpoint Should I Use? {#which-endpoint-should-i-use}

Merchant Identifier supports multiple enrichment pathways depending on **what merchant data you already have** and **what you're trying to achieve**.
Tip: Ask yourself one question first:  
**Do I already have a stable merchant identifier, or only descriptive data?**

### If you have a stable merchant identifier {#if-you-have-a-stable-merchant-identifier}

#### 1. Endpoint: Search by card acceptor id {#1-endpoint-search-by-card-acceptor-id}

###### /merchants-by-card-acceptor-ids {#merchants-by-card-acceptor-ids}

<br />

**Use when:**

* You have a known acquirer Card Acceptor ID
* You want to enrich a specific merchant location

**Example input:**

```PLAIN
card_acceptor_id                123456
country_code                    BRA
```


[Learn more →](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/lookup-by-acceptor-id/index.md)

#### 2. Endpoint: Search for merchants by tax id {#2-endpoint-search-for-merchants-by-tax-id}

###### /merchants-by-tax-ids {#merchants-by-tax-ids}

<br />

**Use when:**

* You have a merchant tax identifier (country-specific)
* You want enrichment for a single merchant entity

**Example input:**

```PLAIN
tax_id                       123456
country_code                 BRA
```


[Learn more →](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/lookup-by-tax-id/index.md)

### If you do NOT have a stable merchant identifier {#if-you-do-not-have-a-stable-merchant-identifier}

#### 3. Endpoint: Search for merchants by descriptor {#3-endpoint-search-for-merchants-by-descriptor}

###### /merchants {#merchants}

<br />

**Use when:**

* Your input comes directly from transaction descriptors
* Merchant data is free-text and payment-formatted

**Example input:**

```PLAIN
  merchant_descriptor     JOHNDOERETAILNEWYORKNY
```


[Learn more →](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/search-by-descriptor/index.md)

#### 4. Endpoint: Search for merchants using AI {#4-endpoint-search-for-merchants-using-ai}

###### /merchants/searches {#merchantssearches}

<br />

**Use when:**

* You have a merchant location record (name + city/state/country)
* Your data may be incomplete, inconsistent, or noisy
* You desire higher match reliability with a tradeoff of higher latency (this endpoint has the most latency)

**Example input:**

```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"
    }
  ]
}
```


[Learn more →](https://developer.mastercard.com/merchant-identifier/documentation/tutorials-and-guides/search-with-ai/index.md)

<br />

<br />

### Pulling a list of multiple merchant locations {#pulling-a-list-of-multiple-merchant-locations}

The Merchant Identifier service does not pull a list of multiple merchant locations. If this is your use case, please see: [Places API documentation](https://developer.mastercard.com/places/documentation/).

**Use when:**

* You want a list of merchant locations satisfying a given scope
* Your query is geographic or criteria-based

<br />

**Example input:** "All Walmart stores in Houston, TX"

### Related use cases not supported today {#related-use-cases-not-supported-today}

The following use cases are not currently available but in development. To learn more about upcoming functionality, please contact your Mastercard representative or click contact sales via the link below.

* **Brand-level enrichment**
  * Example input: "Walmart"
  * With an expected response of brand-level attributes
* **Multi-entity transaction resolution**
  * Example input: "PP\* DOORDASH: Walmart #123 Houston TX"
  * With an expected response of entity-level enrichment across multiple entity types within an unstructured string (merchant, marketplace, payment facilitator, agents provider, etc.)

## Want further support? {#want-further-support}

For more support and consultation on how to optimally use these endpoints, [contact our Sales team here](https://www.mastercard.com/us/en/demo-request.html).