Introduction

The Sona API gives you programmatic access to real-time transaction enrichment, merchant identification, and categorization at scale.

Base URL: All API requests are made to https://api.sona.dev/v2

Authentication

Authenticate requests by including your API key in the Authorization header. You can manage API keys from your dashboard.

        Request Header
        bash
      

$ curl https://api.sona.dev/v2/enrich \
  -H "Authorization: Bearer cnp_sk_live_..." \
  -H "Content-Type: application/json"

Quick Start

Enrich your first transaction in under 60 seconds. Send a POST request with the raw transaction data and receive structured intelligence back.

POST /v2/transactions/enrich

        Example Request
        json
      

{
  "transaction_id": "txn_8f2a9c",
  "description": "AMZN MKTP US*2K7F94H",
  "amount": -42.99,
  "currency": "USD",
  "date": "2026-05-14"
}

        Response
        json
      

{
  "transaction_id": "txn_8f2a9c",
  "merchant": {
    "name": "Amazon",
    "category": "Shopping",
    "logo_url": "https://cdn.sona.dev/logos/amazon.svg",
    "confidence": 0.994
  },
  "enrichment": {
    "is_recurring": false,
    "is_subscription": false,
    "channel": "online"
  }
}

Rate Limits

The API enforces rate limits based on your plan tier. All responses include rate limit headers.

Plan	Requests/min	Burst
Starter	60	100
Growth	600	1,000
Enterprise	6,000	10,000

Response Headers

Every response includes the following rate limit headers:

X-RateLimit-Limit — maximum requests per window
X-RateLimit-Remaining — requests remaining
X-RateLimit-Reset — Unix timestamp when window resets

Error Handling

The API uses conventional HTTP response codes. Codes in the 2xx range indicate success. Codes in the 4xx range indicate client errors. Codes in the 5xx range indicate server errors.

        Error Response
        json
      

{
  "error": {
    "code": "invalid_request",
    "message": "The 'amount' field is required.",
    "doc_url": "https://docs.sona.dev/errors#invalid_request"
  }
}