Validate a TIN
Verify a Tax Identification Number against the LHDN database before creating invoices
Before creating an invoice with a new buyer, you can validate their Tax Identification Number (TIN) against the LHDN database. This helps catch errors early and avoids submission rejections due to invalid buyer details.
How TIN Validation Works
The TIN validation endpoint checks whether a given TIN and registration number combination is recognized by LHDN's MyInvois system. BizCARE caches successful validation results, so repeated lookups for the same TIN are served instantly without hitting the LHDN API again.
Validate a TIN
Send a POST request with the TIN, registration type, and registration number.
curl -X POST https://api.bizcare.my/api/v1/validation/tin \
-H "X-Api-Key: biz_test_your-api-key" \
-H "Content-Type: application/json" \
-d '{
"tin": "C25845670020",
"registrationType": "BRN",
"registrationNumber": "201901067890"
}'Successful Validation
{
"success": true,
"data": {
"valid": true
},
"message": "TIN is valid"
}Cached Result
If the same TIN and registration number have been validated before, the response is served from cache:
{
"success": true,
"data": {
"valid": true
},
"message": "TIN is valid (cached)"
}Cached validations are returned immediately without contacting the LHDN API. This is significantly faster and does not count against LHDN's rate limits.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
tin | string | Yes (400 without it) | The Tax Identification Number to validate (e.g., C25845670020) |
registrationType | string | Yes | One of BRN, NRIC, PASSPORT, or ARMY |
registrationNumber | string | No | The corresponding business registration or identification number |
Your company must be fully set up with valid LHDN credentials before you can validate TINs. The validation endpoint uses your company's clientId and clientSecret to authenticate with the LHDN API.
Invalid TINs and Errors
An unrecognised TIN is not an HTTP error. LHDN answers "no such TIN" and the API returns 200 with valid: false:
{
"success": true,
"data": { "valid": false },
"message": "TIN is invalid"
}Always read data.valid. These cases are real errors and use the standard error envelope:
| Status | code | When |
|---|---|---|
400 | VALIDATION_ERROR | tin is missing (message "TIN is required") |
404 | NOT_FOUND | No company is set up, so there are no LHDN credentials to use ("Company not found for TIN validation") |
409 | SELF_DEALING | The TIN or registration number is your own company's. A buyer or supplier must be a different party. |
502 | LHDN_ERROR | LHDN is unreachable or failed. Retry later. |
{
"success": false,
"error": "This is your own company's TIN or registration number. The buyer or supplier must be a different party.",
"message": "This is your own company's TIN or registration number. The buyer or supplier must be a different party.",
"code": "SELF_DEALING"
}Registration Types
| Type | Description | Example Number |
|---|---|---|
BRN | Business Registration Number (SSM) | 202301045678 |
NRIC | Malaysian National ID | 901215145678 |
PASSPORT | Passport number (foreign entities) | A12345678 |
ARMY | Military identification number | ARM-2023-001 |
Best Practices
- Validate buyer TINs before invoice creation. This prevents LHDN submission rejections caused by invalid buyer details.
- Cache-friendly: Feel free to call this endpoint liberally. Repeated lookups for the same TIN are served from cache and do not incur LHDN API calls.
- Include the registration number when possible. While optional, providing it enables BizCARE to cache the result for future lookups and gives a more thorough validation.