Skip to main content

Quickstart Guide

This guide walks you through making your first POST /enrich call. You will get a Sandbox API key, send a raw transaction string exactly as it arrives from your bank feed or payment processor, and parse the enriched response. Estimated time: 5 minutes.

1
Get your API key

Create a free account at openaggr.com/register. Your Sandbox key is issued instantly. It looks like oagg_sk_test_abc123... and allows 10,000 enrichments per month at no cost.

2
Make your first POST /enrich call

Send a raw transaction string. The string should be exactly what your payment processor or bank feed returns, no cleaning required.

curl -X POST https://api.openaggr.com/v1/enrich \
  -H "Authorization: Bearer oagg_sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction": "WHOLEFDS MKT #12345 0612 AUSTIN TX", "transaction_id": "my-txn-001"}'
3
Parse the response fields

The response includes the merchant name, category, subcategory, confidence score, MCC code, and geo data. All fields are present on every response; null where data is unavailable.

{
  "transaction_id": "my-txn-001",
  "merchant_name": "Whole Foods Market",
  "category": "Food and Drink",
  "subcategory": "Groceries",
  "confidence": 0.99,
  "mcc_code": "5411",
  "city": "Austin",
  "state": "TX",
  "category_color": "#22C55E",
  "latency_ms": 41
}
4
Map categories to your UI

Use the category_color hex token directly in your spending breakdown UI. The color is consistent across every call: #EF4444 for Food and Drink, #F59E0B for Transport, #22C55E for Groceries, #3B82F6 for Travel. Your UI does not need a lookup table.

For the full taxonomy with all color tokens and subcategory depth, see the API Reference or the Product page.

Using the Node.js SDK

Install the SDK and make the same call with typed parameters and auto-retry:

import Openaggr from 'openaggr';

const client = new Openaggr({ apiKey: process.env.OAGG_API_KEY });

const result = await client.enrich({
  transaction: 'WHOLEFDS MKT #12345 AUSTIN TX',
  transactionId: 'my-txn-001'
});

console.log(result.category);    // "Food and Drink"
console.log(result.merchantName); // "Whole Foods Market"
console.log(result.confidence);   // 0.99

Next steps