Social Insurance Benefits API
Compute Vietnamese unemployment benefit, one-time social-insurance withdrawal with 2026 coefficients, severance, job-loss and maternity benefits.
One endpoint, five calculations chosen with type. unemployment: 60% of the average contribution wage of the last 6 months, capped at 5 × the regional minimum wage, for 3 months (12 to under 36 months of contributions) plus one month per further 12 months, up to 12 (Luật Việc làm 74/2025/QH15). The region comes from region or from a ward name.
lump_sum (BHXH một lần): send the contribution periods with their wages; each month is adjusted with the coefficients for 2026 (Công văn 340/BHXH-CSXH), then 1.5 months of average wage per year before 2014 and 2 months per year from 2014, with the official rounding of odd months (Luật BHXH 41/2024/QH15 Điều 70). The answer also says whether withdrawal is possible under the post-1/7/2025 rules.
severance and job_loss follow Bộ luật Lao động 2019 Điều 46–47 (time covered by unemployment insurance excluded), and maternity returns the lump sum (2 × the reference level, 2,530,000 đ from 1/7/2026), the mother's 6-month leave pay and the father's leave days.
Parameters
| Name | In | Type | Required | Default | |
|---|---|---|---|---|---|
type | query|body | string | yes | unemployment, lump_sum, severance, job_loss or maternity. | |
salary | query|body | number | no | Average monthly wage (contribution wage, or contract wage for severance). | |
salaries | body | array | no | Unemployment: the last 6 monthly contribution wages. | |
contribution_months | query|body | number | no | Unemployment: months of unemployment-insurance contributions. | |
region | query|body | string | no | I | Unemployment: wage region I–IV (or ward + province). |
last_month | query|body | string | no | Unemployment: last contribution month (YYYY-MM). | |
periods | body | array | no | Lump sum: [{"from":"2015-01","to":"2020-12","salary":8000000}]. | |
start_date | query|body | string | no | Severance: first working day. | |
end_date | query|body | string | no | Severance: contract end date. | |
unemployment_insurance_months | query|body | number | no | Severance: months covered by unemployment insurance (excluded). | |
birth_date | query|body | string | no | Maternity: date of birth (reference level of that month). | |
children | query|body | number | no | 1 | Maternity: number of children born. |
Example
curl -X POST "https://apibox.io.vn/v1/vn-insurance-benefits" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"unemployment","salary":10000000,"contribution_months":40,"region":"I"}'const res = await fetch('https://apibox.io.vn/v1/vn-insurance-benefits', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"type": "unemployment",
"salary": 10000000,
"contribution_months": 40,
"region": "I"
}),
});
const data = await res.json();
console.log(data);import requests
res = requests.post(
"https://apibox.io.vn/v1/vn-insurance-benefits",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"type": "unemployment", "salary": 10000000, "contribution_months": 40, "region": "I"},
timeout=30,
)
print(res.json())<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-insurance-benefits');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => '{"type":"unemployment","salary":10000000,"contribution_months":40,"region":"I"}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));Response
{
"type": "unemployment",
"average_salary": 10000000,
"contribution_months": 40,
"eligible": true,
"monthly_benefit": 6000000,
"capped": false,
"cap": {
"amount": 26550000,
"rule": "5 × regional minimum wage of the last contribution month",
"region": "I",
"region_from": "region",
"min_wage": 5310000,
"decree": "293/2025/NĐ-CP"
},
"benefit_months": 4,
"total": 24000000,
"reserved_months": 4,
"payment_start": "from the 11th working day after a complete application",
"legal": "Luật Việc làm 74/2025/QH15 Điều 38, 39 (from 1/1/2026): 60% of the average contribution wage of the last 6 months, max 5 × regional minimum wage; 12 to under 36 months -> 3 months, +1 month per further 12 months, max 12 months.",
"reviewed": "2026-11-11"
}Use cases
- Add an unemployment benefit calculator to a job board
- Estimate a one-time social-insurance withdrawal in a finance app
- Compute severance pay in HR and payroll software
- Show maternity benefits in an employee self-service portal
FAQ
Which coefficients are used for BHXH một lần?
The 2026 table of Công văn 340/BHXH-CSXH (5.81 before 1995 down to 1.00 for 2025–2026), applied to every month of each period.
Can everyone still withdraw BHXH một lần?
People who contributed before 1/7/2025 with under 20 years may withdraw after 12 months out of the system; others only in the special cases of Điều 70. The answer states which applies.
How is the unemployment cap found?
5 × the regional minimum wage of the last contribution month (5,310,000 đ in region I in 2026), from region or a ward looked up in the NĐ 293/2025 list.
Related APIs
JSON Validator
Check JSON syntax with exact line and column of errors, and validate data against a JSON Schema (draft 4, 7, 2019-09 or 2020-12).
{ }JSON Formatter
Pretty print JSON with 0-8 spaces or tabs, minify it, or sort object keys recursively. Syntax errors are reported with line and column.
CSVCSV to JSON
Convert CSV into an array of JSON objects using the header row, with delimiter auto-detection, number and boolean typing, and row-level errors.