BHXH Forms D02-LT, TK1-TS (VN) API

Generate the social-insurance forms D02-LT (participant list) and TK1-TS (registration) of QĐ 366/QĐ-BHXH as Excel, with per-row validation.

POSThttps://apibox.io.vn/v1/vn-bhxh-forms

Data & JSON▶ Try it online

Send the rows from your HR system (JSON or an uploaded CSV / XLSX) and get the declaration as an Excel file laid out like the official template of QĐ 366/QĐ-BHXH (29/4/2026, in force 1/5/2026, replacing QĐ 595): form=d02-lt builds "Danh sách tham gia, điều chỉnh đóng BHXH, BHYT, BHTN" with the 21 columns (salary, allowances, contract type, from / to month, KCB facility, change type…) and merged header rows; form=tk1-ts builds one "Tờ khai đăng ký, điều chỉnh thông tin tham gia BHXH, BHYT" sheet per person with fields [01] to [17].

Each row is validated: 10-digit social insurance number, 12-digit personal ID, real dates (DD/MM/YYYY), month ranges, change type codes (TM, ON, TC, TD, GH, KL, TS, OF, DC…), salary plus allowances at least the regional minimum wage of the unit (unit.region or a ward code, NĐ 293/2025/NĐ-CP) and a warning above the 20 × base salary cap. format=json returns the errors per row and field (and the file as base64); strict=true refuses to build a file with errors (422).

D02-TS no longer exists in QĐ 366 (the household list moved to NĐ 188/2025/NĐ-CP). The column layout follows the templates published with QĐ 366 by e-filing providers, since the official scan lists the forms without reproducing them; check with your BHXH office for local requirements.

Parameters

Name	In	Type	Required	Default
`form`	body	string	no	`d02-lt`	d02-lt or tk1-ts.
`rows`	body	array	yes		D02-LT: [{ name, bhxh_code \| id_number, birth_date, position?, salary, allowance_position?, seniority_vk?, seniority_job?, other_allowances?, contract_type (indefinite\|fixed\|other), contract_date?, from_month, to_month?, health_facility?, result_delivery?, change_type, note? }]; TK1-TS: [{ name, sex, birth_date, id_number, ethnicity?, nationality?, phone?, email?, health_facility?, result_delivery?, address?, contribution?, payment_method?, change_request? }]. Or upload `file`.
`unit`	body	object	no		{ name, code, number?, region (1–4) or ward_code + province_code }.
`date`	body	string	no		Report date (default today).
`format`	body	string	no	`xlsx`	xlsx (file) or json (validation report + xlsx_base64).
`include_file`	body	boolean	no	`true`	JSON format: include xlsx_base64.
`strict`	body	boolean	no	`false`	Return 422 instead of a file when there are errors.

Example

curl -X POST "https://apibox.io.vn/v1/vn-bhxh-forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form":"d02-lt","format":"json","include_file":false,"unit":{"name":"Công ty TNHH Ví Dụ","code":"TA1234A","region":1},"rows":[{"name":"Nguyễn Văn An","id_number":"001090012345","birth_date":"15/03/1990","position":"Kế toán viên","salary":8000000,"contract_type":"fixed","contract_date":"01/11/2026","from_month":"11/2026","change_type":"TM"},{"name":"Trần Thị Bình","bhxh_code":"7912345678","birth_date":"20/05/1995","salary":4000000,"from_month":"11/2026","change_type":"DC"}]}'

const res = await fetch('https://apibox.io.vn/v1/vn-bhxh-forms', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "form": "d02-lt",
    "format": "json",
    "include_file": false,
    "unit": {
      "name": "Công ty TNHH Ví Dụ",
      "code": "TA1234A",
      "region": 1
    },
    "rows": [
      {
        "name": "Nguyễn Văn An",
        "id_number": "001090012345",
        "birth_date": "15/03/1990",
        "position": "Kế toán viên",
        "salary": 8000000,
        "contract_type": "fixed",
        "contract_date": "01/11/2026",
        "from_month": "11/2026",
        "change_type": "TM"
      },
      {
        "name": "Trần Thị Bình",
        "bhxh_code": "7912345678",
        "birth_date": "20/05/1995",
        "salary": 4000000,
        "from_month": "11/2026",
        "change_type": "DC"
      }
    ]
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/vn-bhxh-forms",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"form": "d02-lt", "format": "json", "include_file": False, "unit": {"name": "Công ty TNHH Ví Dụ", "code": "TA1234A", "region": 1}, "rows": [{"name": "Nguyễn Văn An", "id_number": "001090012345", "birth_date": "15/03/1990", "position": "Kế toán viên", "salary": 8000000, "contract_type": "fixed", "contract_date": "01/11/2026", "from_month": "11/2026", "change_type": "TM"}, {"name": "Trần Thị Bình", "bhxh_code": "7912345678", "birth_date": "20/05/1995", "salary": 4000000, "from_month": "11/2026", "change_type": "DC"}]},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-bhxh-forms');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"form":"d02-lt","format":"json","include_file":false,"unit":{"name":"Công ty TNHH Ví Dụ","code":"TA1234A","region":1},"rows":[{"name":"Nguyễn Văn An","id_number":"001090012345","birth_date":"15/03/1990","position":"Kế toán viên","salary":8000000,"contract_type":"fixed","contract_date":"01/11/2026","from_month":"11/2026","change_type":"TM"},{"name":"Trần Thị Bình","bhxh_code":"7912345678","birth_date":"20/05/1995","salary":4000000,"from_month":"11/2026","change_type":"DC"}]}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "form": "D02-LT",
  "rows": 2,
  "valid": false,
  "error_count": 1,
  "warning_count": 0,
  "errors": [
    {
      "row": 2,
      "field": "salary",
      "code": "below_minimum_wage",
      "message": "Salary + allowances 4,000,000 is below the region I minimum wage 5,310,000 (NĐ 293/2025/NĐ-CP)"
    }
  ],
  "warnings": [],
  "minimum_wage": {
    "region": "I",
    "amount": 5310000,
    "decree": "293/2025/NĐ-CP"
  },
  "legal": {
    "decision": "366/QĐ-BHXH",
    "signed": "2026-04-29",
    "effective_from": "2026-05-01",
    "replaces": "595/QĐ-BHXH (2017) and amendments",
    "template_source": "Templates attached to QĐ 366 as published by I-VAN providers (the official scan lists the forms only)",
    "reviewed": "2026-11-11"
  },
  "filename": "D02-LT-2026-11-11.xlsx",
  "disclaimer": "Reference template, not legal advice; check the official text and your BHXH office requirements."
}

Use cases

Export the monthly increase / decrease list from an HR system
Catch wrong BHXH numbers and salaries below the minimum wage before filing
Print TK1-TS forms for new employees in one call
Prepare files for manual entry in an e-filing (I-VAN) app

FAQ

Which version of the forms is used?

QĐ 366/QĐ-BHXH of 29/4/2026, in force from 1/5/2026, which replaced QĐ 595/QĐ-BHXH and its amendments.

Can I import the file directly into BHXH software?

The file follows the paper template. E-filing (I-VAN) software uses its own import formats, so use it for printing or as a source for manual entry.

How is the minimum wage checked?

Salary plus position and other allowances must be at least the regional minimum wage of the unit’s region at the report date; give unit.region (1–4) or unit.ward_code.

Related APIs

{✓}

BHXH Forms D02-LT, TK1-TS (VN) API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON