Tax Declaration API related to Housing and Other Income Details

The Tax Declaration APIs now include support for Housing Details (Rented and Owned properties) and Income from Other Sources (TDS/TCS). These additions help provide a complete view of an employee’s tax declaration data and the inputs required for tax calculations.

The updates include:

• Enhancements to the Read Tax Declaration API
• New APIs to submit housing details
• New support for Income from Other Sources and TDS/TCS

Overview

To enable accurate tax calculations and a comprehensive employee tax profile, the following data points are now included:

1. House Rent Allowance (HRA) – Rented Residence
2. House Property Details – Owned Residence
3. Income from Other Sources
4. TDS/TCS Outside Salary

These additions allow integrators to fetch and submit all the required tax declaration inputs using Keka APIs.

Read Tax Declaration API Enhancement

The Read Tax Declaration API now returns additional fields related to housing details and income from other sources.

Endpoint

GET /v1/payroll/employees/taxdeclarations

Purpose

Retrieve an employee’s complete tax declaration including:

• Existing declaration components
• Rented residence details
• Owned house property details
• Income from other sources
• TDS/TCS outside salary

House Rent Allowance – Rented Residence

The rentedResidence object contains details of houses where the employee pays rent and claims HRA exemption.

Employees can declare multiple landlords, and each landlord may require PAN verification or declaration documents.

Example Response

{
  "houseIdentifier": "P427Y8UCZ6",
  "rentPaid": 1234000,
  "address": "Hyderabad",
  "city": "Other Non Metro",
  "landlords": [
    {
      "name": "LANDLORD HYDERABAD",
      "address": "Hyderabad",
      "pan": "GOVERNMENT",
      "isVerified": false,
      "signedDeclaration": {
        "name": "SSE Umesh.pdf",
        "location": "taxbills/e5fe05ba2c1e4337817a180fa1ed4a14.pdf",
        "uploadedOn": "2026-02-18T10:49:40Z",
        "uploadedBy": "4950"
      },
      "hasPan": false,
      "ownerType": "GOVERNMENT"
    },
    {
      "name": "LANDLORD HYDERABAD",
      "address": "Hyderabad",
      "pan": "HPWPS2492G",
      "isVerified": true,
      "signedDeclaration": null,
      "isSameAddress": true,
      "hasPan": true,
      "ownerType": null
    }
  ],
  "attachedDocuments": [
    {
      "name": "Nitin Patel SE.pdf",
      "location": "taxbills/2e625f609ea4482cbdcdffbc59450b7d.pdf",
      "uploadedOn": "2026-02-18T08:31:33Z",
      "uploadedBy": "4950"
    }
  ],
  "status": 2,
  "to": "2023-12-01",
  "from": "2023-04-01"
}

Key Fields

House Property Details – Owned Residence

Employees can also declare self-owned property for home loan interest deductions.

This section captures property occupancy details and loan interest details.

Example Response

{
  "details": {
    "id": "8fc5e0b7-f199-4afc-8c1a-d0b64b9e4ad5",
    "occupancyType": 0,
    "status": "ACCEPTED",
    "address": "string",
    "netAnnualRentRecieved": 23232,
    "rentDetails": {
      "annualLettableValue": 1234,
      "municipalTaxesPaid": 2345,
      "unrealizedRent": 3456
    }
  },
  "lenderDetails": {
    "lenderName": "string",
    "lenderPan": "string",
    "loanDetails": {
      "interestPaidByEmployee": true,
      "loanInterestAmount": 12345,
      "purposeOfLoan": "Home Construction or Purchase"
    }
  },
  "attachmentDetails": {
    "attachmentId": "string",
    "attachmentUrl": "string"
  }
}

Occupancy Types

Conditional Fields

• rentDetails is returned only if occupancyType = 1 or 2
• lenderDetails appears only if interest is paid by the employee

Income from Other Sources (TDS / TCS)

Employees can declare income from sources outside salary along with tax already deducted or collected.

This helps employers calculate accurate tax liability during payroll processing.

Example Response

{
  "id": "string",
  "incomeFromOtherSources": {
    "netInterestReceived": 1,
    "commissionIncome": 2,
    "otherProfessionalIncome": 3,
    "totalIncomeFromOtherSources": 6
  },
  "tdsTcsOutsideSalary": {
    "tdsDeductedOnOtherIncome": 4,
    "tcsCollectedOnHighValueTransactions": 5,
    "totalTaxOutsideSalary": 9
  },
  "attachmentDetails": {
    "attachmentId": "string",
    "attachmentUrl": "string"
  }
}

Supported Income Fields

TDS / TCS Fields

Add Housing Details (Rented Residence)

This API allows creating rental residence declarations for employees claiming HRA exemption.

Endpoint

POST /api/v1/payroll/taxdeclaration/rentalresidence

Query Parameters

Body Type

Form Body

The request should include:

• Rent details
• Property address
• Landlord details
• Rent receipt attachments

Employees can declare multiple landlords for a single residence.

Add Housing Details (Owned Residence)

This API allows employees to declare owned house property details including loan interest.

Endpoint

POST /api/v1/payroll/taxdeclaration/ownresidence

Query Parameters

Body Type

Form Body

This API supports submitting:

• Property details
• Occupancy type
• Loan interest details
• Lender information
• Supporting documents

Add Income from Other Sources

This API enables employees to declare income earned outside salary and associated TDS/TCS values.

The declaration includes:

• Interest income
• Commission income
• Professional income
• Tax deducted at source
• Tax collected at source

Attachments can be uploaded as supporting documents.