ParseTx Batch Processing: Sync and Async Endpoints

ParseTx is built batch-first — every request accepts an array of transaction strings rather than a single item. Whether you need enriched results in milliseconds for a live user session or you’re churning through a full bank statement history overnight, there is a dedicated endpoint for the job. The right choice comes down to payload size and how quickly you need the results back.

Choosing a Mode

	Synchronous	Asynchronous
Endpoint	`POST /v1/enrich`	`POST /v1/enrich/async`
Max items	10	500
Response	Results in the response body	`202 Accepted` + `job_id`
Best for	Real-time UIs, webhooks, small batches	Bulk imports, nightly jobs, Plaid syncs

Synchronous
Asynchronous

The synchronous endpoint is the simplest way to enrich transactions. You POST up to 10 strings, and the API waits until every item is resolved before returning — no polling required.How it works:

Each input is checked against the pre-warmed canonical cache first.
Cache hit: Result is returned in under 50 ms at zero AI cost.
Cache miss: The item is forwarded to the AI inference engine. The endpoint waits up to 10 seconds for a response before returning.
The final response is a single JSON object containing all resolved results.

The synchronous endpoint is capped at 10 items. For larger batches, use the async endpoint.

Best for:

Real-time transaction enrichment as users connect their accounts
Small ad-hoc batches in webhook processors
Exploratory testing and development

curl -X POST https://api.parsetx.com/v1/enrich \
  -H "X-API-Key: pt_live_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{"transactions": ["NETFLIX.COM ON DEMAND", "UBER EATS"]}'

Example response:

{
  "results": [
    {
      "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": "UBER EATS",
      "status": "complete",
      "source": "cache",
      "merchant": "Uber Eats",
      "domain": "ubereats.com",
      "category": "Food & Drink",
      "mcc_code": "5812",
      "is_subscription": false,
      "confidence": 1
    }
  ],
  "job_id": null,
  "status": "complete"
}

The asynchronous endpoint accepts up to 500 transaction strings and processes them in the background. Your request returns immediately with a job_id, and you poll a separate endpoint until the job reaches complete or failed status.How it works:

You POST up to 500 transaction strings to /v1/enrich/async.
The API responds with 202 Accepted and a job_id — instantly, regardless of payload size.
The batch is queued and processed by a background worker.
You poll GET /v1/enrich/jobs/:id to check progress and retrieve results when ready.

Job status values:

Status	Meaning
`queued`	Job accepted, waiting for a worker to pick it up
`processing`	Worker is actively enriching the batch
`complete`	All items processed; results are available
`failed`	Job encountered a fatal error; contact support

Best for:

Bulk import of a user’s entire bank statement history
Nightly batch jobs over large transaction exports
Processing large Plaid or Open Banking data syncs

# Step 1 — Submit the job
curl -X POST https://api.parsetx.com/v1/enrich/async \
  -H "X-API-Key: pt_live_yourkeyhere" \
  -H "Content-Type: application/json" \
  -d '{"transactions": ["NETFLIX.COM ON DEMAND", "UBER EATS", "... up to 500 items"]}'

# Step 2 — Poll for results
curl https://api.parsetx.com/v1/enrich/jobs/84c8a82d-1234-5678-abcd-ef0123456789 \
  -H "X-API-Key: pt_live_yourkeyhere"

202 Accepted response (on submission):

{
  "results": [],
  "job_id": "84c8a82d-1234-5678-abcd-ef0123456789",
  "status": "queued"
}

The Node.js and Python SDKs include built-in exponential backoff polling so you don’t have to manage the loop yourself. Call client.pollJob(jobId) and await the resolved result directly.

Partial Batch Failures

Regardless of which mode you use, individual items within a batch can fail without failing the whole request. A batch with one or more failed items still returns HTTP 200, but the envelope status field will be "partial" instead of "complete". See the Error Handling guide for details on how to handle per-item rejected and retry statuses.

​Choosing a Mode

​Partial Batch Failures

Choosing a Mode

Partial Batch Failures