Log in Get API keyGet a free API key

Docs

Errors

Every error has the same shape and a stable code.

Errors use standard HTTP status codes and always have the same JSON shape, with a stable machine-readable code, a human-readable message, and the request_id:

{
  "error": {
    "code": "invalid_request",
    "message": "descriptor is required.",
    "request_id": "req_01JABCDEF0123456789ABCDEFG"
  }
}

Branch on code, not on message: messages may be reworded, codes will not change.

Error codes

Status	Code	What to do
400	`invalid_request`	Fix the request. The message names the field, for example a country that is not a two-letter code.
401	`unauthorized`	Check the API key. See Authentication.
402	`quota_exceeded`	Your monthly quota is used up. Wait for the next month or upgrade. See Rate limits and quotas.
404	`not_found`	The merchant ID or route does not exist.
429	`rate_limited`	Slow down and retry after the number of seconds in the `Retry-After` header.
500	`internal_error`	Retry with backoff. If it persists, contact us with the `request_id`.

No match is not an error

When we cannot identify a merchant, /v1/enrich still returns 200, with merchant: null and confidence: 0. These results are not billed.

Errors inside a batch

In /v1/enrich/batch, an invalid item gets an error object in its place (with code and message) and the other items are processed normally. See Batch enrichment.

Retrying

Retry 429 after Retry-After, and 500 or network errors with exponential backoff. Do not retry 400, 401 or 402 without changing something first. Enrichment is safe to retry: the same descriptor gives the same answer.

Try it

Runs through the playground, no key needed

Request

curl https://api.descriptorapi.com/v1/enrich \
  -X POST \
  -H "Authorization: Bearer $DESCRIPTORAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}'

body := strings.NewReader(`{"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}`)
req, _ := http.NewRequest("POST", "https://api.descriptorapi.com/v1/enrich", body)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+os.Getenv("DESCRIPTORAPI_KEY"))
resp, err := http.DefaultClient.Do(req)

const res = await fetch("https://api.descriptorapi.com/v1/enrich", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DESCRIPTORAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.descriptorapi.com/v1/enrich",
    headers={"Authorization": f"Bearer {os.environ['DESCRIPTORAPI_KEY']}"},
    json={"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"},
    timeout=10,
)
data = res.json()

$ch = curl_init("https://api.descriptorapi.com/v1/enrich");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => '{"descriptor": "POS 4521 CAREEM*RIDE DXB AE", "country": "AE", "mcc": "4121"}',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DESCRIPTORAPI_KEY'),
        'Content-Type: application/json',
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

{
  "descriptor": "POS 4521 CAREEM*RIDE DXB AE",
  "normalized": "CAREEM RIDE",
  "merchant": {
    "id": "mer_01M4TKG2681HHBYZWQE4FEQARK",
    "name": "Careem",
    "legal_name": null,
    "website": "https://www.careem.com",
    "logo_url": "https://cdn.descriptorapi.com/logos/careem-218be11e.png",
    "category": "transportation",
    "subcategory": "ride_hailing",
    "mcc": "4121"
  },
  "location": {
    "city": "Dubai",
    "country": "AE"
  },
  "processor": null,
  "is_subscription": false,
  "confidence": 0.97,
  "source": "cache",
  "verified": true
}