> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notte.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant resolution

> Turn a raw card-statement descriptor into a merchant profile

> [!TIP]
>
> Read [the Notte skill](https://notte.cc/skill.md) and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

`POST /data/brand/retrieve` with `"type": "by_transaction"` takes the messy text from a card or bank statement and returns the merchant behind it, using the same profile as [Company enrichment](https://docs.notte.cc/data-apis/company-enrichment.md).

> [card] [Try it in the Console](https://console.notte.cc/data-apis/merchants)
>
> Try this API in the playground, no code needed.

## Quick start

```bash theme={null}
curl -X POST https://api.notte.cc/data/brand/retrieve \
  -H "Authorization: Bearer $NOTTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "by_transaction",
    "transaction_info": "STARBUCKS STORE 12345 SEATTLE WA",
    "country_gl": "us"
  }'
```

```json theme={null}
{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "starbucks.com",
    "title": "Starbucks Coffee Company",
    "colors": [{ "hex": "#00754a", "source": "site" }],
    "logos": [{ "url": "https://www.starbucks.com/assets/icons/siren.svg", "type": "logo" }]
  }
}
```

## Parameters

**type** `string` *required*

Always `by_transaction`.

**transaction\_info** `string` *required*

The descriptor text, 3 to 500 characters.

**country\_gl** `string`

Country code to narrow the match, for example `us`.

**city** `string`

City from the transaction.

**mcc** `string`

Merchant category code.

**phone** `string`

Merchant phone number from the transaction.

**high\_confidence\_only** `boolean` (default: false)

Only return a match when the API is confident.

**maxSpeed** `boolean` (default: false)

Prioritize speed.

**timeoutOpts** `object`

`milliseconds` and `behavior`: `fail` or `return-partial`.

**tags** `string[]`

Free-form labels attached to the request.

## When no merchant is found

If the descriptor can't be resolved reliably, the API returns:

```json theme={null}
{
  "error_code": "NOT_FOUND",
  "message": "The merchant could not be identified reliably.",
  "request_id": "..."
}
```

Add `city`, `mcc` or `phone` and retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.