Leave Balances API

Summary

Three Direct operations list, save/upsert, and delete Leave balances. No employee/type query parameters or accrual endpoint exists.

Audience

Frontend/backend developers, QA, Leave/Payroll integrators, and support.

Reference Content

Maturity: Direct / Transitional. Authentication: expected. Authorization: administrative balance scope Requires confirmation in extracted service. Tenant: required for save; queries/deletes use tenant-filtered persistence.

Operation	Method/route	Request	Response/status	Behavior
List balances	GET /leave/balances	None	200 LeaveBalanceDto[]	All visible balances ordered by user/type; no side effects.
Save balance	POST /leave/balances	SaveLeaveBalanceRequest	200 LeaveBalanceDto; 400 invalid	Upserts by user/type/year; normalizes opening/accrued/used non-negative, permits signed adjustment; audit/timeline and balance event.
Delete balance	DELETE /leave/balances/{id}	Route id:int	200 plain success; 404 missing	Removes visible balance and audits; no domain event is raised by delete.

Save fields: userId, leaveType, year, openingBalance, accrued, used, adjusted. Response adds id, carriedForward, encashed, and available.

{"userId":900101,"leaveType":"Configured Leave","year":2032,"openingBalance":10,"accrued":0,"used":1,"adjusted":0}

A success response returns the complete balance DTO. Invalid user/type returns 400; missing delete returns 404. Current request approval does not enforce available balance, and no accrual/carry-forward/encashment API is exposed. Compatibility balance operations are separate.

Source References

• microservices/src/leave-service/Api/LeaveEndpoints.cs
• microservices/src/leave-service/Application/Dtos.cs
• microservices/src/leave-service/Application/LeaveWorkflows.cs
• microservices/src/leave-service/Domain/Leave/LeaveBalance.cs

Related Articles

• Leave API
• Authentication and context
• Response and error model

See Also

• Leave technical documentation
• Leave business documentation

Keywords

• Leave API
• Leave Balances API
• Endpoint reference

Revision Information

• Status: Draft
• Last reviewed: 2026-07-15
• Review cycle: Quarterly