Annual leave calculator API

Annual leave days under Vietnam’s Labour Code: 12/14/16 days, +1 per 5 years, pro-rated months, and the payment for untaken leave when a contract ends.

GETPOSThttps://apibox.io.vn/v1/vn-annual-leave

Data & JSON▶ Try it online

Send the start_date with the employer, the work_type (normal 12 days; heavy 14 days for minors, disabled workers and heavy / toxic / dangerous work; very_heavy 16 days) and the year, or an end_date when the contract ends. The API adds 1 day for every 5 full years of service (Bộ luật Lao động 2019 Điều 114) and pro-rates the year when fewer than 12 months are worked: (annual days + seniority days) / 12 × months, where a part month counts when at least half of it is worked (Nghị định 145/2020/NĐ-CP Điều 66).

With days_taken and monthly_salary it returns the days left and the payment for untaken leave on termination: contract salary of the month before termination ÷ normal working days × days (Điều 67.3), and whether that pay is PIT-exempt (from tax year 2026, Nghị định 253/2026/NĐ-CP).

The decree sets no rounding rule for pro-rated days: the exact value and a half-up rounded value are both returned. Periods that count as work (probation when kept on, sick leave up to 2 months a year, unpaid leave up to 1 month…) are listed in Nghị định 145/2020 Điều 65; send non_counted_days to remove other absences.

Parameters

Name	In	Type	Required	Default
`start_date`	query\|body	string	yes		First day of work with this employer.
`end_date`	query\|body	string	no		Termination date (for the untaken-leave payment).
`year`	query\|body	number	no		Year to compute (default the end_date year or this year).
`work_type`	query\|body	string	no	`normal`	`normal`, `heavy` or `very_heavy`.
`days_taken`	query\|body	number	no		Leave days already taken in the year.
`carried_over_days`	query\|body	number	no		Days carried over from earlier years.
`monthly_salary`	query\|body	number	no		Contract salary of the month before termination.
`working_days_per_month`	query\|body	number	no	`26`	Normal working days of that month.
`months_worked`	query\|body	number	no		Override the months counted in the year.
`non_counted_days`	query\|body	number	no		Days not counted as work for seniority (e.g. long unpaid leave).

Example

curl "https://apibox.io.vn/v1/vn-annual-leave?start_date=2020-01-01&end_date=2026-06-15&days_taken=2&monthly_salary=13000000" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-annual-leave?start_date=2020-01-01&end_date=2026-06-15&days_taken=2&monthly_salary=13000000', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/vn-annual-leave?start_date=2020-01-01&end_date=2026-06-15&days_taken=2&monthly_salary=13000000",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-annual-leave?start_date=2020-01-01&end_date=2026-06-15&days_taken=2&monthly_salary=13000000');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "year": 2026,
  "work_type": "normal",
  "work_type_vi": "Làm công việc trong điều kiện bình thường",
  "work_type_en": "Normal working conditions",
  "start_date": "2020-01-01",
  "end_date": "2026-06-15",
  "service_years": 6.46,
  "full_years": 6,
  "base_days": 12,
  "seniority_days": 1,
  "entitlement_full_year": 13,
  "months_worked": 6,
  "partial_months": [
    {
      "month": 6,
      "counted": true,
      "days_in_service": 15
    }
  ],
  "days": 6.5,
  "days_rounded": 7,
  "days_taken": 2,
  "carried_over_days": 0,
  "days_remaining": 5,
  "untaken_leave_payment": {
    "applies": true,
    "monthly_salary": 13000000,
    "working_days_per_month": 26,
    "daily_wage": 500000,
    "days": 5,
    "amount": 2500000,
    "pit_exempt": true,
    "basis": "Contract salary of the month before termination ÷ normal working days (NĐ 145/2020 Điều 67.3)"
  },
  "legal": [
    "Bộ luật Lao động 45/2019/QH14 Điều 113, 114",
    "Nghị định 145/2020/NĐ-CP Điều 65, 66, 67"
  ],
  "reviewed": "2026-11-11"
}

Use cases

Compute leave balances in HR software
Pay untaken leave in the final settlement
Show new hires their pro-rated leave
Check seniority days for long-serving staff

FAQ

How many days for someone who joined in April?

For normal work: 12 / 12 × 9 months = 9 days in that year; from the 13th month the full 12 days apply.

Is untaken leave paid every year?

The law requires payment when the contract ends or the job is lost. While employed, carry-over or payment follows the company rules or agreement.

Is the payment taxed?

From tax year 2026, pay for untaken leave under the law is PIT-exempt (Nghị định 253/2026/NĐ-CP); before 2026 it was taxable salary.

Related APIs

{✓}

Annual leave calculator API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON