Skip to main content
The /v1/enrich endpoint cleans, normalizes, and enriches a small batch of raw transaction description strings in a single blocking request. You send up to 10 strings — exactly as they appear on a bank statement or card feed — and ParseTx returns structured merchant data for each one. Results are served from cache when available; on a cache miss, the API runs live AI inference and waits for the result before responding, which can take up to 10 seconds. Results with high confidence are automatically written back to cache for future calls.

​
Request Parameters

​
transactions
string[]
required
An array of raw transaction description strings to enrich. Each string should be the unmodified text from a bank statement or card feed (e.g. "AMZN Mktp US*1A2B3C4D5 Amzn.com/bill WA"). Maximum 10 items per request.
Input strings are sanitized for PII (card numbers, account IDs) before processing. High-entropy strings that cannot be resolved to a merchant — such as pure number sequences or random garbage — are returned with "status": "rejected" rather than triggering an error.

​
Response Schema

A successful request returns 200 OK with the following top-level fields:
​
results
EnrichResultItem[]
An array of enriched result objects, one per input string, returned in the same order as submitted.
​
job_id
null
Always null for synchronous requests. Present for structural consistency with the async response shape.
​
status
string
Overall batch status. "complete" if all items resolved cleanly; "partial" if one or more items returned status: "retry".
curl -X POST https://api.parsetx.com/v1/enrich \
  -H "X-API-Key: pt_live_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      "AMZN Mktp US*1A2B3C4D5 Amzn.com/bill WA",
      "NETFLIX.COM ON DEMAND",
      "123456789 garbage"
    ]
  }'

{
  "results": [
    {
      "input": "AMZN Mktp US*1A2B3C4D5 Amzn.com/bill WA",
      "status": "complete",
      "source": "cache",
      "merchant": "Amazon",
      "domain": "amazon.com",
      "category": "Shopping",
      "mcc_code": "5411",
      "is_subscription": false,
      "confidence": 1.0
    },
    {
      "input": "NETFLIX.COM ON DEMAND",
      "status": "complete",
      "source": "cache",
      "merchant": "Netflix",
      "domain": "netflix.com",
      "category": "Entertainment",
      "mcc_code": "4899",
      "is_subscription": true,
      "confidence": 1
    },
    {
      "input": "123456789 garbage",
      "status": "rejected",
      "reason": "Input rejected: too short, high-entropy garbage, or all PII after sanitization",
      "confidence": 0
    }
  ],
  "job_id": null,
  "status": "complete"
}

​
Sync vs. Async: When to Use Which

Use POST /v1/enrich (this endpoint) when:
  • You need results immediately within the same request lifecycle — for example, enriching a transaction at the point of authorization or displaying merchant details inline in your UI.
  • Your batch is 10 items or fewer.
  • Your infrastructure can tolerate up to 10 seconds of latency on cache misses (live AI inference calls).
Use POST /v1/enrich/async instead when:
  • You’re processing a bank statement import, a nightly reconciliation job, or any batch larger than 10 items (up to 500).
  • You want to decouple submission from result retrieval to avoid HTTP timeouts in your pipeline.
  • You’re running background enrichment where immediate results aren’t required.

​
Error Responses

HTTP StatusConditionResponse Body
400 Bad RequestMalformed JSON, missing transactions field, or array exceeds 10 items{"error": "Bad Request — ..."}
401 UnauthorizedX-API-Key header is missing or empty{"error": "Missing API key. Provide your key via the X-API-Key header."}
401 UnauthorizedKey does not match an active key in the database{"error": "Invalid or revoked API key."}
429 Too Many RequestsMonthly transaction quota exceeded{"error": "Monthly quota exceeded.", "usage": 49990, "limit": 50000, "plan": "pay_as_you_go"}
429 Too Many RequestsDaily AI token budget exceeded{"error": "Daily token budget exceeded. Your quota resets at midnight UTC.", "token_usage": 999900, "token_limit": 1000000, "plan": "pay_as_you_go"}
500 Internal Server ErrorUnexpected server-side failure{"error": "Internal Server Error"}
A 429 due to daily token budget only applies when the request triggers live LLM inference (cache misses). Cache hits do not consume token budget. If you’re hitting this limit frequently, consider pre-warming the cache or upgrading to an Enterprise plan.