DOCS/numens/transaction-classification

Batch Business Transaction Tax Treatment

Authentication Required

Include your API key in the x-api-key header of every request.

The Batch Business Transaction Tax Treatment API enqueues up to 500 financial transactions for bulk AI classification and tax treatment. It supports both flat transaction lists and hierarchical multi-business batch submissions.

Flexible Batch Formats

1Flat Transaction Batch: Pass a top-level transactions array containing individual business transactions.
2Multi-Business Batch: Pass a top-level businesses array grouping transactions by client/business entity for multi-entity applications.

HTTP Request

POSThttps://api.taxstreem.com/v1/numen/transaction-tax-treatment/batch

Request Body Schema

Parameter	Type	Required	Description
taskId	string	Required	Unique batch task tracking identifier (e.g. `batch_task_123`).
transactions	array	Conditional	Flat array of business transaction items (Required if `businesses` is not provided). Max 500 items.
businesses	array	Conditional	Multi-business batch array (Required if `transactions` is not provided). Each item includes `businessId`, business metadata, and nested `transactions`.

Batch Status Endpoint

To check the processing status of a queued batch job, use the GET status endpoint:

GEThttps://api.taxstreem.com/v1/numen/transaction-tax-treatment/batch/{job_id}/status

Response Envelope

The API returns an immediate 202 Accepted acknowledgement. Heavy computation runs asynchronously in the background.

Field	Type	Description
data.jobId	string	Unique batch job tracking ID (e.g. `numen_job_987654321xyz`).
data.taskId	string	Your custom batch task tracking identifier.
data.status	string	Initial job status (`pending`).
data.totalBusinesses	number	Total distinct business entities in the batch.
data.totalTransactions	number	Total transactions enqueued across all entities.
data.creditsUsed	number	Total credits deducted for processing the batch.
data.creditsRemaining	number	Developer's remaining active credit balance.
data.statusUrl	string	Relative endpoint path to poll batch status.

Streaming Webhook Delivery Architecture

To avoid holding long client connections when submitting large batches (e.g. 300+ items), TaxStreem delivers results progressively in 50-item streaming chunks via Webhooks:

•Chunk Webhooks (treatment.batch_chunk): Fired as each chunk of 50 items completes. Contains chunk index, total chunks, hasMore flag, and processed results array.
•Completion Webhook (treatment.batch_completed): Fired when all chunks finish processing. Contains overall execution metrics, success counts, and items flagged for human review.

1. Batch Chunk Webhook (`treatment.batch_chunk`)

Field	Type	Description
chunkIndex	number	Current chunk sequence number (1-indexed).
totalChunks	number	Total chunk count calculated for the job (e.g. 6 for 300 items).
hasMore	boolean	`true` if subsequent chunks remain; `false` on final chunk.
results	array	Array of classified transactions including COA categories, WHT/VAT rates, and review flags.

2. Batch Completed Webhook (`treatment.batch_completed`)

Field	Type	Description
processedTransactions	number	Total number of items processed across all chunks.
successfulTransactions	number	Count of high-confidence transactions processed automatically.
needsReviewCount	number	Count of transactions flagged for review (e.g. 12 out of 300).
durationMs	number	Total execution time in milliseconds.

Example Request

curl -X POST https://api.taxstreem.com/v1/numen/transaction-tax-treatment/batch \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
   "taskId": "batch_task_123",
   "businesses": [
      {
         "businessId": "biz_kevs_bakery_001",
         "businessName": "Kev's Bakery Ltd",
         "tin": "12345678-0001",
         "state": "Lagos",
         "country": "Nigeria",
         "transactions": [
            {
               "transactionId": "trans_001",
               "transactionType": "purchase",
               "vendorName": "Flour Mills Nig Plc",
               "description": "50 bags of baking flour",
               "amount": 850000,
               "currency": "NGN",
               "date": "2026-03-08"
            }
         ]
      }
   ]
}'

Example Response

202 Accepted

{
  "success":  true,
  "data":  {
    "jobId":  "numen_job_987654321xyz",
    "taskId":  "batch_task_123",
    "status":  "pending",
    "totalBusinesses":  1,
    "totalTransactions":  1,
    "creditsUsed":  1,
    "creditsRemaining":  498,
    "message":  "Batch transaction tax treatment queued successfully",
    "statusUrl":  "/v1/numen/transaction-tax-treatment/batch/numen_job_987654321xyz/status"
  },
  "meta":  {
    "requestId":  "req_87654321",
    "timestamp":  "2026-08-30T10:00:00.000Z"
  }
}