Skip to main content
The official ParseTx Python SDK wraps the enrichment API in a straightforward client class that handles authentication, request formatting, and async polling for you. It uses the battle-tested requests library under the hood, requires no framework-specific setup, and works in any Python 3.7+ environment — from a Django backend to a standalone data-processing script.

​
Installation

Install the package from PyPI with pip: 
pip install parsetx
The package is published as parsetx (no scoping needed on PyPI). It depends only on the requests library, which is installed automatically.

​
Initialization

Import ParseTxClient and instantiate it with your API key. The client creates a persistent requests.Session and attaches your key to every outgoing request via the X-API-Key header automatically. 
from parsetx import ParseTxClient

client = ParseTxClient(api_key='pt_live_yourkeyhere')
Avoid hardcoding your API key in source files. Store it as an environment variable and read it at runtime — your key stays out of version control and you can rotate it without touching your code:
import os
from parsetx import ParseTxClient

client = ParseTxClient(api_key=os.environ['PARSETX_API_KEY'])

​
Synchronous Enrichment

Use client.enrich() when you need results right away. It sends up to 10 transaction strings to POST /v1/enrich and returns the fully enriched response as a Python dictionary. 
from parsetx import ParseTxClient

client = ParseTxClient(api_key='pt_live_yourkeyhere')

response = client.enrich([
    'AMZN Mktp US*1A2B3C4D5',
    'UBER EATS',
    'NETFLIX.COM ON DEMAND'
])

for result in response['results']:
    if result['status'] == 'complete':
        print(f"{result['merchant']} ({result['category']})")
# Amazon (Shopping)
# Uber Eats (Food & Drink)
# Netflix (Entertainment)
Results are returned in the same order as your input list. Each item’s status field tells you how to handle it:
StatusMeaning
completeEnrichment succeeded — all merchant fields are present.
rejectedInput was high-entropy, too short, or all PII after sanitization.
retryA transient processing fault occurred for this item only.

Max batch size

Up to 10 items per synchronous call. Passing more raises a ValueError before any network request is sent.

Response time

Cached merchants typically resolve in under 50 ms. New merchants route through the LLM pipeline and may take a moment longer.

​
Asynchronous Batch Enrichment

For batches larger than 10 items, use client.enrich_async(). It submits up to 500 transaction strings to the background processing queue and returns a job_id string immediately — you don’t wait for results at submission time. 
from parsetx import ParseTxClient

client = ParseTxClient(api_key='pt_live_yourkeyhere')

# Submit up to 500 transactions
job_id = client.enrich_async(transactions)

print(f"Job submitted: {job_id}")
# Job submitted: 8f2e32a6-c205-4c07-8e6c-7f5ff5d4116c
Each async batch is capped at 500 items. For datasets larger than 500 items, split your list into chunks of ≤ 500 and call enrich_async() once per chunk.

​
Polling for Async Results

Pass your job_id to client.poll_job() to retrieve the finished results. The method polls GET /v1/enrich/jobs/:id in a loop and returns only when the job status reaches "complete" or "failed". It applies exponential backoff automatically — starting at a 2-second interval, multiplying by 1.5 on each pass, and capping at 10-second intervals. 
from parsetx import ParseTxClient

client = ParseTxClient(api_key='pt_live_yourkeyhere')

# Submit up to 500 transactions
job_id = client.enrich_async(transactions)

# Poll until complete (built-in exponential backoff)
result = client.poll_job(job_id)
print(f"Enriched {len(result['results'])} transactions")

​
Polling options

ParameterTypeDefaultDescription
interval_msint2000Initial delay between poll attempts, in milliseconds.
max_wait_msint120000Maximum total wait time before a ParseTxError is raised (2 minutes).
# Custom polling — start faster, allow longer total wait
result = client.poll_job(job_id, interval_ms=1000, max_wait_ms=300000)
If max_wait_ms elapses before the job finishes, poll_job raises a ParseTxError. Save your job_id beforehand so you can call poll_job again later without re-submitting the batch.

​
Complete Async Workflow

1
Submit the batch
2
job_id = client.enrich_async(transactions)
3
Poll for results
4
result = client.poll_job(job_id)
5
Process the enriched data
6
if result['status'] == 'complete':
    for item in result['results']:
        if item['status'] == 'complete':
            print(f"{item['input']} → {item['merchant']} [{item['category']}]")

​
Environment Variable Pattern

Loading credentials from environment variables is the standard practice for any application you deploy or share. Set PARSETX_API_KEY once in your environment and reference it everywhere: 
import os
from parsetx import ParseTxClient

client = ParseTxClient(api_key=os.environ['PARSETX_API_KEY'])
For local development you can use a .env file with a library like python-dotenv: 
# .env  (add this file to .gitignore)
PARSETX_API_KEY=pt_live_yourkeyhere

from dotenv import load_dotenv
import os
from parsetx import ParseTxClient

load_dotenv()
client = ParseTxClient(api_key=os.environ['PARSETX_API_KEY'])

​
Method Reference

ParseTxClient(api_key, base_url?)

Creates a new client instance. api_key (str, required) is your pt_live_... key. The optional base_url argument overrides the default https://api.parsetx.com.

client.enrich(transactions)

Synchronously enriches a list of up to 10 raw transaction strings. Returns a dict with a results list, a job_id of None, and a status string.

client.enrich_async(transactions)

Submits a list of up to 500 raw transaction strings for background processing. Returns a str — the job_id you use to retrieve results.

client.poll_job(job_id, interval_ms?, max_wait_ms?)

Polls GET /v1/enrich/jobs/:id with exponential backoff until the job reaches "complete" or "failed". Returns a dict with the same shape as a sync enrich() response.