Batch

Authentication Required

This endpoint requires a valid API key. Include your API key in the x-api-key header of every request. You can generate a test key in your developer dashboard.

The Batch Transaction API submits multiple transactions to Numens in a single request. Each transaction is classified independently — Numens returns a taxType, taxRate, and taxAmount for every entry in the array.

Ideal for platforms that need to process a day's worth of transactions at close of business, or any system that accumulates transactions before sending them to the intelligence engine in bulk.

Integration Flow

1Assemble Array: Build the transactions array. Each entry must include a unique transactionId for idempotency.
2Submit Batch: POST up to 100 transactions in a single request.
3Receive Results: A transaction.batch.classified webhook fires when the full batch completes, carrying a classification array keyed by transactionId.

HTTP Request

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

Request Body

The following parameters are required for this action.

Parameter	Type	Required	Description
batchId	string	Required	A universally unique identifier (UUID) assigned by you. Used for idempotency to ensure this exact batch is not processed twice if the connection drops. Max 64 characters.
payload	array[object]	Required	An array of transaction objects containing the target data. Cannot be empty. Maximum 500 items per batch. Schema mirrors the single payload attributes.

Response Documentation

A successful invocation of this endpoint returns a 202 Accepted or 200 OK. Since filing operations are processed asynchronously alongside tax gateways, the immediate response acknowledges successful receipt and enqueueing of the schedule payload.

Field Name	Type	Description
status	string	The high-level outcome of the request context. Value is typically `accepted` indicating payload validation passed.
message	string	A human-readable confirmation note (e.g. "schedule accepted successfully").
data.id	string	The tracking UUID for this schedule. This precise ID correlates to the `filingId` in downstream webhook events.
data.created_at	string (date-time)	Timestamp marking the instant the schedule safely enqueued, in ISO 8601 format.

Error Handling

The API applies standard HTTP status codes indicating success or failure. In case of an anomaly, the response body contains an errors array detailing specific field-level validation issues to facilitate rapid integration debugging.

HTTP Status	Error Key	Cause & Resolution
400	Bad Request	Cause: Missing required fields, invalid attributes (e.g. malformed TIN), or structural JSON anomalies. Resolution: Traverse the `errors` array in the response to target the invalid field constraints, format properly, and re-submit.
401	Unauthorized	Cause: The API key credential is missing, malformed, or revoked. Resolution: Ensure your `x-api-key` is populated in the request header and that you are matching the correct environment bounds (live vs test).
403	Forbidden	Cause: Properly authenticated, but the key context is lacking specific scope permissions or the merchant account represents restricted access. Resolution: Review integration scopes within the dashboard to assure capability rights correspond to NUMENS operations.
429	Too Many Requests	Cause: Network volume exceeds the rate envelope associated with your tier configuration. Resolution: Gracefully throttle via exponential backoff semantics checking the `Retry-After` header variable, or upgrade capacity constraints.

Example Request

curl -X POST https://api.taxstreem.com/v1/numens/batch \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
    "batchId": "numens-batch-001",
    "transactions": [
      {
        "transactionId": "TXN-20240320-001",
        "counterparty": "Acme Consulting Ltd",
        "amount": 250000,
        "currency": "NGN",
        "description": "Professional consultancy services",
        "transactionDate": "2024-03-20"
      }
    ]
  }'

Example Response

202 Accepted

{
  "status":  "accepted",
  "message":  "schedule accepted successfully",
  "data":  {
    "id":  "xaee2ddf-effvkfes",
    "created_at":  "2026-02-20T10:00:00Z"
  }
}