Voluntary BHXH & Household BHYT (VN) API

Monthly, 3/6/12-month or multi-year voluntary BHXH contributions with state and provincial support, and household BHYT for each member.

GETPOSThttps://apibox.io.vn/v1/vn-voluntary-insurance

Data & JSON▶ Try it online

Voluntary social insurance (BHXH tự nguyện, Luật BHXH 2024 and NĐ 159/2025/NĐ-CP): 22 % of the chosen income, from the rural poverty line (1,500,000 VND in 2026) to 20 × the reference level (50,600,000 VND from 1/7/2026). State support is 50 % (poor households, island communes), 40 % (near-poor), 30 % (ethnic minorities) or 20 % (others) of 22 % × the poverty line, for at most 10 years; the API adds the provincial top-up where we have verified it (coverage: Hà Nội, TP.HCM, Hải Phòng, Đà Nẵng) and flags unverified sources. Methods: monthly, 3, 6, 12 months, advance for 2–5 years ahead (discounted with the fund’s monthly investment rate) and missing for the missing months at retirement age.

Household health insurance (BHYT hộ gia đình, NĐ 188/2025/NĐ-CP): 4.5 % of the base salary for the first member, 70 %, 60 %, 50 % and 40 % of that for the 2nd, 3rd, 4th and 5th+ members, paid for 3, 6 or 12 months, with provincial support for some cases (e.g. people aged 65–74 in TP.HCM). type=both returns both. Rates follow the date (date, default today).

Parameters

Name	In	Type	Required	Default
`type`	query	string	no	`bhxh`	bhxh, bhyt or both.
`income`	query	number	no		BHXH: chosen monthly income (default the minimum).
`group`	query	string	no	`other`	poor, near_poor, ethnic_minority, island, veteran or other.
`method`	query	string	no	`monthly`	monthly, 3, 6, 12, advance (with years 2–5) or missing (with months 1–60).
`years`	query	number	no		Years paid ahead (method=advance).
`months`	query	number	no		BHYT: 3, 6 or 12; BHXH missing: months 1–60.
`members`	query	number	no	`1`	BHYT: number of members, or an array [{ name, age, case }] (POST).
`province`	query	string	no		Province name or code for local support.
`supported_months_used`	query	number	no		Months of state support already received (10-year cap).
`rate`	query	number	no		Monthly fund rate in % for advance / missing payments.
`date`	query	string	no		Payment date (default today).

Example

curl "https://apibox.io.vn/v1/vn-voluntary-insurance?type=both&income=2000000&group=near_poor&method=12&province=H%E1%BA%A3i%20Ph%C3%B2ng&members=3&months=12&date=2026-11-11" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-voluntary-insurance?type=both&income=2000000&group=near_poor&method=12&province=H%E1%BA%A3i%20Ph%C3%B2ng&members=3&months=12&date=2026-11-11', {
  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-voluntary-insurance?type=both&income=2000000&group=near_poor&method=12&province=H%E1%BA%A3i%20Ph%C3%B2ng&members=3&months=12&date=2026-11-11",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-voluntary-insurance?type=both&income=2000000&group=near_poor&method=12&province=H%E1%BA%A3i%20Ph%C3%B2ng&members=3&months=12&date=2026-11-11');
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

{
  "province": {
    "code": "31",
    "name": "Hải Phòng"
  },
  "bhxh": {
    "type": "bhxh_voluntary",
    "date": "2026-11-11",
    "group": "near_poor",
    "income": 2000000,
    "rate": 0.22,
    "method": "12_months",
    "months": 12,
    "monthly_contribution": 440000,
    "gross_amount": 5280000,
    "support": {
      "national_percent": 0.4,
      "local_percent": 0.25,
      "total_percent": 0.65,
      "base": 330000,
      "months_supported": 12,
      "monthly_national": 132000,
      "monthly_local": 82500,
      "national": 1584000,
      "local": 990000,
      "total": 2574000,
      "local_ref": "NQ 56/2025/NQ-HĐND TP Hải Phòng (11/12/2025), luatvietnam.vn"
    },
    "you_pay": 2706000,
    "limits": {
      "income_min": 1500000,
      "income_min_ref": "NĐ 07/2021/NĐ-CP (chuẩn nghèo nông thôn, kéo dài đến 31/12/2026)",
      "income_max": 50600000,
      "reference_level": 2530000,
      "reference_level_ref": "Nghị định 161/2026/NĐ-CP"
    },
    "notes": [],
    "unverified": []
  },
  "bhyt": {
    "type": "bhyt_household",
    "date": "2026-11-11",
    "months": 12,
    "members": 3,
    "base_salary": 2530000,
    "base_salary_ref": "Nghị định 161/2026/NĐ-CP",
    "rate": 0.045,
    "first_member_monthly": 113850,
    "ladder": {
      "1": 1,
      "2": 0.7,
      "3": 0.6,
      "4": 0.5,
      "5+": 0.4
    },
    "rows": [
      {
        "member": 1,
        "name": null,
        "factor": 1,
        "monthly": 113850,
        "amount": 1366200,
        "local_support_percent": 0,
        "local_support": 0,
        "you_pay": 1366200,
        "support_rules": []
      },
      {
        "member": 2,
        "name": null,
        "factor": 0.7,
        "monthly": 79695,
        "amount": 956340,
        "local_support_percent": 0,
        "local_support": 0,
        "you_pay": 956340,
        "support_rules": []
      }
    ],
    "total": 3142260,
    "you_pay": 3142260,
    "notes": [
      "The 70/60/50/40% ladder applies to household members joining in the same fiscal year, in joining order.",
      "If the base salary changes after payment there is no top-up or refund for the period already paid (NĐ 188/2025 Điều 8 k.3)."
    ]
  },
  "coverage": [
    "Hà Nội",
    "TP. Hồ Chí Minh",
    "Hải Phòng",
    "Đà Nẵng"
  ],
  "legal": [
    {
      "ref": "Luật BHXH 41/2024/QH15 (Điều 31, 36)",
      "effective_from": "2025-07-01"
    },
    {
      "ref": "NĐ 159/2025/NĐ-CP (BHXH tự nguyện)",
      "effective_from": "2025-07-01"
    }
  ],
  "reviewed": "2026-11-11",
  "disclaimer": "Reference calculation, not legal advice; check the official text."
}

Use cases

Show the exact amount to pay in a wallet or insurance-collection app
Compare monthly and yearly payment for a customer
Compute household BHYT for a family of five
Explain how much the state and the province support

FAQ

Why is the minimum 264,000 VND a month?

22 % × 1,500,000 = 330,000 VND, minus the 20 % state support (66,000 VND) for people outside the supported groups.

Which provinces add their own support?

Hà Nội, TP.HCM, Hải Phòng and Đà Nẵng are on file (see coverage); other provinces get the national rules only.

What rate is used for paying years ahead?

The fund’s average monthly investment return of the previous year published by BHXH VN; pass rate to override it.

Related APIs

{✓}

Voluntary BHXH & Household BHYT (VN) API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON