DOCS/numens/transaction-classification

Batch Transaction Classification

Authentication Required

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

The Batch Transaction Classification API classifies multiple financial transactions in a single request. Use this endpoint for bulk imports, end-of-period reconciliation, or ERP sync jobs where many transactions need tax treatment simultaneously.

Integration Flow

1Assemble Transactions: Collect all transactions into the transactions array.
2Receive Classifications: Each transaction in the response array carries its individual classification and confidence score.
3Apply Results: Route classified transactions into VAT/WHT filing or flag low-confidence items for manual review.

HTTP Request

POSThttps://api.taxstreem.com/v1/numens/classify/batch

Request Body

Parameter	Type	Required	Description
transactions	array	Required	Array of transaction objects. Each object follows the single classification schema (transactionId, counterparty, amount, currency, description, transactionDate).

transactions[ ] — Item Schema

Field	Type	Required	Description
transactionId	string	Required	Unique ID for this transaction (idempotency key).
counterparty	string	Required	Full legal name of the other party.
amount	number	Required	Amount in smallest currency unit.
currency	string	Required	ISO 4217 currency code (e.g. NGN).
description	string	Required	Payment narration. Richer text improves accuracy.
transactionDate	string	Required	ISO 8601 date of the transaction.

Response

Returns 200 OK with an array of classification results, one per submitted transaction.

Example Request

curl -X POST https://api.taxstreem.com/v1/numens/classify/batch \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
   "transactions": [
      {
         "transactionId": "TXN-001",
         "counterparty": "Acme Consulting",
         "amount": 250000,
         "currency": "NGN",
         "description": "Consultancy services",
         "transactionDate": "2024-03-20"
      },
      {
         "transactionId": "TXN-002",
         "counterparty": "Lagos Properties Ltd",
         "amount": 500000,
         "currency": "NGN",
         "description": "Office rent March 2024",
         "transactionDate": "2024-03-01"
      }
   ]
}'

Example Response

200 OK

{
  "results":  [
    {
      "transactionId":  "TXN-001",
      "classification":  "WHT_CONSULTING",
      "confidence":  0.94,
      "recommendation":  "Deduct 5% WHT"
    },
    {
      "transactionId":  "TXN-002",
      "classification":  "WHT_RENT",
      "confidence":  0.98,
      "recommendation":  "Deduct 10% WHT"
    }
  ]
}