DOCS/numens/transaction-classification

Single Business Transaction Tax Treatment

Authentication Required

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

The Single Business Transaction Tax Treatment API submits a single financial transaction to Numens for AI-driven tax treatment and classification. It analyzes the transaction type, TIN, vendor/counterparty, description, state, and amount to determine applicable VAT, WHT, and income tax treatments.

Integration Flow

1Submit Transaction: Send the single business transaction with tenant, client, TIN, amount, currency, and narration details.
2Receive Job ID: Numens validates subscription credits and enqueues the job, returning an asynchronous 202 Accepted response containing a jobId and statusUrl.
3Track Progress: Poll the job status URL or receive webhooks to retrieve classified tax treatment results.

HTTP Request

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

Request Body

Parameter	Type	Required	Description
businessId	string	Required	Unique business identifier (e.g. `biz_kevs_bakery_001`).
businessName	string	Optional	Legal or trade name of the business entity (e.g. `Kev's Bakery Ltd`).
tenantId	string	Optional	Tenant identifier. Auto-derived from developer authentication token if omitted.
clientId	string	Optional	Legacy client identifier (optional if `businessId` is provided).
transactionId	string	Required	Your internal unique transaction identifier (e.g. `trans_abc123`).
transactionType	string	Required	Category of transaction (e.g. `purchase`, `sale`, `EXPENSE`).
tin	string	Required	Tax Identification Number (TIN) for the business entity.
vendorName	string \| null	Required	Name of the vendor/counterparty. Set to `null` for anonymous or retail B2C transactions.
description	string	Required	Detailed narration or memo describing the transaction goods/services.
amount	number	Required	Total numerical amount of the transaction (e.g. `1500.50`).
currency	string	Required	ISO 4217 currency code (e.g. `NGN`).
date	string	Required	Transaction date in ISO format (e.g. `2026-03-08`).
state	string	Required	State where transaction occurred (e.g. `Lagos`).
country	string	Required	Operating country (e.g. `Nigeria`).
taskId	string	Optional	Optional task tracking ID (auto-generated if omitted).

Response

Returns 202 Accepted with an asynchronous job envelope and credit status.

Field	Type	Description
success	boolean	Indicates whether the job was successfully enqueued.
data.jobId	string	Unique Numen job identifier for progress tracking.
data.taskId	string	Task batch tracking identifier.
data.status	string	Current status of the queued job (`pending`).
data.totalTransactions	number	Total transactions enqueued (1 for single submission).
data.creditsUsed	number	Number of subscription plan credits deducted.
data.creditsRemaining	number	Developer's remaining active credit balance.
data.statusUrl	string	API endpoint path to query the progress and results of the job.

Example Request

curl -X POST https://api.taxstreem.com/v1/numen/transaction-tax-treatment/single \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
   "businessId": "biz_kevs_bakery_001",
   "businessName": "Kev's Bakery Ltd",
   "transactionId": "trans_abc123",
   "transactionType": "purchase",
   "tin": "12345678-0001",
   "vendorName": "Acme Corp",
   "description": "Office supplies and stationery",
   "amount": 1500.5,
   "currency": "NGN",
   "date": "2026-03-08",
   "state": "Lagos",
   "country": "Nigeria"
}'

Example Response

202 Accepted

{
  "success":  true,
  "data":  {
    "jobId":  "numen_job_a1b2c3d4e5f6",
    "taskId":  "numen_task_78901234",
    "status":  "pending",
    "totalBusinesses":  1,
    "totalTransactions":  1,
    "creditsUsed":  1,
    "creditsRemaining":  499,
    "message":  "Single transaction tax treatment queued successfully",
    "statusUrl":  "/v1/numen/transaction-tax-treatment/batch/numen_job_a1b2c3d4e5f6/status"
  },
  "meta":  {
    "requestId":  "req_12345678",
    "timestamp":  "2026-08-30T10:00:00.000Z"
  }
}