Quickstart: Make Your First ParseTx Enrichment Call

Getting from zero to enriched transaction data takes less than five minutes. This guide walks you through getting an API key, making your first request in the language of your choice, and understanding what comes back. By the end you’ll have a working integration you can build on.

Get your API key

ParseTx uses API keys to authenticate every request. To get yours, visit the ParseTx pricing page and click Get API Key.You’ll provide your email address and a credit card during sign-up. Your card is required to prevent API abuse — but you are only ever billed for what you use. There are no monthly minimums, no setup fees, and no charges just for having an account.

Your API key is shown only once immediately after creation. Copy it to a secure location — ParseTx never stores the raw key, so it cannot be recovered if lost. If you misplace it, generate a new one from the dashboard.

Once issued, your key will look like this:

pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep this key out of your source code and version control. See the Authentication guide for best practices.

Make your first request

Call POST /v1/enrich with a JSON body containing a transactions array. The synchronous endpoint accepts up to 10 transaction strings per request.Replace pt_live_yourkeyhere with your actual API key:

curl -X POST https://api.parsetx.com/v1/enrich \
  -H "X-API-Key: pt_live_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{"transactions": ["SQ *BLUE BOTTLE COFFEE SAN FRANCISCO CA"]}'

Store your API key in an environment variable (e.g. PARSETX_API_KEY) rather than hardcoding it. The SDKs automatically read from this variable if no key is passed to the constructor.

Understand the response

A successful request returns a 200 OK with a JSON body like this:

{
  "results": [
    {
      "input": "SQ *BLUE BOTTLE COFFEE SAN FRANCISCO CA",
      "status": "complete",
      "source": "cache",
      "merchant": "Blue Bottle Coffee",
      "domain": "bluebottlecoffee.com",
      "category": "Food & Drink",
      "mcc_code": "5812",
      "is_subscription": false,
      "confidence": 0.95
    }
  ],
  "job_id": null,
  "status": "complete"
}

Here’s what each field means:

Field	What it tells you
`input`	The original string you sent, echoed back for easy matching
`status`	`"complete"` means fully enriched; `"rejected"` means the input was unparseable garbage; `"retry"` means a transient error — resend it
`source`	`"cache"` means the result came from ParseTx’s pre-warmed merchant database (sub-50ms); `"llm"` means the AI resolved it fresh
`merchant`	The clean, canonical merchant name — consistent every time for the same merchant
`domain`	The merchant’s verified web domain — pass this to a favicon service to render a logo
`category`	One of 15 standardized categories you can use for grouping or filtering
`mcc_code`	The 4-digit ISO 18245 Merchant Category Code — useful for accounting, compliance, and card reward logic
`is_subscription`	`true` if this merchant bills on a recurring schedule (streaming services, SaaS tools, etc.)
`confidence`	A score from `0.0` to `1.0` indicating how certain ParseTx is. Cache hits always return `1.0`. You can filter or flag results below your own threshold.

The job_id field is null for synchronous requests. It only contains a UUID when you use the async endpoint (POST /v1/enrich/async) for batches of up to 500 transactions.

Next steps

You’re up and running. Here’s where to go depending on what you’re building:

Batch Processing

Processing a full bank statement or expense report? Learn how to submit up to 500 transactions in a single async job and poll for results.

Response Schema

Deep-dive into every field ParseTx returns, including the full category taxonomy, MCC code mapping, and status values.

Authentication

Best practices for storing your API key, rotating credentials, and handling 401 errors gracefully.

Enrich API Reference

Complete reference for request parameters, headers, error codes, and rate limits for the /v1/enrich endpoint.