Search Taxpayer Tin API

Request Method

GET

Request URL

https://api-sandbox.my.cleartax.com/einvoice/v1/search/tin

Request Headers

Parameter	Data Type	Field Validations
x-cleartax-auth-token	String	Cannot be empty	Mandatory. User auth token.
x-clear-tin	String	Cannot be empty	Mandatory. TIN of the entity
x-clear-branch	String	Should be a valid branch from the user account	Optional. Branch name (store name) added in the user account which maps to a TIN of the entity.
x-request-id	UUID	Should be unique for every request	Optional. Unique request ID.
Content-Type	String	application/json	application/json

Request Query Params

Parameter	Data Type	Field Validations	Description
idType	String	Mandatory if idValue is passed NRIC VARCHAR (12 CHAR) - PASSPORT VARCHAR (12 CHAR) - BRN VARCHAR (20 CHAR) - ARMY VARCHAR (12 CHAR)	NRIC, Passport number, Business registration number, army number
idValue	String	Mandatory if idType is passed	The actual value of the ID Type selected. For example, if NRIC selected as ID Type, then pass the NRIC value here.
taxpayerName	String	Mandatory if idType and idValue are not passed	The Taxpayer Name.

Response Status Codes

HTTP Status Code	Description
200	For a successful status check
400	For any kind of invalid payload issues
401	If the user is not authenticated for the operation
403	If the user is not authorized for the operation

Response Schema

Parameter	Data Type	Field Validations	Description
NA	NA	NA	NA

Error Details Object

Parameter	Data Type	Field Validations	Description
error_code	String	Cannot be null	A code to identify the error. Error codes are published below.
error_message	String	Cannot be null	Human readable error message.

Sample Response (Success)

HTTP Status Code: 200

Response Body

{
    "Tin": "C58746708080",
    "ErrorDetail": null
}

{
    "Tin": null,
    "ErrorDetail": [
        {
            "ErrorCode": "ERR-10006",
            "ErrorMessage": "Taxpayer Tin not found with provided details.",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

Sample Response (Error)

Case1: Invalid Query Params

HTTP Status Code

400

Response Body

{
    "ErrorDetails": [
        {
            "ErrorCode": "300119",
            "ErrorMessage": "Both Id Type and Id Value must be passed to search taxpayer TIN",
            "ErrorSource": "CLEARTAX",
            "Path": null
        }
    ]
}

API Validations

NA

API Constraints

1. This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401.

2. If the auth token is valid, but the user does not have the authorization to generate e-invoice for a document, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular TIN used in the request.

3. Rate Limit: The below rate limits are in line with those applied by LHDN.

   Production - 60 API calls per minute with a burst capacity of 6 API calls

   Sandbox - 30 API calls per minute with a burst capacity of 6 API calls