API Documentation

Everything you need to integrate transaction enrichment into your application.

Quick Start

Get started with the Easy Enrichment API in just a few minutes. Here's a simple example to enrich a transaction:

bash

curl -X POST https://api.easyenrichment.com/enrich \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "AMZN MKTP US*2K4X9Y1Z0"}'

Base URL

All API requests should be made to: https://api.easyenrichment.com

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

http

Authorization: Bearer enrich_xxxxxxxxxxxx

Getting Your API Key

to get your API key.

Keep Your Key Secret

Never expose your API key in client-side code or public repositories.

Pricing & Billing

Easy Enrichment uses simple per-request pricing: from 1¢ to 2¢ per request depending on your plan.

Flat Rate

1-2¢ per request

Buy $100 in credits for the best rate (1¢). Smaller purchases start at 2¢ per call.

Volume Discounts

Buy more credits, get bonus credits. $25+ gets 10% bonus, $50+ gets 20%, and $100+ gets 30% extra credits.

The response includes a billing object showing the cost charged and your remaining balance.

Billing Response Example

json

{
  "success": true,
  "data": { ... },
  "billing": {
    "cost_cents": 1,
    "balance_cents": 19
  }
}

Free Trial

New accounts start with 20 free API calls. No credit card required. See pricing to add more.

Enrich Transaction

Enrich a single transaction description to get merchant details, category, and more.

POST/enrich

Request Body

Parameter	Type	Required	Description
description	string	Yes	The raw transaction description

Example Request

javascript

const response = await fetch('https://api.easyenrichment.com/enrich', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'UBER *TRIP HELP.UBER.COM'
  })
});

const data = await response.json();
console.log(data);

Batch Enrichment

Enrich multiple transactions in a single API call (up to 100 transactions per request).

POST/enrich/batch

Request Body

Parameter	Type	Required	Description
transactions	array	Yes	Array of transaction descriptions (max 100)

Example Request

javascript

const response = await fetch('https://api.easyenrichment.com/enrich/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    transactions: [
      'NETFLIX.COM',
      'SPOTIFY SUBSCRIPTION',
      'AMZN MKTP US*2K4X9Y1Z0'
    ]
  })
});

const data = await response.json();

Response Format

Every successful response includes detailed merchant information with the following fields:

Field	Type	Description
merchant_name	string	Clean, readable merchant name
category	string	Primary spending category
categories	string[]	Array of applicable categories
subcategory	string	More specific category classification
business_type	string	Type of business (e.g., "E-commerce Platform")
mcc_code	string	Standard Merchant Category Code
is_chain	boolean	Whether merchant is part of a chain
is_subscription	boolean	Whether this is a recurring payment
is_online_only	boolean	Whether merchant operates online only
domain	string	Merchant website domain
logo_url	string	URL to merchant logo (via Logo.dev)
brand_id	string	Unique brand identifier
country	string	Country code (ISO 3166-1 alpha-2)
contact_phone	string	Customer support phone number
contact_email	string	Customer support email
support_url	string	URL to support page
co2_category	string	Carbon footprint category (low/medium/high)
confidence	number	Confidence score (0-1)
description	string	Human-readable transaction description

⚠️

Logo URLs

Logo URLs are served via Logo.dev. To display logos on your domain, you must add your domain to Logo.dev's allowed domains list at logo.dev. Only HTTPS domains are supported.

Example Response

json

{
  "success": true,
  "data": {
    "original_description": "UBER *TRIP HELP.UBER.COM",
    "merchant_name": "Uber",
    "category": "Transportation",
    "categories": ["Rideshare", "Transportation", "Travel"],
    "subcategory": "Rideshare Services",
    "business_type": "Transportation Network",
    "mcc_code": "4121",
    "is_chain": true,
    "is_subscription": false,
    "is_online_only": false,
    "domain": "uber.com",
    "logo_url": "https://img.logo.dev/uber.com?token=pk_xxx&size=128",
    "brand_id": "uber_global",
    "country": "US",
    "contact_phone": "+1-800-593-7069",
    "contact_email": "support@uber.com",
    "support_url": "https://help.uber.com",
    "co2_category": "medium",
    "confidence": 0.97,
    "description": "Uber rideshare trip"
  }
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

Code	Description
200	Success - Request completed
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
402	Payment Required - Insufficient balance
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong

Error Response Format

json

{
  "success": false,
  "error": "Insufficient balance. Please add funds to continue."
}

Code Examples

Ready-to-use code examples in popular programming languages.

Python

python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.easyenrichment.com"

def enrich_transaction(description):
    response = requests.post(
        f"{BASE_URL}/enrich",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={"description": description}
    )
    return response.json()

# Example usage
result = enrich_transaction("STARBUCKS STORE 12345")
print(result["data"]["merchant_name"])  # "Starbucks"

Node.js

javascript

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.easyenrichment.com';

async function enrichTransaction(description) {
  const response = await fetch(`${BASE_URL}/enrich`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ description })
  });
  return response.json();
}

// Example usage
const result = await enrichTransaction('STARBUCKS STORE 12345');
console.log(result.data.merchant_name); // "Starbucks"

cURL

bash

curl -X POST https://api.easyenrichment.com/enrich \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "STARBUCKS STORE 12345"}'

Rate Limits

To ensure fair usage, the API has the following rate limits:

100

requests per minute

10,000

requests per day

Need higher limits? Contact us for enterprise plans.