TIN and Reference Codes

Validate a taxpayer TIN

Send the TIN and matching identification information as lowercase JSON properties:

curl --request POST "{api_base_url}/lhdn/tin_validation" \
  --header "Authorization: Bearer {access_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_tin":"{taxpayer_tin}",
    "customer_idtype":"BRN",
    "customer_idnum":"{business_registration_number}"
  }'

The response uses response_msg. Treat an error text as a failed validation even when the HTTP request itself succeeded.

Supported identity types depend on the taxpayer, including NRIC, PASSPORT, BRN, and ARMY. The TIN, type, and number must identify the same taxpayer.

Validate taxpayer information when creating or changing the customer or supplier master record, then cache the verified result. The official TIN validation guidance advises against calling the validation API before every document because unnecessary repeated calls can be throttled.

Search for a taxpayer TIN

The current AECloud search endpoint accepts identification type and value as query parameters:

curl --request GET "{api_base_url}/lhdn/tin_search?customer_idtype=BRN&customer_idnum={business_registration_number}" \
  --header "Authorization: Bearer {access_token}" \
  --header "Accept: application/json"

Use search to assist an authorized business process. Do not use it to enumerate taxpayer data.

Reference-code endpoints

Endpoint	Response content
GET /lhdn/classification_code	code, description
GET /lhdn/currency_code	code, currency
GET /lhdn/payment_method	code, payment_method
GET /lhdn/tax_type	code, description
GET /lhdn/unit_type	code, description, name

These endpoints return collection responses under items.

Reference-data strategy

• Retrieve codes during configuration or scheduled reference-data refresh, not for every invoice line.
• Store both code and description for user selection, but submit the code.
• Do not silently replace an obsolete or unknown code with a default.
• Record the reference-data refresh time.
• Revalidate mappings before production launch and after an announced LHDN change.

Use current reference endpoints and official MyInvois materials rather than copying a static code table into application source.