> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TDS Taxes API

> List the TDS tax rates configured for your organization

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

The permission required on your API key is **Tax** with the **Read** action enabled.

## Request

This endpoint takes no path parameters, query parameters, or body. Every TDS tax configured for the organization is returned in a single response — there is no pagination.

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.pazy.io/v1.0/taxes/tds \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/taxes/tds', {
    method: 'GET',
    headers: {
      Authorization: 'Api-Key YOUR_API_KEY'
    }
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/taxes/tds"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                        | Type    | Description                                                                                            |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `ok`                         | boolean | Indicates whether the request was successful                                                           |
| `data.tdsList`               | array   | TDS taxes configured for the organization                                                              |
| `data.tdsList[].id`          | string  | Tax id. Pass this as `tdsId` to the [Vendor Advance Creation](/apis/vendor-advance-creation) API       |
| `data.tdsList[].label`       | string  | Display name given to the tax in Pazy                                                                  |
| `data.tdsList[].description` | string  | Description of the TDS section this tax falls under. `-` when the section has no description on record |
| `data.tdsList[].section`     | string  | Income Tax Act section the deduction applies under e.g. `194C`, `194J`                                 |
| `data.tdsList[].rate`        | number  | Deduction value — a percentage when `rateType` is `PERCENTAGE`, an absolute amount when `ABSOLUTE`     |
| `data.tdsList[].rateType`    | string  | How `rate` is applied: `PERCENTAGE` or `ABSOLUTE`                                                      |
| `data.tdsList[].dateCreated` | string  | ISO 8601 timestamp of when the tax was created                                                         |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "tdsList": [
      {
        "id": "5019",
        "label": "TDS 194C LDC 1%",
        "description": "TDS for product shoes",
        "section": "194C",
        "rate": 1,
        "rateType": "PERCENTAGE",
        "dateCreated": "2026-06-19T13:17:51.749Z"
      },
      {
        "id": "5020",
        "label": "TDS 194J 10%",
        "description": "Fees for professional or technical services",
        "section": "194J",
        "rate": 10,
        "rateType": "PERCENTAGE",
        "dateCreated": "2026-05-02T10:11:03.221Z"
      }
    ]
  }
}
```

### Empty Result

An organization with no TDS taxes configured returns `200` with an empty array, not an error:

```json theme={null}
{
  "ok": true,
  "data": {
    "tdsList": []
  }
}
```

## Error Responses

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

Returned when the API key doesn't have the **Tax** resource with the **Read** action enabled.

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Rate Limiting

**HTTP Status:** `429 Too Many Requests`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  }
}
```

### Server Errors

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}
```

## Best Practices

* Use `id` as the `tdsId` when creating a vendor advance, and compute the expected `tdsAmount` from `rate` and `rateType` — the create API validates your figure against its own calculation and rejects a mismatch
* Refresh this list at the start of each integration run rather than hardcoding ids; taxes are added and retired over time
* Match on `section` (not `label`) when mapping to your own tax master — labels are free text set by the organization