API reference
Enrich one descriptor
POST/v1/enrich
Normalizes the descriptor and resolves the merchant from, in order: the cache of previously seen descriptors, merchant rules, fuzzy matching and (for descriptors never seen before) an AI model.
When nothing can be determined the response is still 200, with merchant: null and confidence: 0. The API never invents a merchant.
Request body
| Field | Type | Description |
|---|---|---|
descriptorrequired |
string | The raw statement line, exactly as your bank or processor provides it. |
country |
string | Optional ISO 3166-1 alpha-2 hint (card or account country). Improves accuracy. |
mcc |
string | Optional merchant category code from the card network. |
amount |
number | Optional. Accepted and validated; not used for matching yet. |
currency |
string | Optional ISO 4217 code. Accepted and validated; not used for matching yet. |
Response
| Field | Type | Description |
|---|---|---|
descriptorrequired |
string | The descriptor you sent. |
normalizedrequired |
string | The cleaned merchant part of the descriptor. |
merchantrequired |
object | null | |
idrequired |
string | null | Merchant ID, or null for an AI suggestion that has not been reviewed yet. |
namerequired |
string | |
legal_namerequired |
string | null | |
websiterequired |
string | null | |
logo_urlrequired |
string | null | |
categoryrequired |
string | Top-level category ID |
subcategoryrequired |
string | null | |
mccrequired |
string | null | |
locationrequired |
object | null | Where the transaction happened, from the descriptor or your country hint. |
cityrequired |
string | null | |
countryrequired |
string | null | ISO 3166-1 alpha-2. |
processorrequired |
string | null | Aggregator or wallet detected in the descriptor (PayPal, Square, Apple Pay, Tabby, ...). |
is_subscriptionrequired |
boolean | |
confidencerequired |
number | 0 when nothing was found. |
sourcerequired |
string | null | How the merchant was resolved; null when nothing was found. One of: |
verifiedrequired |
boolean | True only when the merchant record has been approved by our team. |
request_idrequired |
string | Unique ID of this request. |
Status codes
-
200
Enrichment result.
-
400
The request is malformed or a field is invalid.
Error code
invalid_request -
401
Missing, invalid or revoked API key, or a suspended account.
Error code
unauthorized -
402
HTTP 402. The monthly quota of your plan is used up (or a batch is larger than what is left). Quotas reset at the start of each UTC month.
Error code
quota_exceeded -
429
Too many requests per second. Retry after the number of seconds in
Retry-After.Error code
rate_limited -
500
Something went wrong on our side.
Error code
internal_error