/v1/enrich endpoint or an async job — follows the same schema. Understanding each field helps you build reliable integrations: you’ll know exactly when to display a merchant logo, when to retry a failed item, and when to discard a garbage input entirely.
Example: Successful Enrichment
EnrichResultItem Fields
The original transaction string exactly as you submitted it — before any normalization or sanitization. This field is always present regardless of status, so you can map results back to their position in your request array.
The resolution status of this item. Always present. One of three values:
Present only when
status is "complete". Indicates where the enrichment result came from:cache— Returned from the global edge cache. Sub-50ms latency. Confidence is always1.llm— Retrieved via AI inference on a cache miss. The result is now cached for 30 days.
The canonical, normalized merchant name. Present when
status is "complete".ParseTx always returns a consistent capitalization and spelling regardless of how the raw input was formatted — AMZN Mktp US*1A2B3C4D5, amzn.com, and Amazon Marketplace all resolve to "Amazon". This consistency is what makes the field reliable for bookkeeping deduplication and display labels.The verified primary domain of the merchant. Present when
status is "complete". Null when the merchant has no known web presence (e.g. individual sellers, local cash businesses).Use this field to render merchant logos client-side via a favicon service — see the tip below.A strictly typed category string from ParseTx’s 15-category taxonomy. Present when
status is "complete". Never free-form — always one of the values documented in the Categories reference.Use this field for transaction filtering, budget bucketing, and spend analytics in your application.A 4-digit Merchant Category Code conforming to ISO 18245. Present when
status is "complete". Null when no MCC can be determined.MCC codes are used by payment networks to classify merchants at a finer grain than the 15-category taxonomy. They are particularly useful for accounting integrations, compliance tooling, and expense policy engines that need to distinguish, for example, 5812 (Eating Places & Restaurants) from 5814 (Fast Food Restaurants).true if this merchant is known to operate on a recurring subscription model. Present when status is "complete".This field is determined based on the canonical merchant’s billing pattern, not the specific transaction string. Netflix, Spotify, and GitHub will return true. A one-time Amazon purchase will return false.Use this field to power subscription-tracking features, recurring charge alerts, or “subscriptions you might have forgotten about” views in personal finance apps.A decimal score between
0.0 and 1.0 representing how confident ParseTx is in the enrichment result.1.0— Cache hit (deterministic; verified result).0.80–0.99— AI enrichment with high confidence. Result is cached.< 0.80— AI enrichment with lower confidence. Result is returned but not cached; subsequent requests will re-run enrichment.0.0— Item was rejected. No enrichment was performed.
confidence >= 0.9 and flag lower-confidence results for manual review.Batch Response Envelope
The top-level response object that wraps the array ofEnrichResultItem results.
An ordered array of enriched items. The order matches the order of the
transactions array in your request — index 0 in results corresponds to index 0 in your input. This is true even for async jobs.nullfor synchronous requests (POST /v1/enrich).- A UUID v4 string for async jobs (
POST /v1/enrich/async). Use this value to pollGET /v1/enrich/jobs/{job_id}for the completed results.
The overall outcome of the batch:
complete— Every item inresultshasstatus: "complete"orstatus: "rejected". No retries are needed.partial— At least one item returnedstatus: "retry". The rest of the batch was processed normally. You should extract the retry items and resubmit them.
Handling the Three Status Values
complete
Enrichment succeeded.Read
merchant, domain, category, mcc_code, is_subscription, and confidence from the item. Store or display as needed.rejected
Garbage input.The string was all digits, high-entropy noise, or collapsed to empty after PII stripping. Do not retry. Log it, skip it, or surface a fallback label in your UI.
retry
Transient failure.A transient upstream error occurred for this item only. Safe to resubmit — collect all retry items from the batch and send them in a new request.