Skip to main content
Context.dev’s Transaction Enrichment API takes a raw card or ACH descriptor (e.g., AMZN*MKTP US) and returns:
  • title and domain: clean company name and domain
  • logos: SVG/PNG variants in light, dark, and on-background modes
  • colors: hex codes of colors from the merchant’s logo
  • industries.eic: industry + subindustry classification
  • stock: ticker and exchange for publicly traded merchants
  • And more: socials, address, links, description, slogan
Our database has 50M+ identified merchants. You can also find small and local merchants by passing mcc, city, country_gl, or phone.

Integrate Context.dev's Transaction Enrichment endpoint in your app

Open in Cursor

​
Prerequisites

  • A Context.dev API key. Sign up at context.dev/signup, copy the key from the dashboard (prefix ctxt_secret_), and export it: 
    export CONTEXT_DEV_API_KEY="ctxt_secret_..."
  • An SDK (optional). Install for your language, or skip the install and call directly with curl: 
    npm install context.dev

​
Identify a transaction

GET /brand/transaction_identifier takes a raw descriptor and resolves it to a merchant brand. Pass MCC and geography hints when you have them: they collapse ambiguity sharply on small or regional merchants. 
curl -G https://api.context.dev/v1/brand/transaction_identifier \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "transaction_info=STARBUCKS STORE 12345" \
  --data-urlencode "mcc=5814" \
  --data-urlencode "country_gl=us"
10 credits per successful call

​
Request Parameters

ParameterTypeDescription
transaction_infostringRequired. Raw transaction descriptor (e.g. AMZN MKTP US*2X7Y8Z, SQ *COFFEE SHOP NYC).
mccstring4-digit Merchant Category Code. The resolver maintains an MCC database with specific descriptions; otherwise it falls back to a general category based on the code range. Examples: 5411 grocery, 5814 fast food / takeout, 5812 restaurants, 5942 book stores, 4121 taxis & limousines.
country_glstring (ISO 3166-1 alpha-2, lowercase)Country hint for geographic disambiguation. Examples: us, gb, ca, au. Every alpha-2 code is supported.
citystringCity hint to prioritize local branches or regional brand variants. Free-form; standard names work best (e.g. San Francisco, New York).
phonenumberPhone number from the transaction descriptor, when present, to help verify the brand match.
high_confidence_onlybooleanWhen true, runs additional verification and returns 400 instead of a low-confidence match. Use for spend analytics, compliance, or expense flows. Defaults to false.
force_languagestringForce the language of the retrieved brand data.
maxSpeedbooleanSkip time-consuming operations for a faster, less complete response. Defaults to false.
timeoutMSintegerAbort with a 408 if the request exceeds this many milliseconds. Min 1000, max 300000 (5 min).

​
Response

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "starbucks.com",
    "title": "Starbucks",
    "description": "Starbucks is a global coffee company that puts people at the heart of its business…",
    "slogan": "Inspiring and nurturing the human spirit — one person, one cup",
    "colors": [
      { "hex": "#0bac66", "name": "Secret Garden" },
      { "hex": "#7cd4b4", "name": "Seafoam Blue" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/67dc7846-2ca2-4a7b-9877-6bb5a5e2c0e0.png",
        "mode": "has_opaque_background",
        "type": "icon",
        "colors": [{ "hex": "#0bac66", "name": "Secret Garden" }],
        "resolution": { "width": 180, "height": 180, "aspect_ratio": 1 }
      }
    ],
    "socials": [
      { "type": "x", "url": "https://x.com/starbucks" },
      { "type": "facebook", "url": "https://facebook.com/starbucks" },
      { "type": "instagram", "url": "https://instagram.com/starbucks" }
    ],
    "address": {
      "street": "2401 Utah Avenue South",
      "city": "Seattle",
      "state_province": "Washington",
      "state_code": "WA",
      "country": "United States",
      "country_code": "US",
      "postal_code": "98134"
    },
    "stock": { "ticker": "SBUX", "exchange": "NASDAQ" },
    "industries": {
      "eic": [
        {
          "industry": "Retail & E-commerce",
          "subindustry": "Omnichannel & In-Store Retail"
        }
      ]
    },
    "primary_language": "english",
    "is_nsfw": false
  }
}
FieldTypeDescription
statusstring"ok" on success.
codeintegerHTTP status code, echoed for convenience.
brand.domainstringCanonical merchant domain.
brand.titlestringClean company name.
brand.descriptionstringOne-paragraph company description.
brand.sloganstringMarketing tagline, when available.
brand.colors[]arrayBrand colors ordered by visual prominence. Each has hex and a human-readable name.
brand.logos[]arrayLogo variants: url, mode (light / dark / has_opaque_background), type (logo / icon), colors, and resolution.{width, height, aspect_ratio}.
brand.socials[]arraySocial profile URLs. type is one of x, facebook, instagram, linkedin, youtube, tiktok, github, and 20+ more.
brand.addressobjectHQ address: street, city, state_province, state_code, country, country_code, postal_code.
brand.stockobjectticker and exchange for publicly traded merchants. null for private companies.
brand.industries.eic[]arrayEIC industry tags with industry and subindustry. For NAICS / SIC codes, call /web/naics or /web/sic.
brand.linksobjectNon-social URLs: blog, pricing, careers, contact, privacy, terms, login, signup.
brand.primary_languagestringDetected language of the merchant’s website (e.g. english, spanish).
brand.is_nsfwbooleanSafe-content flag.

​
Handle errors

StatusMeaningWhat to do
400The descriptor couldn’t be identified (no confident brand match), high_confidence_only blocked a low-confidence hit, or transaction_info is missing.Fall back to a cleaned descriptor + an MCC-based category icon. Cache the miss for at least 24 hours so retries don’t burn credits.
401Missing or invalid API key.Re-check the env var and the dashboard.
429Rate limit.Back off exponentially.
A fallback pattern that surfaces 400 as a “no match” outcome instead of an exception: 
import ContextDev from "context.dev";

const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });

async function enrichOrFallback(transaction: {
  description: string;
  mcc?: string;
  country?: string;
}) {
  try {
    const { brand } = await client.brand.identifyFromTransaction({
      transaction_info: transaction.description,
      mcc: transaction.mcc,
      country_gl: transaction.country,
    });
    return brand;
  } catch (err: any) {
    if (err.status === 400) return null; // no confident match
    throw err;
  }
}
For the full error code catalog, see Troubleshooting.

​
Use cases

  • Personal finance apps: show actual company logos and clean names for every merchant and subscription.
  • Reconcile employee expense reports automatically: match messy expense entries to clean company names, logos, and categories.

​
Next steps

Prefetch for Faster Response

Hide cold-hit latency from your users.

Handle Rate Limits

Backoff strategies, client cache, and prefetch fallbacks.

Best Practices

Caching, error handling, and key hygiene.

Troubleshooting

Status codes, retry patterns, and common errors.