Skip to main content
REST API

One POST request. Structured transaction data back.

Send the raw string exactly as it arrives from your bank feed or payment processor. Receive merchant name, category, subcategory, confidence score, MCC code, and geo data in a single JSON response. No pre-cleaning required on your side.

Get API Key Full Reference
curl example
$ curl https://api.openaggr.com/v1/enrich \
  -H "Authorization: Bearer oagg_sk_..." \
  -d '{"transaction": "WHOLEFDS MKT #12345 AUSTIN TX"}'
200 OK, 42ms
Response
"merchant_name": "Whole Foods Market",
"category": "Food and Drink",
"subcategory": "Groceries",
"confidence": 0.99
Core Endpoints

Three enrichment endpoints

Use them independently or chain them. /enrich is the primary call. /cashflow takes the enriched output from /enrich as input. /merchant-resolve can run standalone when you only need name normalization and MCC lookup. All accept JSON, all return JSON. Base URL: https://api.openaggr.com/v1

POST
/enrich
Classifies a transaction string into merchant name, category, subcategory, confidence score, MCC code, and geo data. The primary enrichment call.
returns: merchant, category, confidence, mcc, geo
POST
/cashflow
Takes an array of enriched transactions and returns a 30-day per-category spending forecast with income/expense separation and recurring charge isolation.
returns: forecast, recurring_charges, net_position
POST
/merchant-resolve
Resolves a raw merchant string to a clean merchant object with name normalization, MCC code, and logo availability flag. Use independently from /enrich.
returns: name, mcc, city, logo_available
Response Schema

Every field explained

The full annotated response from a POST /enrich call. All fields are present on every response; null where data is unavailable.

200 OK 38ms
{
"transaction_id": "txn_abc123", // your original ID passed through
"merchant_name": "Whole Foods Market",
"merchant_raw": "WHOLEFDS MKT #12345 AUSTIN TX",
"category": "Food and Drink",
"subcategory": "Groceries",
"confidence": 0.99, // 0.0 to 1.0
"mcc_code": "5411",
"mcc_label": "Grocery Stores and Supermarkets",
"city": "Austin",
"state": "TX",
"category_color": "#22C55E",
"logo_available": true,
"latency_ms": 38
}
SDKs

Official client libraries

Install your language's client, set your API key as an environment variable, and make your first enrichment call in under 10 lines of code. All SDKs are typed and include auto-retry on 429 and 5xx responses.

Node.js
npm install openaggr
View guide
Python
pip install openaggr
View guide
Ruby
gem install openaggr
View guide
Go
go get openaggr/sdk-go
View guide
Authentication

API key authentication. Two environments.

How to authenticate
Pass your API key in the Authorization header as a Bearer token. All requests must use HTTPS.
Authorization: Bearer oagg_sk_live_...
Key types
Sandbox keys (prefix oagg_sk_test_) are free, rate-limited to 10,000 calls/month, and return realistic enrichment results. Production keys (oagg_sk_live_) require a Growth or Scale plan.
Rate limits
Sandbox: 100 req/min. Growth: 1,000 req/min. Scale: custom. Rate limit headers returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Error format
All errors return a JSON object with code and message fields. HTTP status codes follow REST conventions (401, 429, 422, 500).

Ready to enrich your first transaction?

Get a free Sandbox key and send any raw transaction string. The Sandbox environment returns the same enriched output as production, so you can build against real response shapes before upgrading.

Get API Key Full API Reference