Docs

Confidence and source

How sure we are, and where an answer came from.

Every result carries a confidence between 0 and 1 and a source saying how the merchant was found. Use them to decide what to show your users and what to review.

Source

Descriptors fall through four steps, cheapest first, and the first one that answers wins:

source	Meaning	Typical confidence
cache	We have resolved this exact descriptor before, and return that answer.	Same as the original answer
rules	A merchant pattern matched: exact, prefix or regex.	0.85 to 0.97
fuzzy	The descriptor closely matches a known merchant name, for example with a typo or truncation.	0.74 to 0.90
ai	A language model identified the merchant. The answer is cached and queued for review by our team.	at most 0.85

When nothing matches, source is null, merchant is null and confidence is 0.

Verified

verified: true means the merchant record was approved by a person on our team. AI suggestions are unverified until reviewed, and until then their merchant.id is null.

Choosing a threshold

0.85 and above: show the merchant as fact.
0.6 to 0.85: show it, but consider letting users correct it.
Below 0.6: show the cleaned descriptor (normalized) instead of a merchant.

These are starting points; tune them on your own data.

Try it

Runs through the playground, no key needed

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);

{ "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 }