# 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    | <p>Mandatory if idValue is passed</p><p><br></p><p>NRIC VARCHAR (12 CHAR)</p><p>- PASSPORT VARCHAR (12 CHAR)</p><p>- BRN VARCHAR (20 CHAR)</p><p>- ARMY VARCHAR (12 CHAR)</p> | 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

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

```json
{
    "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

```json
{
    "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.&#x20;

   **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**