API reference
All 171 endpoints, grouped the way an integration uses them. Every page here is generated from the OpenAPI description, so it says exactly what the contract says.
Platform
7 endpointsHealth, tokens, key introspection, organizations and webhook subscriptions.
| GET | /health | Liveness probe |
| POST | /auth/token | Exchange a key pair for a short-lived token |
| GET | /me | Describe the calling key |
| GET | /organizations | List organizations |
| POST | /organizations | Create a child organization |
| GET | /organizations/{id} | Retrieve an organization |
| PUT | /organizations/{id} | Update statutory IDs and the pay calendar |
Org master
21 endpointsDepartments, designations, holiday calendar and shifts.
| GET | /departments | List departments |
| POST | /departments | Create a department |
| GET | /departments/{id} | Retrieve a department |
| PATCH | /departments/{id} | Update a department |
| DELETE | /departments/{id} | Delete a department |
| GET | /designations | List designations |
| POST | /designations | Create a designation |
| GET | /designations/{id} | Retrieve a designation |
| PATCH | /designations/{id} | Update a designation |
| DELETE | /designations/{id} | Delete a designation |
| GET | /holidays | List the holiday calendar |
| POST | /holidays | Add a holiday |
| GET | /holidays/{id} | Retrieve a holiday |
| PATCH | /holidays/{id} | Update a holiday |
| DELETE | /holidays/{id} | Delete a holiday |
| GET | /shifts | List shifts |
| POST | /shifts | Create a shift |
| GET | /shifts/{id} | Retrieve a shift |
| PATCH | /shifts/{id} | Update a shift |
| DELETE | /shifts/{id} | Delete a shift |
| POST | /shifts/{id}/assign | Assign employees to a shift |
Employees
10 endpointsThe employee master the engine reads on every run.
| GET | /employees | List employees |
| POST | /employees | Create or upsert an employee |
| POST | /employees/bulk | Bulk upsert employees |
| GET | /employees/{id} | Retrieve an employee |
| PATCH | /employees/{id} | Update an employee |
| POST | /employees/{id}/exit | Mark an employee's last working day |
| GET | /employees/{id}/bank | Retrieve bank details |
| PUT | /employees/{id}/bank | Replace bank details |
| GET | /employees/{id}/statutory | Retrieve statutory identifiers |
| PUT | /employees/{id}/statutory | Replace statutory identifiers |
Payroll configuration
34 endpointsOne-time per-organization setup - cycle, components, groups, TDS, PT, payment methods.
| GET | /payroll-settings | Retrieve payroll settings |
| PUT | /payroll-settings | Replace payroll settings |
| GET | /payroll-settings/period | Retrieve the period setting |
| PUT | /payroll-settings/period | Set the cut-off and the salary period |
| GET | /payroll-settings/salary-days | Retrieve the salary-days basis |
| PUT | /payroll-settings/salary-days | Choose calendar days or a fixed 30-day month |
| GET | /payroll-settings/currency | Retrieve the payroll currency |
| PUT | /payroll-settings/currency | Set the payroll currency |
| GET | /salary-components | List salary components |
| POST | /salary-components | Create a salary component |
| GET | /salary-components/{id} | Retrieve a salary component |
| PATCH | /salary-components/{id} | Update a salary component |
| DELETE | /salary-components/{id} | Delete a salary component |
| GET | /salary-groups | List salary groups |
| POST | /salary-groups | Create a salary group |
| GET | /salary-groups/{id} | Retrieve a salary group |
| PATCH | /salary-groups/{id} | Update a salary group |
| DELETE | /salary-groups/{id} | Delete a salary group |
| PUT | /salary-groups/{id}/components | Attach components and their values |
| POST | /salary-groups/{id}/employees | Assign employees to a salary group |
| GET | /tds-slabs | List TDS slabs |
| POST | /tds-slabs | Create a TDS slab |
| PATCH | /tds-slabs/{id} | Enable or disable a TDS slab |
| GET | /professional-tax/states | List professional tax states and slabs |
| POST | /professional-tax/states | Add a professional tax state |
| GET | /employees/{id}/professional-tax | Retrieve an employee's PT mapping |
| PUT | /employees/{id}/professional-tax | Map an employee to a PT state |
| GET | /reimbursement-rates | Retrieve reimbursement rates |
| PUT | /reimbursement-rates | Set reimbursement rates |
| GET | /payment-methods | List payment methods |
| POST | /payment-methods | Create a payment method |
| GET | /payroll-cycles | List payroll cycles |
| POST | /payroll-cycles | Create a payroll cycle |
| PUT | /employees/{id}/cycle | Assign an employee to a cycle |
Employee salary
9 endpointsPer-employee salary structure, increments and variable components.
| GET | /employees/{id}/salary | Retrieve the current salary structure |
| PUT | /employees/{id}/salary | Set the opening salary structure |
| POST | /employees/{id}/salary/increments | Record an increment or decrement |
| GET | /employees/{id}/salary/history | Retrieve the structure history |
| PUT | /employees/{id}/salary/allow-payroll | Allow or block payroll generation |
| GET | /employees/{id}/hourly-rate | Retrieve the hourly rate |
| PUT | /employees/{id}/hourly-rate | Set the hourly rate |
| GET | /employees/{id}/variable-components | List per-period extras |
| PUT | /employees/{id}/variable-components | Set per-period extras |
Period inputs
16 endpointsAttendance, leave, overtime, expenses and advances the run consumes.
| GET | /attendance | Read attendance for a window |
| POST | /attendance/bulk | Upsert daily attendance |
| GET | /leaves | List leave records |
| POST | /leaves | Create a leave record |
| PATCH | /leaves/{id} | Approve, reject or cancel a leave |
| GET | /overtime-requests | List overtime requests |
| POST | /overtime-requests | Raise an overtime request |
| POST | /overtime-requests/{id}/approve | Approve an overtime request |
| GET | /overtime-policies | List overtime policies |
| POST | /overtime-policies | Create an overtime policy |
| POST | /overtime-policies/{id}/assign | Assign employees to an overtime policy |
| GET | /expenses | List expenses |
| POST | /expenses | Create a reimbursable expense |
| POST | /expenses/{id}/approve | Approve an expense for the next run |
| GET | /employees/{id}/advances | List advances and loans |
| POST | /employees/{id}/advances | Create an advance with a recovery schedule |
Payroll runs
16 endpointsThe engine itself - preview, calculate, hold, lock, mark paid, reverse.
| POST | /payroll-runs/preview | Calculate a run without persisting it |
| GET | /payroll-runs | List payroll runs |
| POST | /payroll-runs | Create a run |
| GET | /payroll-runs/{id} | Retrieve a run |
| DELETE | /payroll-runs/{id} | Delete a draft run |
| POST | /payroll-runs/{id}/calculate | Calculate and persist the slips |
| POST | /payroll-runs/{id}/recalculate | Recalculate selected employees |
| GET | /payroll-runs/{id}/employees | List per-employee lines |
| GET | /payroll-runs/{id}/employees/{empId} | Retrieve one slip breakdown |
| PATCH | /payroll-runs/{id}/employees/{empId} | Override one slip |
| POST | /payroll-runs/{id}/hold | Hold or release employees |
| POST | /payroll-runs/{id}/lock | Freeze a run |
| POST | /payroll-runs/{id}/unlock | Unlock a run |
| POST | /payroll-runs/{id}/mark-paid | Mark a run paid |
| POST | /payroll-runs/{id}/email | Email payslip PDFs |
| POST | /payroll-runs/{id}/reverse | Reverse a run |
Payslips
6 endpointsGenerated slips as JSON, PDF and salary certificates.
| GET | /payslips | List payslips |
| GET | /payslips/{id} | Retrieve a payslip |
| GET | /payslips/{id}.pdf | Stream the payslip PDF |
| POST | /payslips/{id}/email | Email one payslip |
| GET | /payslips/{id}/salary-certificate | Salary certificate for the financial year |
| GET | /employees/{id}/payslips | List one employee's payslips |
Disbursement
3 endpointsBank files, disbursement summaries and Tally sync.
| GET | /payroll-runs/{id}/bank-file | Download the bank upload file |
| GET | /payroll-runs/{id}/disbursement-summary | Totals by bank and payment method |
| POST | /payroll-runs/{id}/sync-tally | Post the run to Tally |
Statutory
20 endpointsPF, ESI, PT, LWF and TDS returns in filing-ready formats.
| GET | /statutory/pf/ecr | PF ECR file |
| GET | /statutory/pf/form-5 | PF Form 5 - new joiners |
| GET | /statutory/pf/form-10 | PF Form 10 - exits |
| GET | /statutory/pf/form-12a | PF Form 12A - monthly return |
| GET | /statutory/pf/form-3a | PF Form 3A - annual member return |
| GET | /statutory/pf/form-6a | PF Form 6A - annual consolidated return |
| GET | /statutory/pf/statement | PF statement |
| GET | /statutory/esi/report | ESI monthly report |
| GET | /statutory/esi/return | ESI return |
| GET | /statutory/esi/form-01 | ESI Form 01 - employer registration |
| GET | /statutory/pt/report | Professional tax report |
| GET | /statutory/pt/return | Professional tax return |
| GET | /statutory/lwf/return | Labour welfare fund return |
| POST | /statutory/lwf/mark-submitted | Mark the LWF return filed |
| GET | /statutory/tds/24q | TDS Form 24Q |
| GET | /statutory/tds/26q | TDS Form 26Q |
| GET | /statutory/filings | Filing dashboard |
| GET | /government-forms | List tracked challans and acknowledgements |
| POST | /government-forms | Track a challan or acknowledgement |
| GET | /government-forms/{id} | Retrieve a tracked form |
FnF and gratuity
10 endpointsFull and final settlements and gratuity projections.
| GET | /fnf | List settlements |
| POST | /fnf | Open a settlement |
| GET | /fnf/{id} | Retrieve a settlement |
| POST | /fnf/{id}/recalculate | Recalculate a settlement |
| POST | /fnf/{id}/approve | Approve a settlement |
| POST | /fnf/{id}/cancel | Cancel a settlement |
| POST | /fnf/{id}/mark-paid | Mark a settlement paid |
| GET | /gratuity | Gratuity across the organization |
| GET | /gratuity/{employeeId} | One employee's gratuity projection |
| POST | /gratuity/export | Export the gratuity liability |
Reports
13 endpointsPayroll, attendance and compliance reports as JSON or file exports.
| GET | /reports/payroll-register/summary | Payroll register - summary |
| GET | /reports/payroll-register/detail | Payroll register - detail |
| GET | /reports/salary-register | Salary register |
| GET | /reports/attendance-summary | Attendance summary |
| GET | /reports/overtime | Overtime report |
| GET | /reports/ctc-annual | Annual CTC report |
| GET | /reports/pay-difference | Pay difference report |
| GET | /reports/monthly-tds | Monthly TDS report |
| GET | /reports/esi-deduction | ESI deduction report |
| GET | /reports/salary-summary | Salary summary |
| GET | /reports/gratuity | Gratuity report |
| GET | /reports/leave | Leave report |
| GET | /reports/expense | Expense report |
Imports
3 endpointsBulk file imports and their job status.
| GET | /imports/template | Download a sample import file |
| POST | /imports | Upload a file for import |
| GET | /imports/{jobId} | Check import progress |
Webhooks
3 endpointsEvent subscriptions. The events themselves are described under `webhooks`.
| GET | /webhooks | List webhook subscriptions |
| POST | /webhooks | Register a webhook subscription |
| DELETE | /webhooks/{id} | Remove a webhook subscription |