> ## 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 Tax Creation API

> Create a TDS tax rate for your organization

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json
```

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

## Request

**Content-Type:** `application/json`

Creates a custom TDS rate in your organization tax master. Use the returned `id` as `tdsId` when creating vendor advances or other transactions that need a TDS deduction.

To list rates that already exist, use the [TDS Taxes API](/apis/taxes-tds).

### Body Parameters

| Parameter | Type   | Required | Constraints                                                                    | Description                                                                            |
| --------- | ------ | -------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `name`    | string | Yes      | 1–255 characters                                                               | Display name for the rate in Pazy (returned as `label` on list)                        |
| `section` | string | Yes      | Valid TDS section id from the Pazy tax catalog (e.g. `194C1`, `1023`, `194J1`) | Section the deduction applies under — same ids used when creating rates in the Pazy UI |
| `rate`    | number | Yes      | 0–100                                                                          | Deduction percentage                                                                   |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/taxes/tds \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "TDS 194C 1%",
      "section": "194C1",
      "rate": 1
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/taxes/tds', {
    method: 'POST',
    headers: {
      Authorization: 'Api-Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'TDS 194C 1%',
      section: '194C1',
      rate: 1
    })
  });

  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",
      "Content-Type": "application/json"
  }
  payload = {
      "name": "TDS 194C 1%",
      "section": "194C1",
      "rate": 1
  }

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

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                  | Type    | Description                                                         |
| ---------------------- | ------- | ------------------------------------------------------------------- |
| `ok`                   | boolean | Indicates whether the request was successful                        |
| `data.tax.id`          | string  | Tax id. Pass this as `tdsId` to transaction create APIs             |
| `data.tax.label`       | string  | Display name given to the tax                                       |
| `data.tax.description` | string  | Description of the TDS section, or `-` when none is on record       |
| `data.tax.section`     | string  | Income Tax Act section e.g. `194C`                                  |
| `data.tax.rate`        | number  | Deduction percentage                                                |
| `data.tax.rateType`    | string  | How `rate` is applied — `PERCENTAGE` for rates created via this API |
| `data.tax.dateCreated` | string  | ISO 8601 timestamp of when the tax was created                      |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "tax": {
      "id": "5021",
      "label": "TDS 194C 1%",
      "description": "Payment of contractors HUF/Individual ",
      "section": "194C1",
      "rate": 1,
      "rateType": "PERCENTAGE",
      "dateCreated": "2026-09-02T06:45:12.110Z"
    }
  }
}
```

## Error Responses

### Validation Errors

**HTTP Status:** `400 Bad Request`

Returned when `section` is not a recognized TDS section id.

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unknown TDS section: 999X"
  }
}
```

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

* Prefer creating rates once and reusing the returned `id` across transactions rather than creating a duplicate rate per bill
* Match `section` to a catalog id from the Pazy UI / tax master (e.g. `194C1`, `1023`) — free-text labels like bare `194C` are rejected unless they exist as an id
* After create, confirm the rate appears on [List TDS Taxes](/apis/taxes-tds) before hardcoding the id in downstream jobs