BHYT card code decoder API

Decode a Vietnamese health insurance card code (mã thẻ BHYT): beneficiary group, benefit level and %, issuing province and social insurance number.

GETPOSThttps://apibox.io.vn/v1/bhyt-check

Data & JSON▶ Try it online

A Vietnamese health insurance card code has 15 characters, e.g. DN4797931234567: 2 letters for the beneficiary group (DN = employee of a company, HT = pensioner, TE = child under 6, HS / SV = pupil / student…), 1 digit for the benefit level (1–5), 2 digits for the province that issued the card and the 10-digit social insurance number (mã số BHXH). The API splits the code and explains each part in Vietnamese and English.

Group codes and benefit levels follow Appendix I of Official Letter 1804/BHXH-QLT (04/08/2025, after the 2024 amendment of the Health Insurance Law): 65 groups in five categories (paid by employers, by the social insurance fund, by the state budget, partly by the budget, voluntary), plus old codes still printed on cards. Levels are returned with their share of costs (100%, 95%, 80%…) and conditions. A level that differs from the usual one for the group is flagged as a warning, not an error, because a person in several groups gets the best benefit. codes checks up to 500 codes at once and list=true returns the full table.

Only the structure is decoded: the card is not looked up on the VSS portal (validity dates and registered clinic are unknown), and nothing is stored.

Parameters

Name	In	Type	Required
`code`	query\|body	string	yes	The 15-character card code (spaces allowed), or a 10-digit social insurance number.
`codes`	body	array	no	Up to 500 codes at once.
`list`	query	boolean	no	`true`: return the table of group codes and levels.

Example

curl "https://apibox.io.vn/v1/bhyt-check?code=DN4797931234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/bhyt-check?code=DN4797931234567', {
  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/bhyt-check?code=DN4797931234567",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/bhyt-check?code=DN4797931234567');
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

{
  "input": "DN4797931234567",
  "normalized": "DN4797931234567",
  "formatted": "DN 4 79 7931234567",
  "format": "card code (15 characters)",
  "valid": true,
  "errors": [],
  "warnings": [],
  "group": {
    "code": "DN",
    "vi": "Người lao động làm việc theo hợp đồng lao động, người quản lý trong doanh nghiệp nhà nước",
    "en": "Employees and managers of state-owned enterprises",
    "category": {
      "number": 1,
      "vi": "Nhóm do người lao động và người sử dụng lao động đóng",
      "en": "Paid by employer and employee"
    },
    "legacy": false,
    "usual_benefit_level": 4
  },
  "benefit_level": {
    "level": 4,
    "percent": 80,
    "vi": "80% chi phí KCB trong phạm vi được hưởng; 100% khi KCB tại tuyến xã, chi phí một lần dưới 15% lương cơ sở hoặc đủ 5 năm liên tục và chi trả cùng trong năm vượt 6 tháng lương cơ sở",
    "en": "80% of covered costs; 100% at commune level, below 15% of the base salary per visit, or after 5 consecutive years once co-payments exceed 6 months of base salary"
  },
  "province": {
    "code": "79",
    "name": "TP. Hồ Chí Minh",
    "since_2025": "TP. Hồ Chí Minh"
  },
  "social_insurance_number": "7931234567",
  "legal_basis": "QĐ 1351/QĐ-BHXH (card code structure); Công văn 1804/BHXH-QLT 04/08/2025, Phụ lục I (group codes, benefit levels); Luật BHYT 2008 amended by Luật 51/2024/QH15 (Điều 22)",
  "reviewed": "2026-11-11"
}

Use cases

Show the co-payment rate at hospital or pharmacy check-in
Validate card codes typed into a clinic system (HIS)
Group patients by beneficiary type in reports
Explain card codes to customers in an insurance app

FAQ

What about the new 10-digit or 12-digit codes?

Electronic cards show the 10-digit social insurance number and, since 08/2025, the 12-digit personal ID can replace it. These are accepted but carry no group or level: use the 15-character code for that.

Does it tell me if the card is still valid?

No, validity dates are not part of the code. Check them on the card, VssID or VNeID.

Why is a level marked as unusual?

Each group has a usual level (DN → 4 = 80%). A different level can be correct when the holder also belongs to a better-covered group, so it is only a warning.

Related APIs

{✓}

BHYT card code decoder API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON