Independence Day offer · ₹52/employee/moClaim offer
INDPayroll
API reference

Employee salary

Per-employee salary structure, increments and variable components.

Base URLhttps://api.indpayroll.com/v19 endpoints
GET /employees/{id}/salary

Retrieve the current salary structure

The CTC or daily wage in force today, broken into the components the engine will value on the next run.

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Query parameters

as_on
string (date)
Read the structure in force on a past date.

Responses

  • 200 The structure. EmployeeSalary
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
Request
curl -X GET https://api.indpayroll.com/v1/employees/{id}/salary \
  -H "Authorization: Bearer $INDP_API_KEY"
Response · 200
{
  "employee_id": "ext:emp-1001",
  "basis": "monthly_ctc",
  "monthly_ctc": 85000,
  "annual_ctc": 1020000,
  "daily_wage": null,
  "salary_group_id": 3,
  "effective_from": "2026-04-01",
  "allow_generate_payroll": true,
  "components": [
    {
      "code": "BASIC",
      "name": "Basic",
      "kind": "earning",
      "monthly_amount": 42500,
      "annual_amount": 510000
    },
    {
      "code": "HRA",
      "name": "House Rent Allowance",
      "kind": "earning",
      "monthly_amount": 17000,
      "annual_amount": 204000
    },
    {
      "code": "SPL",
      "name": "Special Allowance",
      "kind": "earning",
      "monthly_amount": 21700,
      "annual_amount": 260400
    },
    {
      "code": "PF_EMPLOYER",
      "name": "Employer PF",
      "kind": "employer_contribution",
      "monthly_amount": 1800,
      "annual_amount": 21600
    }
  ]
}
PUT /employees/{id}/salary

Set the opening salary structure

Use this once per employee, when they join. Later changes belong in POST /employees/{id}/salary/increments, which keeps the history and the effective dates the engine pro-rates against.

Send a salary_group_id to inherit a template, or components to state the split explicitly. Sending both is rejected.

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Body application/json · required

basis required
enum: monthly_ctc, daily_wage, hourly
Monthly CTC, daily wage or hourly.
monthly_ctc
number (double)
Monthly cost to company.
daily_wage
number (double)
Rate per day.
hourly_rate
number (double)
Rate per hour.
salary_group_id
integer
Inherit the components of this group. Mutually exclusive with components.
components
object[]
State the split explicitly. Mutually exclusive with salary_group_id.
effective_from required
string (date)
The date this structure starts applying from.

Responses

  • 200 Structure set. EmployeeSalary
  • 400 The request was malformed or failed validation. ErrorResponse
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
  • 422 The request was well-formed but the engine could not compute it - a missing salary structure, no PT state on an employee, or a period with no inputs. ErrorResponse
Request
curl -X PUT https://api.indpayroll.com/v1/employees/{id}/salary \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "basis": "monthly_ctc",
  "monthly_ctc": 85000,
  "salary_group_id": 3,
  "effective_from": "2026-04-01"
}'
POST /employees/{id}/salary/increments

Record an increment or decrement

Effective-dated. A change landing mid-period is pro-rated across the two structures, so an increment on the 16th pays half the month at each rate.

Set arrears: true to pay the difference for elapsed months of the financial year in the next run.

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Headers

Idempotency-Key
string
A unique key, at most 255 characters, that makes this request safe to retry. Replaying a key within 24 hours returns the original response and does not act again.

Body application/json · required

id
string
—
type
enum: increment, decrement
—
effective_from required
string (date)
—
new_monthly_ctc
number (double)
An amount in the organization's payroll currency, to two decimal places.
new_daily_wage
number (double)
An amount in the organization's payroll currency, to two decimal places.
percent
number
Send instead of an absolute amount to raise the current CTC by a percentage.
salary_group_id
integer
Move the employee onto a different structure at the same time.
reason
string
—
arrears
boolean
True pays the difference for elapsed months of the current financial year as arrears in the next run.

Responses

  • 201 Recorded. The response carries the structure that results. EmployeeSalary
  • 400 The request was malformed or failed validation. ErrorResponse
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
  • 409 The resource is in a state that forbids the change - a locked or paid run, a duplicate external_id, or a settlement already approved. ErrorResponse
Request
curl -X POST https://api.indpayroll.com/v1/employees/{id}/salary/increments \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "increment",
  "effective_from": "2026-04-01",
  "new_monthly_ctc": 95000,
  "reason": "Annual appraisal 2026",
  "arrears": true
}'
GET /employees/{id}/salary/history

Retrieve the structure history

Every structure the employee has held, in effective-date order, with who changed it and why.

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Responses

  • 200 History, newest first. object
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
Request
curl -X GET https://api.indpayroll.com/v1/employees/{id}/salary/history \
  -H "Authorization: Bearer $INDP_API_KEY"
Response · 200
{
  "data": [
    {
      "effective_from": "2026-04-01",
      "effective_to": null,
      "monthly_ctc": 95000,
      "salary_group_id": 3,
      "change_type": "increment",
      "reason": "Annual appraisal 2026",
      "changed_at": "2026-09-30T09:41:02Z",
      "changed_by": "indp_live_9f2c41ab"
    },
    {
      "effective_from": "2024-06-01",
      "effective_to": "2026-03-31",
      "monthly_ctc": 85000,
      "salary_group_id": 3,
      "change_type": "initial",
      "changed_at": "2024-05-28T11:02:44Z",
      "changed_by": "indp_live_9f2c41ab"
    }
  ]
}
PUT /employees/{id}/salary/allow-payroll

Allow or block payroll generation

Keeps an employee on the master but out of every run - a sabbatical, a suspension, a dispute. Unlike an exit, it is reversible and leaves the joining date and structure untouched.

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Body application/json · required

allow_generate_payroll required
boolean
—
reason
string
—

Responses

  • 200 Updated. AllowPayrollFlag
  • 400 The request was malformed or failed validation. ErrorResponse
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
Request
curl -X PUT https://api.indpayroll.com/v1/employees/{id}/salary/allow-payroll \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "allow_generate_payroll": false,
  "reason": "Unpaid sabbatical to December."
}'
GET /employees/{id}/hourly-rate

Retrieve the hourly rate

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Responses

  • 200 The rate. HourlyRate
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
PUT /employees/{id}/hourly-rate

Set the hourly rate

For hourly and timelog payroll. Pay is valued from logged hours when the run is calculated with add_timelogs: true.

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Body application/json · required

employee_id
string
—
hourly_rate required
number (double)
An amount in the organization's payroll currency, to two decimal places.
standard_hours_per_day
number
—
overtime_multiplier
number
Applied to hours beyond the standard day when no overtime policy covers the employee.
effective_from
string (date)
—

Responses

  • 200 Updated. HourlyRate
  • 400 The request was malformed or failed validation. ErrorResponse
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
Request
curl -X PUT https://api.indpayroll.com/v1/employees/{id}/hourly-rate \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "hourly_rate": 320,
  "standard_hours_per_day": 8,
  "overtime_multiplier": 2,
  "effective_from": "2026-10-01"
}'
GET /employees/{id}/variable-components

List per-period extras

Bonuses, incentives and arrears attached to a period rather than to the standing structure.

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Query parameters

period
string
Period in YYYY-MM form. Defaults to the open one.

Responses

  • 200 Variable components. object
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
PUT /employees/{id}/variable-components

Set per-period extras

Replaces the period's extras by default. The taxable, pf_applicable and esi_applicable flags decide how each one is treated - an incentive is usually taxable and ESI-applicable but outside PF wages.

Path parameters

id required
string
Employee id, or your own identifier prefixed with ext: - /employees/ext:emp-1001.

Body application/json · required

components required
VariableComponent[]
—
replace
boolean
True replaces every variable component in the period; false merges by code.

Responses

  • 200 Updated. object
  • 400 The request was malformed or failed validation. ErrorResponse
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
  • 409 The resource is in a state that forbids the change - a locked or paid run, a duplicate external_id, or a settlement already approved. ErrorResponse
Request
curl -X PUT https://api.indpayroll.com/v1/employees/{id}/variable-components \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "replace": true,
  "components": [
    {
      "code": "INCENTIVE",
      "name": "Q2 sales incentive",
      "amount": 18000,
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "taxable": true,
      "pf_applicable": false,
      "esi_applicable": true
    }
  ]
}'
Previous
Payroll configuration
Next
Period inputs