Skip to main content
The official ParseTx Node.js SDK gives you a clean, Promise-based interface to the transaction enrichment API. Whether you need instant results for a handful of records or want to fire off a 500-item background job, a single client class handles both flows. TypeScript types ship in the box, so you get full IntelliSense with zero extra configuration.

​
Installation

1
Install the npm package
2
npm install @parsetx/sdk
3
The package is published under the @parsetx scope rather than the bare name parsetx. The npm registry’s similarity-detection rules block parsetx as too close to the existing parse5 package, so the official home is @parsetx/sdk. TypeScript type definitions are bundled directly — no separate @types/ install is needed.
4
Import the client
5
import { ParseTxClient } from '@parsetx/sdk';

​
CDN / No-install Alternative

If you’re working in an environment where you can’t use npm — a browser project, a Cloudflare Worker, or a Deno script — you can import the standalone ES module directly from the jsDelivr CDN: 
import { ParseTxClient } from 'https://cdn.jsdelivr.net/gh/parsetx/API-Webservices-Nova@main/sdks/node/parsetx.js';
The CDN build is the same source file published to npm. It exports the identical ParseTxClient class, so all examples on this page apply without any changes.

​
Initialization

Pass your API key to the constructor. Every subsequent call from that client instance automatically sends the key in the X-API-Key header — you never need to include it yourself. 
import { ParseTxClient } from '@parsetx/sdk';

const client = new ParseTxClient('pt_live_yourkeyhere');
Keep your API key out of source control. Store it in an environment variable and read it with process.env.PARSETX_API_KEY rather than hardcoding the string in your codebase.

​
Synchronous Enrichment

Use client.enrich() when you need results immediately. It sends up to 10 transactions to POST /v1/enrich and resolves with the fully enriched payload. 
import { ParseTxClient } from '@parsetx/sdk';

const client = new ParseTxClient('pt_live_yourkeyhere');

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

for (const result of response.results) {
  if (result.status === 'complete') {
    console.log(`${result.merchant} (${result.category})`);
  }
}
// Amazon (Shopping)
// Uber Eats (Food & Drink)
// Netflix (Entertainment)
Each item in response.results maps 1-to-1 to your input array by position. Check result.status before reading enrichment fields — possible values are "complete", "rejected" (high-entropy or unrecognizable input), and "retry" (transient processing fault).

Max batch size

Up to 10 items per synchronous call. Passing more than 10 throws immediately on the client before any network request is made.

Response time

Cached merchants typically resolve in under 50 ms. Novel merchants route through the LLM pipeline and may take slightly longer.

​
Asynchronous Batch Enrichment

For batches larger than 10 items, use client.enrichAsync(). It submits up to 500 transactions to the background queue and returns a job_id string immediately — no waiting for results. 
import { ParseTxClient } from '@parsetx/sdk';

const client = new ParseTxClient('pt_live_yourkeyhere');

// Submit up to 500 transactions for background processing
const jobId = await client.enrichAsync(transactions);

console.log(`Job submitted: ${jobId}`);
// Job submitted: 8f2e32a6-c205-4c07-8e6c-7f5ff5d4116c
Each async batch is capped at 500 items. If you need to process more than 500 items, split your list into chunks of ≤ 500 and submit each as a separate job.

​
Polling for Async Results

Once you have a job_id, pass it to client.pollJob(). The method checks the job status in a loop and resolves only when the status transitions to "complete" or "failed". It uses built-in exponential backoff — starting at a 2-second interval, multiplying by 1.5 on each pass, and capping at 10-second intervals — so you don’t need to implement any waiting logic yourself. 
import { ParseTxClient } from '@parsetx/sdk';

const client = new ParseTxClient('pt_live_yourkeyhere');

// Submit up to 500 transactions for background processing
const jobId = await client.enrichAsync(transactions);

// Poll until complete (built-in exponential backoff)
const result = await client.pollJob(jobId);
console.log(`Enriched ${result.results.length} transactions`);

​
Polling options

pollJob accepts an optional second argument to tune the backoff behaviour:
OptionTypeDefaultDescription
intervalMsnumber2000Initial delay between poll attempts, in milliseconds.
maxWaitMsnumber120000Maximum total wait time before the call throws a timeout error (2 minutes).
// Custom polling — start faster, wait longer
const result = await client.pollJob(jobId, {
  intervalMs: 1000,
  maxWaitMs: 300000  // 5 minutes
});
If maxWaitMs elapses before the job finishes, pollJob throws an Error. Store the jobId before polling so you can retry later if needed.

​
Complete Async Workflow

1
Submit the batch
2
const jobId = await client.enrichAsync(transactions);
3
Poll for results
4
const result = await client.pollJob(jobId);
5
Process the enriched data
6
if (result.status === 'complete') {
  for (const item of result.results) {
    if (item.status === 'complete') {
      console.log(`${item.input} → ${item.merchant} [${item.category}]`);
    }
  }
}

​
Method Reference

new ParseTxClient(apiKey)

Creates a new client instance. apiKey (string, required) is your pt_live_... key. An optional second argument baseUrl overrides the default https://api.parsetx.com.

client.enrich(transactions[])

Synchronously enriches an array of up to 10 raw transaction strings. Returns Promise<EnrichResponse> containing a results array, a job_id of null, and a status string.

client.enrichAsync(transactions[])

Submits an array of up to 500 raw transaction strings for background processing. Returns Promise<string> — the job_id you use to retrieve results.

client.pollJob(jobId, options?)

Polls GET /v1/enrich/jobs/:id with exponential backoff until the job reaches "complete" or "failed". Returns Promise<EnrichResponse>.