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.

Last updated

Was this helpful?