Transaction Classification
Authentication Required
Include your API key in the x-api-key header of every request.
The Transaction Classification API uses Numens to determine the tax nature of a single financial transaction. It analyzes the counterparty, description, and amount to classify the transaction for VAT, WHT, and income tax treatment — eliminating manual categorisation in your accounting workflows.
Integration Flow
- 1Submit Transaction: Send the transaction metadata including counterparty, amount, currency, and a description.
- 2Receive Classification: Numens returns a synchronous tax classification with recommended treatment.
- 3Apply Result: Use the classification to drive downstream VAT/WHT filing or accounting entries.
HTTP Request
POSThttps://api.taxstreem.com/v1/numens/classify
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| transactionId | string | Required | Your internal unique identifier for this transaction. Used as an idempotency key. |
| counterparty | string | Required | Full legal name of the vendor, customer, or other party involved in the transaction. |
| amount | number | Required | Transaction amount in the smallest currency unit (e.g. kobo for NGN). |
| currency | string | Required | ISO 4217 currency code (e.g. NGN, USD). |
| description | string | Required | Narration or memo from your payment or accounting system. Richer descriptions improve classification accuracy. |
| transactionDate | string | Required | ISO 8601 date the transaction occurred (e.g. 2024-03-20). |
Response
Returns 200 OK with a synchronous classification result.
| Field | Type | Description |
|---|---|---|
| transactionId | string | Echo of the submitted transaction ID. |
| classification | string | Tax nature of the transaction (e.g. VATABLE, WHT_CONSULTING, EXEMPT). |
| confidence | number | Confidence score between 0 and 1. Scores below 0.7 should trigger manual review. |
| recommendation | string | Plain-language action recommendation for your finance team. |
Example Request
curl -X POST https://api.taxstreem.com/v1/numens/classify \ -H "x-api-key: txsm_test_SK489c..." \ -H "Content-Type: application/json" \ -d '{ "transactionId": "TXN-20240320-001", "counterparty": "Acme Consulting Ltd", "amount": 250000, "currency": "NGN", "description": "Professional consultancy services", "transactionDate": "2024-03-20" }'
Example Response
200 OK
{
"transactionId": "TXN-20240320-001",
"classification": "WHT_CONSULTING",
"confidence": 0.94,
"recommendation": "Deduct 5% WHT and remit via Flux WHT Filing API"
}