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

FnF and gratuity

Full and final settlements and gratuity projections.

Base URLhttps://api.indpayroll.com/v110 endpoints
GET /fnf

List settlements

Query parameters

organization_id
integer
Organization to act on. Required when the API key can reach more than one organization; optional - and defaulted - when it can reach exactly one.
status
enum: draft, approved, paid, cancelled
—
employee_id
string
—
page
integer
1-based page number.
per_page
integer
Items per page. The engine caps this at 200.

Responses

  • 200 Settlements. object
  • 401 The key is missing, unknown, or the HMAC signature did not verify. ErrorResponse
POST /fnf

Open a settlement

Builds a draft settlement for an employee who has been exited: the final month's pay, leave encashment, gratuity if the service qualifies, less notice recovery and any outstanding advance.

The employee must already have a date of leaving - call POST /employees/{id}/exit first, or let that call open the settlement for you with create_fnf: true.

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

employee_id required
string
—
settlement_date
string (date)
—
include_leave_encashment
boolean
—
leave_balance_days
number
Send when you hold leave balances yourself. Otherwise the engine reads its own.
include_gratuity
boolean
—
notice_recovery_days
number
—
additional_earnings
PayslipLine[]
—
additional_deductions
PayslipLine[]
—
remarks
string
—

Responses

  • 201 Draft settlement. FnfSettlement
  • 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
  • 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 POST https://api.indpayroll.com/v1/fnf \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "employee_id": "ext:emp-1044",
  "settlement_date": "2026-10-05",
  "include_leave_encashment": true,
  "leave_balance_days": 7.5,
  "include_gratuity": true,
  "notice_recovery_days": 0,
  "additional_deductions": [
    {
      "code": "ASSET",
      "name": "Asset recovery - laptop",
      "amount": 4500
    }
  ]
}'
Response · 201
{
  "id": "fnf_01J9K7YR4H",
  "employee_id": "ext:emp-1044",
  "employee_name": "Sanjay Patnaik",
  "organization_id": 42,
  "date_of_leaving": "2026-09-18",
  "settlement_date": "2026-10-05",
  "status": "draft",
  "payable_days": 18,
  "leave_encashment": {
    "days": 7.5,
    "rate_basis": "basic",
    "amount": 18750
  },
  "gratuity": {
    "eligible": true,
    "years_of_service": 6.3,
    "amount": 115385
  },
  "notice_recovery": 0,
  "advance_recovery": 10000,
  "gross": 178135,
  "total_deductions": 19820,
  "net_payable": 158315
}
GET /fnf/{id}

Retrieve a settlement

Components, leave encashment, gratuity and recoveries, line by line.

Path parameters

id required
string
INDPayroll id of the resource.

Responses

  • 200 The settlement. FnfSettlement
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
POST /fnf/{id}/recalculate

Recalculate a settlement

Rebuilds a draft from current data - use it after correcting the leave balance, the exit date or the final month's attendance.

Path parameters

id required
string
INDPayroll id of the resource.

Body application/json · optional

employee_id required
string
—
settlement_date
string (date)
—
include_leave_encashment
boolean
—
leave_balance_days
number
Send when you hold leave balances yourself. Otherwise the engine reads its own.
include_gratuity
boolean
—
notice_recovery_days
number
—
additional_earnings
PayslipLine[]
—
additional_deductions
PayslipLine[]
—
remarks
string
—

Responses

  • 200 Recalculated. FnfSettlement
  • 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
POST /fnf/{id}/approve

Approve a settlement

Freezes the figures. After approval only a cancellation can change them.

Path parameters

id required
string
INDPayroll id of the resource.

Body application/json · optional

remarks
string
—

Responses

  • 200 Approved. FnfSettlement
  • 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
POST /fnf/{id}/cancel

Cancel a settlement

Refused once the settlement has been paid.

Path parameters

id required
string
INDPayroll id of the resource.

Body application/json · required

reason required
string
—

Responses

  • 200 Cancelled. FnfSettlement
  • 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/fnf/{id}/cancel \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Employee withdrew the resignation."
}'
POST /fnf/{id}/mark-paid

Mark a settlement paid

Records the payment and fires fnf.settled.

Path parameters

id required
string
INDPayroll id of the resource.

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

paid_on required
string (date)
—
payment_method_id
integer
—
reference
string
—

Responses

  • 200 Paid. FnfSettlement
  • 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/fnf/{id}/mark-paid \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "paid_on": "2026-10-07",
  "payment_method_id": 2,
  "reference": "NEFT-20261007-0042"
}'
GET /gratuity

Gratuity across the organization

Every employee with their years of service, eligibility and accrued amount as on a date - the calculator and the liability report in one.

Query parameters

organization_id
integer
Organization to act on. Required when the API key can reach more than one organization; optional - and defaulted - when it can reach exactly one.
as_on
string (date)
Date to project to. Defaults to today.
eligible_only
boolean
Only employees who have completed five years of continuous service.
page
integer
1-based page number.
per_page
integer
Items per page. The engine caps this at 200.

Responses

  • 200 Projections. object
  • 401 The key is missing, unknown, or the HMAC signature did not verify. ErrorResponse
GET /gratuity/{employeeId}

One employee's gratuity projection

The statutory formula is returned alongside the amount, so the figure can be checked by hand: 15/26 of the last drawn basic plus DA, per completed year of service, capped at the statutory limit.

Path parameters

employeeId required
string
Employee id, or ext: + your own identifier.

Query parameters

as_on
string (date)
—

Responses

  • 200 The projection. GratuityProjection
  • 404 No such resource, or it belongs to an organization this key cannot reach. ErrorResponse
Request
curl -X GET https://api.indpayroll.com/v1/gratuity/{employeeId} \
  -H "Authorization: Bearer $INDP_API_KEY"
Response · 200
{
  "employee_id": "ext:emp-1044",
  "employee_name": "Sanjay Patnaik",
  "date_of_joining": "2020-06-15",
  "as_on": "2026-09-18",
  "years_of_service": 6.3,
  "eligible": true,
  "last_drawn_basic_da": 33000,
  "formula": "(15 / 26) x last drawn basic + DA x completed years",
  "amount": 114231,
  "capped_at_statutory_limit": false
}
POST /gratuity/export

Export the gratuity liability

Builds the same projection as a spreadsheet, for the auditors or the actuary.

Body application/json · required

organization_id
integer
—
as_on
string (date)
—
eligible_only
boolean
—
format
enum: xlsx, csv, pdf
—

Responses

  • 200 The requested file. The content type follows format - text/csv, text/plain, application/pdf, or the Office XML type for xlsx.
  • 202 Accepted. The work runs asynchronously; poll the returned resource. AsyncAck
  • 400 The request was malformed or failed validation. ErrorResponse
Request
curl -X POST https://api.indpayroll.com/v1/gratuity/export \
  -H "Authorization: Bearer $INDP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": 42,
  "as_on": "2027-03-31",
  "eligible_only": false,
  "format": "xlsx"
}'
Previous
Statutory
Next
Reports