TaxStreem Logo
DOCS/flux/validate

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

GEThttps://api.taxstreem.com/v1/flux/validate/taxid/{taxId}

Path Parameter

ParameterTypeRequiredDescription
taxIdstringRequiredNRS 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

HeaderRequiredDescription
x-api-keyRequiredA Flux production key (txsm_live_) or any sandbox key (txsm_test_).
Idempotency-KeyRequiredA 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

FieldTypeDescription
data.validbooleanTrue when the identifier is on the CAC register.
data.queryobjectWhat was looked up: type (rc or taxid) and the normalised value.
data.companies[].namestringApproved name on the register.
data.companies[].rcNumberstringRC/BN number as CAC prints it.
data.companies[].taxIdstring | nullNRS Tax ID; null when none has been issued.
data.companies[].classificationstringCOMPANY, BUSINESS_NAME, IT (incorporated trustees), LP or LLP.
data.companies[].statusstringRegister status, e.g. ACTIVE, INACTIVE, STRUCK OFF, IN LIQUIDATION.
data.companies[].natureOfBusinessstringDeclared line of business, when CAC has one.
data.companies[].registeredAtstring | nullRegistration date (ISO 8601).
data.companies[].dataAsOfstringWhen this record was last read from the register.
data.creditsUsednumberCredits charged for this lookup.
data.creditsRemainingnumberBalance 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 StatusError KeyCause & Resolution
400Bad RequestMalformed Tax ID or missing Idempotency-Key. Not billed.
401UnauthorizedMissing or invalid x-api-key.
402Payment RequiredYour balance does not cover one lookup. Top up and retry.
403ForbiddenNo active subscription, or the key belongs to a plan without Flux. Sandbox keys are not affected.
404Not FoundNot an error: the identifier is not on the register (data.valid: false). Billed.
409ConflictThe Idempotency-Key was used for a different lookup, or the first request with it is still running.
429Too Many RequestsRate limit or the key's daily consumption cap (DAILY_CAP_EXCEEDED). Back off and retry.
503Service UnavailableThe register could not be reached. Not billed; retry with the same Idempotency-Key.
Example Request
curl -X GET https://api.taxstreem.com/v1/flux/validate/taxid/2522507763846 \
  -H "x-api-key: txsm_live_SK489c..." \
  -H "Idempotency-Key: validate-7f3c2a"
Example Response
200 OK
{
  "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"
  }
}