Validate Tax ID
Authentication Required
Include your API key in the x-api-key header and a unique Idempotency-Key header on every request.
The Validate Tax ID API confirms that a Tax ID belongs to a business on the Corporate Affairs Commission (CAC) register and returns that business, including its RC/BN number, approved name, classification and status. Use it to check the Tax ID a vendor gave you before you deduct and file WHT against it.
The answer is synchronous: 200 with data.valid: true when the Tax ID is on the register, 404 with data.valid: false when it is not. companies is always a list, because one identifier can belong to more than one entity (for example a company and a business name registered under the same RC number).
HTTP Request
Path Parameter
| Parameter | Type | Required | Description |
|---|---|---|---|
| taxId | string | Required | NRS Tax ID, 8–20 digits. Spaces and dashes are ignored, so 2522-5077-63846 is the same as 2522507763846. A malformed value is refused with 400 and is not billed. |
Headers
| Header | Required | Description |
|---|---|---|
| x-api-key | Required | A Flux production key (txsm_live_) or any sandbox key (txsm_test_). |
| Idempotency-Key | Required | A unique value per lookup (up to 200 visible ASCII characters). Repeating it within 24 hours returns the first answer with replayed: true and is not billed again. |
Response
| Field | Type | Description |
|---|---|---|
| data.valid | boolean | True when the identifier is on the CAC register. |
| data.query | object | What was looked up: type (rc or taxid) and the normalised value. |
| data.companies[].name | string | Approved name on the register. |
| data.companies[].rcNumber | string | RC/BN number as CAC prints it. |
| data.companies[].taxId | string | null | NRS Tax ID; null when none has been issued. |
| data.companies[].classification | string | COMPANY, BUSINESS_NAME, IT (incorporated trustees), LP or LLP. |
| data.companies[].status | string | Register status, e.g. ACTIVE, INACTIVE, STRUCK OFF, IN LIQUIDATION. |
| data.companies[].natureOfBusiness | string | Declared line of business, when CAC has one. |
| data.companies[].registeredAt | string | null | Registration date (ISO 8601). |
| data.companies[].dataAsOf | string | When this record was last read from the register. |
| data.creditsUsed | number | Credits charged for this lookup. |
| data.creditsRemaining | number | Balance after the charge. |
Billing
Each completed lookup is billed once at the Flux validation price on your rate card, whether or not the identifier is found — "not on the register" is an answer too. Malformed identifiers (400), failures (503) and replays of an Idempotency-Key are not billed.
Sandbox
Sandbox keys are free and never reach the register. 1234567890123 answers 200 with a test company; any other well-formed value answers 404.
Errors
| HTTP Status | Error Key | Cause & Resolution |
|---|---|---|
| 400 | Bad Request | Malformed Tax ID or missing Idempotency-Key. Not billed. |
| 401 | Unauthorized | Missing or invalid x-api-key. |
| 402 | Payment Required | Your balance does not cover one lookup. Top up and retry. |
| 403 | Forbidden | No active subscription, or the key belongs to a plan without Flux. Sandbox keys are not affected. |
| 404 | Not Found | Not an error: the identifier is not on the register (data.valid: false). Billed. |
| 409 | Conflict | The Idempotency-Key was used for a different lookup, or the first request with it is still running. |
| 429 | Too Many Requests | Rate limit or the key's daily consumption cap (DAILY_CAP_EXCEEDED). Back off and retry. |
| 503 | Service Unavailable | The register could not be reached. Not billed; retry with the same Idempotency-Key. |
curl -X GET https://api.taxstreem.com/v1/flux/validate/taxid/2522507763846 \ -H "x-api-key: txsm_live_SK489c..." \ -H "Idempotency-Key: validate-7f3c2a"
{
"success": true,
"data": {
"valid": true,
"query": {
"type": "taxid",
"value": "2522507763846"
},
"companies": [
{
"name": "DANGOTE NIGERIA LTD",
"rcNumber": "38931",
"taxId": "2522507763846",
"classification": "COMPANY",
"status": "ACTIVE",
"natureOfBusiness": "General Merchandise",
"registeredAt": "1981-05-04T01:00:00Z",
"cacCompanyId": 204167,
"dataAsOf": "2026-11-21T14:30:00Z"
}
],
"source": "CAC iCRP public register",
"creditsUsed": 0.5,
"creditsRemaining": 99.5
},
"meta": {
"requestId": "flux_val_3b9e1c0d2a4f5e6b",
"timestamp": "2026-11-21T15:00:00Z"
}
}