Docs

One endpoint: send raw transaction descriptors, get back a cleaned merchant name, one of our categories, and a confidence score from 0 to 1. Results are automated suggestions. They can be wrong, especially for small or local merchants, so check anything that matters (taxes, bookkeeping) yourself.

Authentication

Header: Authorization: Bearer <your key>. X-API-Key: <your key> also works. Keys start with mcl_. Get a free key at /signup. Keep keys server-side.

POST /v1/clean

Single: {"descriptor": "...", "mcc": "5411", "amount": -12.5} (mcc and amount optional). Batch: {"descriptors": [ ... ]} with up to 10 items on Free and 100 on Starter and Scale; each item is a string or an object like the single form.

Example request

curl -X POST https://merchantcleanup.pages.dev/v1/clean \
  -H "Authorization: Bearer mcl_your_key" \
  -H "Content-Type: application/json" \
  -d '{"descriptor": "POS PURCHASE SQ *MAPLE STREET COFFEE 1234 OAKLAND CA"}'

Example response

{
  "input": "POS PURCHASE SQ *MAPLE STREET COFFEE 1234 OAKLAND CA",
  "merchant": "Maple Street Coffee",
  "category": "meals",
  "confidence": 0.6,
  "match": "keyword",
  "processor": "Square"
}

Batch body

{"descriptors": [
  "TST* JOES DINER #0042 AUSTIN TX",
  {"descriptor": "MAPLE STREET MARKET 0091", "mcc": "5411", "amount": -42.10}
]}

Batch responses are {"results": [...], "count": N} in input order. An item that cannot be read returns {"input": ..., "error": "..."} in its slot and is still returned.

Response fields

Other endpoints

• GET /v1/demo?q=... - keyless demo, one descriptor per request, limited per IP per day
• GET /v1/categories - category list
• POST /v1/refresh (with your paid key) - checks your subscription with Stripe and returns a new key with a fresh expiry (up to 35 days). Inactive subscription: 402
• /openapi.json (OpenAPI 3.1) and /postman.json (Postman collection)

Limits

Plans differ by speed and batch size. There is no monthly call count.

• Limits are per key and per minute (UTC clock minute). Over the limit you get 429 rate_limited with a Retry-After header. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining.
• Limits are counted in memory on each server instance, so they are approximate: your requests may be spread over several instances and sometimes get more than the listed rate. We do not promise more than the listed rate.
• Each request is up to 64 KB; each descriptor up to 300 characters.
• Keys are signed and not stored by us. Free keys are valid for 2 years. Paid keys are valid for up to 35 days and are renewed with POST /v1/refresh while your subscription is active; after a cancel, a key stops working when it expires.

Business Days & Holidays add-on

National public holidays for 26 countries (US, CA, GB, IE, AU, NZ, DE, FR, ES, IT, NL, BE, AT, CH, SE, NO, DK, FI, PL, PT, CZ, JP, SG, MX, BR, ZA), years 2025 to 2028. Weekend is Saturday and Sunday for every country. For GB, a holiday that falls on a weekend is listed only on its substitute weekday, named "(substitute day)", as on gov.uk; other countries may list both the actual date and an "(observed)" date. Add subdiv (a state, province or region code, for example subdiv=CA for California or subdiv=SCT for Scotland) to any endpoint to include that region's holidays; codes are listed at /v1/holidays/countries. Without subdiv you get nationwide holidays only, except GB, which defaults to England and Wales (ENG). Data is generated from the open-source python-holidays project (MIT licence, notice). Dates can be wrong or change; check anything that matters.

Same key and header as /v1/clean. Holiday endpoints have their own per-minute limit per key: 5 requests a minute without the add-on, 120 with Holidays Basic ($5/month, pricing). A Holidays Basic purchase issues its own key; on it, /v1/clean uses Free plan limits. Holidays Pro is coming soon. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining.

• GET /v1/holidays?country=US&year=2026 - list of {date, name}
• GET /v1/is-business-day?country=GB&date=2026-12-28 - business_day, weekend, holiday (name or null)
• GET /v1/business-days?country=DE&start=2026-12-01&end=2026-12-31 - inclusive counts, up to 731 days
• GET /v1/add-business-days?country=US&date=2026-11-25&days=3 - moves forward (or back with a negative number, up to 1000) skipping weekends and holidays
• GET /v1/holidays/countries - countries, subdivision codes, defaults and coverage gaps (no key, not counted)

Coverage gaps

Without subdiv, only nationwide public holidays are returned. Not covered anywhere: municipal or city holidays, bank-only or school holidays, half days, and one-off holidays declared after the data was built.

curl "https://merchantcleanup.pages.dev/v1/add-business-days?country=US&date=2026-11-25&days=3" -H "Authorization: Bearer mcl_your_key"
{"country":"US","date":"2026-11-25","days":3,"result":"2026-12-01"}

Errors: 400 bad_country / bad_subdiv / bad_year / bad_date / bad_range / bad_days / out_of_range; 429 rate_limited.

CORS

CORS is enabled for all origins (Access-Control-Allow-Origin: *, methods GET, POST, OPTIONS). That lets you try the API from a browser, but do not put a key in public front-end code.

Errors

Errors look like {"error": {"code": "rate_limited", "message": "..."}}.

Data

We do not store descriptors you send. We do not store your key: it is signed, and we check the signature on each call.