TIN Verification by phone number
Retrieve the taxpayer record registered against a Nigerian phone number. Billed as part of TIN Verification — the same subscription covers this and /tin/verify.
/v1/tin/by-phoneAuthorization
api-key In: header
Header Parameters
Required for live-mode keys. Unique key identifying this request attempt.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/v1/tin/by-phone" \ -H "Content-Type: application/json" \ -d '{ "phoneNumber": "08012345678" }'{ "success": true, "statusCode": 200, "message": "Request processed successfully", "timestamp": "2025-10-20T16:30:00.000Z", "path": "/v1/auth/register", "data": { "verificationStatus": "VERIFIED", "referenceId": "VER-TIN_NG-JPGI3POERX", "verificationId": "9f2c1a7b4e6d8f30", "charged": true, "chargeAmount": 50, "taxpayer": { "firsTin": "20304753-0001", "jtbTin": "10001", "taxpayerName": "ACME LIMITED", "cacRegNumber": "2030404", "taxOffice": "MSTO GARKI", "phoneNumber": "08012345678", "email": "accounts@acme.example", "address": "13 Some Street, Garki" } }}TIN Verification
Retrieve the taxpayer record for a FIRS tax identification number (NNNNNNNN-NNNN). To look one up by phone number use /tin/by-phone. To check only whether a number exists, without retrieving the record, use /tin/validate — which takes the bare-digit NRS form instead. Requires a valid Idempotency-Key header for live-mode API keys to prevent duplicate charges.
TIN Validation
Check whether a tax identification number exists, without retrieving the taxpayer record. Takes the bare-digit NRS form (10-13 digits), which is a different form from the one /tin/verify takes. **A 200 means the check ran, not that the number exists — read `result`, which is VALID or INVALID.** A negative answer is a real answer and is charged for. Billed separately from TIN Verification; a subscription to one does not grant the other.