GET /v1/enrich/jobs/:id — Poll Async Job Results

After submitting a batch via POST /v1/enrich/async, use this endpoint to check the progress of your job and retrieve enriched results once processing is complete. You authenticate with the same API key used to create the job — the API will return 401 if the keys don’t match. Poll this endpoint until the status field is either complete or failed; at that point, no further polling is needed.

Path Parameters

string

required

The UUID of the async enrichment job, as returned in the job_id field of the POST /v1/enrich/async response (e.g. "84c8a82d-1234-5678-abcd-ef0123456789").

Job Status Values

Status	Meaning
`queued`	The job has been accepted but has not yet started processing.
`processing`	Enrichment is actively running. Results are not yet available.
`complete`	All items have been processed. The `results` array is fully populated.
`failed`	A fatal error occurred. Contact support with your `job_id` for investigation.

Response Schema

The response shape is consistent across all job states. The results array is empty while the job is queued or processing, and fully populated once it reaches complete.

string

The job UUID, matching the id path parameter you requested.

status

string

The current job status: queued, processing, complete, or failed.

item_count

number

The total number of transaction strings submitted in the original batch. Present once the job has been picked up for processing.

results

EnrichResultItem[]

An empty array [] while the job is queued or processing. When status is complete, this array contains one result object per submitted transaction, in the same order as originally submitted.

Show EnrichResultItem fields

input

string

The original raw transaction string you submitted.

status

string

Resolution status for this item. One of:

complete — enrichment succeeded
rejected — input was high-entropy garbage or reduced to nothing after PII sanitization
retry — an uncaught mapper error occurred; you should retry this item

source

string

How the result was resolved. Only present when status is complete. One of:

cache — served from the ParseTx KV cache
llm — resolved via live AI inference

merchant

string

The canonical, human-readable merchant name (e.g. "Netflix"). Only present when status is complete.

domain

string | null

The verified web domain of the merchant (e.g. "netflix.com"). null if no domain could be confirmed. Only present when status is complete.

category

string

The ParseTx taxonomy category assigned to this merchant (e.g. "Entertainment", "Shopping"). Only present when status is complete.

mcc_code

string | null

The 4-digit ISO Merchant Category Code (e.g. "4899"). null if no MCC mapping could be determined. Only present when status is complete.

is_subscription

boolean

true if the merchant operates on a recurring subscription model. Only present when status is complete.

confidence

number

Enrichment confidence score from 0.0 to 1.0. Cache hits return 1.0; rejected items return 0.0; LLM results reflect the model’s own confidence.

reason

string

A human-readable explanation of why the item was rejected or failed. Only present when status is rejected or retry.

created_at

string

ISO 8601 timestamp of when the job was submitted.

updated_at

string

ISO 8601 timestamp of the most recent status update.

curl https://api.parsetx.com/v1/enrich/jobs/84c8a82d-1234-5678-abcd-ef0123456789 \
  -H "X-API-Key: pt_live_yourkeyhere"

{
  "id": "84c8a82d-1234-5678-abcd-ef0123456789",
  "status": "processing",
  "item_count": 3,
  "results": []
}

Polling Best Practices

Use exponential backoff when polling this endpoint — for example, check at 1 s, then 2 s, 4 s, 8 s, and so on, capping at a reasonable maximum (e.g. 30 s). This avoids hammering the API unnecessarily while still retrieving results promptly. The ParseTx SDKs handle this automatically via pollJob() (TypeScript) / poll_job() (Python): both methods accept configurable maxAttempts and initialDelay parameters and resolve a promise/coroutine when the job reaches a terminal state.

Stop polling as soon as status is complete or failed — the job state will not change after reaching either terminal state.

Error Responses

HTTP Status	Condition	Response Body
`401 Unauthorized`	`X-API-Key` header is missing or empty	`{"error": "Missing API key. Provide your key via the X-API-Key header."}`
`401 Unauthorized`	Key does not match the key used to create the job, or key is revoked	`{"error": "Invalid or revoked API key."}`
`404 Not Found`	No job exists with the provided UUID	`{"error": "Job not found."}`
`500 Internal Server Error`	Unexpected server-side failure	`{"error": "Internal Server Error"}`

​Path Parameters

​Job Status Values

​Response Schema

​Polling Best Practices

​Error Responses

Path Parameters

Job Status Values

Response Schema

Polling Best Practices

Error Responses