Skip to main content

API Reference

Base URL: https://api.openaggr.com/v1. All requests must use HTTPS. Request bodies and responses are JSON. Three endpoints: POST /enrich for transaction categorization and merchant enrichment, POST /cashflow for 30-day cashflow forecasting, POST /merchant-resolve for standalone name normalization and MCC lookup.

Authentication

Pass your API key in the Authorization header as a Bearer token:

Authorization: Bearer oagg_sk_test_abc123...

Sandbox keys (prefix oagg_sk_test_) are free and limited to 10,000 calls/month. Production keys (prefix oagg_sk_live_) require a paid plan.

POST /enrich

Enriches a single raw transaction string. Returns merchant name, category, subcategory, confidence score, MCC code, and geo data.

Request body

{
  "transaction": "string, required",    // raw bank transaction string
  "transaction_id": "string, optional"  // your reference ID, passed through
}

Response fields

{
  "transaction_id": "string",
  "merchant_name": "string",
  "merchant_raw": "string",
  "category": "string",
  "subcategory": "string | null",
  "confidence": number,          // 0.0 to 1.0
  "mcc_code": "string | null",
  "mcc_label": "string | null",
  "city": "string | null",
  "state": "string | null",
  "category_color": "string",    // hex color token
  "logo_available": boolean,
  "latency_ms": number
}

POST /cashflow

Takes an array of enriched transaction objects and returns a 30-day per-category spending forecast with income/expense separation.

Request body

{
  "transactions": [               // array of enriched transaction objects
    {
      "transaction_id": "string",
      "category": "string",
      "amount": number,             // USD, positive = debit
      "date": "ISO 8601 date string"
    }
  ],
  "forecast_days": 30             // default 30, max 90
}

POST /merchant-resolve

Resolves a raw merchant string to a clean merchant object. Use independently if you only need name normalization and MCC lookup.

Request body

{
  "merchant_string": "string, required"
}

Rate limits

Rate limit headers are returned on every response:

  • X-RateLimit-Limit: requests allowed per minute
  • X-RateLimit-Remaining: requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp of window reset

When you exceed the limit, a 429 Too Many Requests response is returned with a Retry-After header.

Error codes

All errors return a JSON body with code and message fields:

{
  "code": "invalid_transaction",
  "message": "transaction field is required and must be a non-empty string"
}

Webhooks

Subscribe to enrichment.completed events for batch processing. POST your endpoint URL in the dashboard. Each webhook event is signed with your webhook secret using HMAC-SHA256. Validate with the X-Oagg-Signature header.