Salary - API Reference

Audience: Frontend engineers, mobile/panel engineers, backend engineers, QA, and the accounting integration's developers (for the read-only vocabulary the accounting API mirrors). Scope: Admin (/api/salary/**) and mobile portal (/api/mobile/staff/{salary,payslips,assets}) routes owned by the salary management module. The accounting-facing /api/integration/** surface is documented alongside the integration module.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. Admin Routes — Catalog and Structures

5. Admin Routes — Assignments, Employees, One-Time Items, Bulk

6. Admin Routes — Periods, Payslips, Runs

7. Admin Routes — Payments, Reports, Settings

8. Mobile/Portal Routes

SalaryPortalAssignmentDto (GET staff/salary, or null when the caller has no effective assignment): effectiveFrom (SalaryDateDto), structureName (nullable), designationName/departmentName (nullable — the caller's own designation and department label, read straight off their staff row rather than any live lookup; a designation or department that is itself deactivated still returns its name), lines (SalaryPortalLineDto[]: code, name, kind, monthlyPaisa), totals (SalaryPortalTotalsDto: basicPaisa/allowancesPaisa/grossPaisa), scheduled (nullable SalaryPortalScheduledDto: effectiveFrom — a pending future change, when one exists).

SalaryPortalPayslipSummaryDto (GET staff/payslips list items): identity/period fields, grossEarningsPaisa/leaveDeductionPaisa/totalDeductionsPaisa/netPayPaisa, paymentStatus, paidOn (nullable). SalaryPortalPayslipDetailDto (GET staff/payslips/:id) extends it with employerContributionsPaisa (the employer's SSF share paid on top of gross — not part of netPayPaisa, which is computed from earning and deduction lines only), the day/divisor and leave breakdown (periodDays/employedDays/divisorDays/leaveDays/leavePaidDays/leaveUnpaidDays/leaveDeductionDays), lines (SalaryPortalPayslipLineDto[]: code/name/kind/amountPaisa — kind is earning, deduction, or employer_contribution), leaves (SalaryPortalPayslipLeaveDto[]: leaveTypeLabel/unpaidDaysInPeriod/deductionDays), and bank (nullable SalaryPortalPayslipBankDto: bankName, accountLastFour — the last four digits only). Never an override reason, an event, or an accounting field — the portal shows what was paid, not why.

9. Accepted Change Types

POST /api/salary/employees/:staffId/assignments accepts a changeType from SALARY_CLIENT_CHANGE_TYPES: initial, revision, increment, decrement, promotion, demotion, correction, stop, resume. initial is the only type accepted for a staff member with no current effective assignment; every other type requires one (SALARY_ASSIGNMENT_NO_CURRENT otherwise). Every type except initial requires a reason string. A promotion additionally accepts a designationId identifying the new designation.

10. Error Codes

error-codes.ts declares 101 SALARY_* codes covering assignment lifecycle (SALARY_ASSIGNMENT_*), catalogue (SALARY_CATEGORY_*, SALARY_COMPONENT_*), structures (SALARY_STRUCTURE_*), periods (SALARY_PERIOD_*), payslips (SALARY_PAYSLIP_*), payments (SALARY_PAYMENT_*), runs (SALARY_RUN_*), inbound sync (SALARY_INBOUND_*), bulk (SALARY_BULK_*), and tax slabs (SALARY_TAX_SLABS_*). The ones worth calling out specifically:

11. Integration Notes

The accounting application never calls /api/salary/** directly except the inbound events read (GET /api/salary/inbound-events, gated by SalarySync_READ for an admin, or the client's own scope for the accounting application via integration). It reads the salary change feed at the grain its scopes allow (payroll:read for the vocabulary and period/payslip lifecycle, payroll:identity:read for PAN/SSF/CIT numbers, payroll:bank:read for the bank snapshot on an approved payslip) and writes payment state through payroll:write. See the integration module's docs for the client-facing request/response shapes, INTEGRATION_SCOPE_GRANT_FORBIDDEN, and INTEGRATION_EVENT_SCOPE.

12. DTOs — Catalog, Structures, Designations

CreateSalaryCategoryDto: name (string, required, ≤80) · kind (required, SalaryComponentKind: earning/deduction/employer_contribution) · description (optional, nullable, ≤500) · sortOrder (optional int, ≥0, default 0). UpdateSalaryCategoryDto: same minus kind (immutable) minus name/sortOrder/description becoming optional, plus status (optional, SalaryCatalogStatus: active/inactive/archived) and version (required int ≥1 — a stale value is 409 SALARY_VERSION_CONFLICT). SalaryCategoryDto (response) adds publicId, isSystem, componentCount, createdAt/updatedAt.

CreateSalaryComponentDto: code (required, ^[A-Z][A-Z0-9_]{1,29}$) · name (required, ≤80) · categoryId (required, uuid) · frequency (required, SalaryFrequency: monthly/one_time) · defaultValueType (optional nullable, SalaryValueType: flat/percent) · defaultAmountPaisa (optional nullable int, 0-9,999,999,999) · defaultPercentBp (optional nullable int, 0-10000) · defaultPercentBase (optional nullable, SalaryPercentBase: basic/gross_earnings) · taxable/prorated/leaveDeductible (all required booleans) · description (optional nullable, ≤500) · sortOrder (optional int ≥0). UpdateSalaryComponentDto: every field optional (code/frequency immutable, absent entirely), plus required version. SalaryComponentDto (response) adds publicId, category (SalaryCategoryRefDto: publicId/name/kind), role (SalaryComponentRole), isSystem, usage ({structures, assignments, oneTimeItems} counts — non-zero usage is what SALARY_COMPONENT_IN_USE protects), createdAt/updatedAt.

CreateSalaryStructureDto: name (required, ≤150) · description (optional nullable, ≤2000) · effectiveFrom (required, ISO date string) · designationIds (optional array of uuid). UpdateSalaryStructureDto: name/description/effectiveFrom all optional, plus required version. PutSalaryStructureLinesDto: lines (required array, 1-40, each SalaryStructureLineInputDto: componentId uuid required, valueType required enum, amountPaisa/percentBp/percentBase per the value-shape rule, sortOrder optional) plus version. PutSalaryStructureDesignationsDto: designationIds (required array of uuid) plus version. ReviseSalaryStructureDto: effectiveFrom (required date, must be future), changeNote (required, 3-2000), lines (same shape as above, 1-40), version. CopySalaryStructureDto: name only (required, ≤150) — copies as a fresh draft, no version needed since nothing existing is touched. Every structure-lifecycle action (activate/deactivate/reactivate/archive) takes only { version } (SalaryStructureVersionOnlyDto).

Structure response DTOs nest SalaryStructureLineDto (adds the resolved component ref and monthlyPaisa), SalaryStructureVersionSummaryDto (versionNo, effectiveFrom as SalaryDateDto, changeNote, createdByName), and SalaryStructureMonthlyDto (basicPaisa/earningsPaisa/deductionsPaisa — the structure's own monthly total, not any one employee's).

SalaryDesignationDto (GET salary/designations): publicId, name, department ({publicId, name}), isTeaching, defaultStructure (nullable — {publicId, name, currentVersionNo, monthly: {basicPaisa, earningsPaisa}}), applicableStructures (array of {publicId, name, status}), staffCount, salariedCount, onDefaultCount. PutSalaryDesignationDefaultDto: structureId (nullable uuid — null clears the default; setting one requires the structure already declare that designation applicable, or the write is refused by the composite FK, translated to a validation error).

13. DTOs — Assignments, Employees, One-Time Items, Bulk

AssignmentEffectiveDateDto (nested in every change): mode (required, one of immediate/ad_date/bs_date/bs_month/plus_days/next_period) plus exactly the field its mode needs — date (AD, ad_date), dateBs (BS, bs_date), bsYear+bsMonth (bs_month), days (1-366, plus_days); immediate/next_period take no extra field. See the feature doc §5 for what each mode resolves to.

AssignmentChangeDto (the body of both preview and, extended, commit): changeType (required, SALARY_CLIENT_CHANGE_TYPES: initial/revision/increment/decrement/promotion/demotion/correction/stop/resume) · effectiveDate (required, above) · structureId (optional nullable uuid) · lines (optional array of AssignmentLineInputDto: componentId uuid required, valueType required, amountPaisa/percentBp/percentBase optional nullable per value-shape) · designationId (optional nullable uuid — required when changeType is promotion/demotion; a missing, unknown, or inactive designation both answer SALARY_PROMOTION_DESIGNATION_INVALID) · taxAssessment (optional, single/couple) · ssfEnrolled (optional bool) · reason (optional, 3-500 — required in practice for every changeType except initial, enforced server-side, not by the DTO) · replaceScheduled (optional bool — supersede an already-pending scheduled change instead of refusing with SALARY_ASSIGNMENT_SCHEDULED_EXISTS).

CommitAssignmentChangeDto extends the above with effectiveFrom (required, the exact AD date preview returned — echoed back, not recomputed, so a client cannot silently commit against a different date than what it previewed) and basis (required AssignmentBasisDto: currentAssignmentId/currentVersion/scheduledAssignmentId/scheduledVersion, all nullable — the exact snapshot preview returned). Commit re-validates from scratch: it re-runs the same evaluateChange preview uses (self-dealing, permission, designation, locked-period, and every other blocking check) under the period+staff locks, so nothing preview missed can slip through a race; separately, it compares the request's basis against what it just re-read and throws SALARY_VERSION_CONFLICT on any mismatch — a concurrent change between preview and commit is caught even though the blocking-check re-run alone might not catch it (the assignment could still be structurally valid, just not the one the client's screen was showing).

CreateSalaryOneTimeItemDto: staffId (required uuid) · componentId (required uuid, must be a one_time-frequency component) · bsYear (required, 2000-2090) · bsMonth (required, 1-12) · valueType (required) · amountPaisa/percentBp (optional nullable int, ≥1 — per the schema's salary_one_time_items_amount_bounded, percentBp up to 100,000, i.e. 1000%) · reason (required, 3-500) · idempotencyKey (optional uuid — paired with the caller's own user id server-side for replay safety).

SalaryBulkScopeDto (who the action applies to — every field optional, combined with AND where more than one is given): staffIds (≤2000 uuids) · departmentIds/designationIds (int arrays) · structureId (uuid — filters to staff currently on this structure) · employmentStatuses (string array). SalaryBulkActionDto: kind (required, apply_structure/adjust_salary/one_time_item/profile_import/reschedule), plus per-kind fields: apply_structure needs structureId + optional includeOverrides; adjust_salary needs mode (percent/flat) and either basisPoints or amountPaisa, plus optional componentId (default BASIC); one_time_item needs valueType, percentBp or (implicitly) a flat amount, bsYear, bsMonth, reason; reschedule needs assignmentIds (≤2000 uuids); every action-needing-a-date kind (apply_structure/adjust_salary/reschedule) also needs effectiveDate. Every kind accepts an optional reason (3–500 characters); the run records it on every assignment row it writes and on every scheduled change it cancels, and falls back to "Applied by a bulk salary run." only when the operator gave none. BulkPreviewDto: action + scope (required, nested) plus page/size (default 1/20, size capped 100 — preview is paginated, unlike the run itself). BulkCommitDto extends it with staffIds (required — the exact eligible set the client confirmed, checked against a fresh eligibility re-evaluation; any id no longer eligible refuses the whole commit) and requestKey (required uuid, per-requester idempotency for the whole bulk operation).

BulkPreviewResultDto: resolvedEffectiveFrom (nullable SalaryDateDto — the server-resolved date, or null when the action kind needs none) · counts (a free-form {total, eligible, <reason>: n, ...} record — one key per distinct ineligibility reason seen on the page) · rows (the current page, each SalaryBulkRowDto: staffId, name, employeeCode, eligible, reasons (string array — values from SALARY_BULK_INELIGIBLE_REASONS: already_on_structure/individual_override/missing_profile_salary/inactive_employment/pending_scheduled_change/date_before_current/date_in_locked_period/no_current_assignment/self), current (nullable {basicPaisa, grossPaisa}), proposed (nullable, same shape)) · eligibleStaffIds (the complete eligible set across every page, not just the one shown — what a client passes to BulkCommitDto.staffIds).

proposed is computed only for apply_structure and adjust_salary, only for rows that are eligible AND already have a current assignment, and only for the page actually being returned (not the whole eligible set, to bound the work a single preview call does). For apply_structure it is the target structure version's own monthly totals, unconditionally the same for every eligible row. For adjust_salary it re-reads that staff member's current lines, applies the delta (a flat amount, or a percentage of the current value of the named component — default BASIC) to that one component only, floors at zero, and totals the result; a row whose target component has no current flat line (e.g. it is presently a percentage line) gets proposed: null even if otherwise eligible. one_time_item, profile_import, and reschedule always return proposed: null for every row — those actions do not change the recurring monthly total in a way this preview computes. salary/bulk/salary-bulk-proposal.util.ts is the shared arithmetic both preview and the run handler call, so the number shown in preview is guaranteed to be the number the run would actually write.

14. DTOs — Periods, Payslips, Runs

CreateSalaryPeriodDto: bsYear (required, 2000-2090) · bsMonth (required, 1-12) · notes (optional, 1-500). PrepareSalaryPeriodDto is just { version }. CancelSalaryPeriodDto: { version, reason } (reason required, 3-500). Approve/reopen/send take { version } alone (not separately listed — same SalaryVersionDto shape).

SalaryPeriodDto (response) carries, beyond the identity fields: label/bsYear/bsMonth/fiscalYearBs/fiscalMonth, startDate/endDate (SalaryDateDto), calendarDays, status, settings (nullable SalaryPeriodSettingsDto — paymentAuthority/requireDistinctApprover/leaveDivisor/ssfEnabled/tdsEnabled, null until prepared), counts (SalaryPeriodCountsDto: payslips/draft/approved/cancelled/blocked/paid), totals (SalaryPeriodTotalsDto: the five payisa sums), activeRun (nullable SalaryRunSummaryDto), sync (SalaryPeriodSyncDto: lastInboundAt, varianceCount, externallyUpdated, manuallyUpdated), actorIsMaker (nullable bool — non-null only when the period requires a distinct approver, tells the caller's own UI whether to grey out Approve), the five lifecycle timestamp/actor pairs, reopenedCount, notes, allowedActions (string array — a UI hint from state, never a permission check), version. SalaryPeriodActionResultDto wraps {period, runId} — runId is non-null only when the action ran in the background.

SetSalaryOverrideDto: componentId (required uuid, must be deduction/employer_contribution) · amountPaisa (required int ≥0) · reason (required, 3-500) · version. AcknowledgeSalaryFlagDto: flag (required, must be in SALARY_ACKNOWLEDGEABLE_FLAGS — today only employment_inactive_with_pay) · reason (required, 3-500) · version. CreateSalaryExclusionDto: staffId (required uuid) · reason (required, 3-500) — no version (exclusions are their own row, not an edit of the payslip).

SalaryPayslipSummaryDto: identity/period fields, status (draft/approved/cancelled), revision, the five money totals, paymentStatus, paidAmountPaisa, flags/blockingFlags (string arrays — blockingFlags is flags minus whatever is in acknowledgedFlags), isSelf (true when the payslip is the caller's own — every mutating route on it then refuses regardless of permission), allowedActions, version. SalaryPayslipDetailDto adds the day/divisor breakdown, taxAssessment/ssfEnrolled, the five tax figures, acknowledgedFlags, lines (SalaryPayslipLineDto — component ref, origin (SalaryLineOrigin), value shape, grossPaisa/leaveDeductionPaisa/computedAmountPaisa/amountPaisa, overridden/overrideReason, sourcePayslipId for a leave-adjustment line), segments, leaves (SalaryPayslipLeaveDto), events (SalaryPayslipEventDto), and bank (SalaryPayslipBankDto, optional — the key is present on the response only for a caller holding StaffSalary_READ; a caller without that permission never sees the key at all, regardless of the payslip's approval state).

SalaryRunDto: kind/status/periodId (nullable), the four item counters, requestedBy (nullable ref), startedAt/finishedAt/lastProgressAt, errorCode/errorMessage, allowedActions (retry/cancel by state), createdAt. SalaryRunItemDto: staffId/employeeName/employeeCode, status (SalaryRunItemStatus), outcome (nullable, e.g. "prepared"), attempts, errorCode/errorMessage, resultId (nullable — the public id of whatever row the item created, e.g. a new assignment or payslip).

15. DTOs — Payments, Reports, Settings

RecordSalaryPaymentDto: status (required, SalaryPaymentStatus) · paidAmountPaisa (optional int ≥0 — defaults to net pay for paid, required for partially_paid) · paidOn (optional AD date — defaults to today for paid/partially_paid) · paymentReference (optional, 1-128) · note (required, 3-500) · requestKey (required uuid — per-actor idempotency: the same key with the same body from the same actor replays the stored result; a different body or a different actor reusing the key is refused) · version.

SalaryDashboardDto (GET salary/dashboard): employees ({assigned, unassigned, stopped}), scheduledChanges ({pending, failedActivation}), currentPeriod (nullable {id, periodLabel, status}), pendingLeaveAdjustments (array of {staffId, employeeName, periodLabel}), exceptions (array of {staffId, employeeName, reason}, reason one of missing_bank_details/missing_pan/stopped_with_pending_adjustment).

ListSalaryHistoryQueryDto (GET salary/history): staffId (optional uuid — omit for every staff member), from/to (optional date strings), kind (optional, assignment/one_time_item). SalaryHistoryItemDto: kind, id, staffId, employeeName, changeType (nullable — set only for an assignment row), componentName (nullable — set only for a one_time_item row), effectiveFromOrBsMonth (a single overloaded field: an AD date string for an assignment, a BS-month label for a one-time item — read kind first to know which), status, reason (nullable), createdBy, createdAt.

SalaryPayslipsExportQueryDto (GET salary/exports/payslips): periodId (required uuid) — the CSV always exports one period's payslips at a time; there is no cross-period export.

SalarySettingsDto / PatchSalarySettingsDto: the patchable subset is deliberately narrow — roundingMode, roundingUnitPaisa, leaveDivisor — everything else (SSF, TDS, retirement cap, payment authority, distinct approver, citizenship sharing) is on the separate PatchSalaryFinancialSettingsDto behind SalaryFinancialSettings_UPDATE: paymentAuthority, payrollClientId (nullable uuid), requireDistinctApprover (bool), ssfEnabled (bool), ssfEmployeeRateBp/ssfEmployerRateBp (0-10000), employerSsfTaxable (bool), tdsEnabled (bool), retirementCapPaisa (0-999,999,999,999), retirementCapNumerator/retirementCapDenominator (1-100 each), shareCitizenshipWithAccounting (bool) — every field optional except version.

PutSalaryNotificationSettingDto: isEnabled (required bool), audiences (required array, subset of SALARY_NOTIFICATION_AUDIENCES), channels (required array, subset of SALARY_NOTIFICATION_CHANNELS), version. The response additionally carries allowedAudiences/allowedChannels — the matrix's own ceiling for that event key, so the UI can grey out an audience/channel the event will never actually notify even if selected.

PutSalaryTaxSlabsBodyDto (PUT salary/tax-slabs/:fiscalYearBs/:assessment): slabs (required array, 1-20, each {upperBoundPaisa (nullable, the open top slab), rateBp (0-10000), waivedForSsf (bool, legal only on seq 1)} — the array's own order becomes seq 1..n; the whole group replaces what existed, and the deferred trigger salary_tax_slabs_check refuses at commit if the replacement is not contiguous/increasing/single-open-top). CopySalaryTaxSlabsDto: fromFiscalYearBs/toFiscalYearBs (both required, 2000-2089) — copies a whole group forward.

16. Error Codes by Route Group

Every route group's mutating actions can also return the shared codes: VALIDATION_FAILED (a DTO field fails its decorator), PERMISSION_INSUFFICIENT (the guard's own message when @Permissions() is not held), and — for anything read by public id — the group's own _NOT_FOUND. This table lists what is specific to each group, and what a consumer should do about it.