TDS Compliance API

Overview

The RegInfra API is organized around REST. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes. The API processes one vendor payment per request and returns a complete TDS decision with the full reasoning chain attached.

Every response includes the applicable section, rate, deduction amount, threshold state at payment time, and a plain-English justification suitable for statutory audit documentation. Decisions are stored permanently and queryable at any time.

Test vs live mode

The API key you use determines the mode. Test mode keys have the prefix tds_test_ and do not create compliance records or affect your live vendor data. Live keys have the prefix tds_live_.

Authentication

All requests must include your API key in the x-api-key header. Requests without a valid key return 401 authentication_error.

x-api-key: tds_live_your_key_here
Content-Type: application/json

Requesting access

During beta, API keys are provisioned manually. Request a free trial at reginfra.com/#trial or email contact@reginfra.com. You will receive a test key within 24 hours on business days.

Base URL & versioning

The current API version is v1. The version is specified in the URL path.

Breaking changes are never made to an existing version. When CBDT issues a circular — rates and thresholds update automatically on the effective date. Your integration keeps working without any changes.

Deprecation notices are issued a minimum of 6 months in advance.

Idempotency

The API supports idempotency for safely retrying requests without processing the same vendor payment twice. Include a unique Idempotency-Key header with every request.

Idempotency-Key: INV-2026-001-v1

Key format

Use your invoice number, transaction reference, or a UUID. Keys must be under 255 characters and are retained for 24 hours.

// Good — use meaningful identifiers
Idempotency-Key: INV-2026-001
Idempotency-Key: TXN-Q1-2026-042
Idempotency-Key: VENDOR_001_2026-04-18_50000

// Bad — too generic, risk of collision
Idempotency-Key: 12345

Core endpoint — compute TDS

This is the primary endpoint. Call it at the moment of vendor payment. It returns the correct TDS decision with the complete reasoning chain and stores the decision permanently.

Replace {section} with the section identifier — e.g. 194C, 194J, 194A.

Sample request — 194J professional services

POST https://api.reginfra.com/v1/tds/194J/compute
Content-Type: application/json
x-api-key: tds_live_your_key_here
Idempotency-Key: INV-2026-001

{
  "transaction_id": "INV-2026-001",
  "pan": "ABCDE1234F",
  "vendor_name": "ABC Consulting Pvt Ltd",
  "deductee_type": "Company",
  "residential_status": "Resident",
  "pan_status": "Available",
  "is_206ab_applicable": false,
  "is_pan_operative": true,
  "nature_of_payment": "professional_fees",
  "service_type": "Professional_Services",
  "credit_amount": 75000,
  "aggregate_amount_ytd": null,
  "credit_datetime": "2026-04-18T10:00:00"
}

{
  "section": "194J",
  "tds_rate": "0.10",
  "tds_amount": "7500.00",
  "currency": "INR",
  "computed_at": "2026-04-18T10:32:39+00:00",
  "legal_reference": {
    "act": "Income-tax Act, 2025",
    "section": "393 Table 1 S.No.(6)(iii)",
    "section_title": "Fees for professional or technical services",
    "effective_from": "2026-04-01"
  },
  "calculation_reasoning": {
    "threshold_check": "₹75,000 exceeds threshold ₹50,000 — TDS applicable",
    "rate_selection": "10% — PAN available, Professional_Services",
    "aggregate_impact": "YTD after this payment: ₹75,000"
  },
  "meta": {
    "rule_id": "r_ac29066e",
    "rule_version": "1.0.0"
  },
  "warnings": []
}

Request fields

Required fields

Optional fields

Response fields

GET /transactions

Query stored TDS decisions. Returns all decisions matching the filter criteria. Query stored decisions for any vendor, date range, or section. Use for audit documentation, reconciliation, or historical reporting.

Query parameters

GET /v1/tds/transactions?vendor_pan=ABCDE1234F&from_date=2026-04-01&to_date=2026-06-30

GET /health

Returns API status. Use for monitoring and uptime checks.

{ "status": "ok", "version": "1.0.0" }

TDS sections covered

Section mismatch detection

If you call POST /v1/tds/194C/compute but the nature_of_payment field indicates professional fees, RegInfra returns a 400 section_mismatch error before any deduction is calculated. The error includes the correct section to use.

{
  "error": "section_mismatch",
  "message": "nature_of_payment 'professional_fees' is not valid under 194C",
  "correct_section": "194J",
  "correct_endpoint": "/v1/tds/194J/compute"
}

Error codes

Rate limits

Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Upcoming endpoints

• POST /v1/tds/validate — Pre-payment validation without storing a decision. Check section and rate before committing.
• GET /v1/tds/ytd/{pan} — Current YTD aggregate for a vendor PAN across all sections.
• GET /v1/tds/export/26Q — Export quarterly 26Q filing data in NSDL format.