Vietnam Form Catalogs API

Official Vietnamese code lists for forms: 54 ethnic groups, religions, nationalities, VSCO 2020 occupations, education, marital status, blood groups.

GEThttps://apibox.io.vn/v1/vn-catalogs/{catalog}/{code}

Data & JSON▶ Try it online

The catalogs API serves the coded lists that Vietnamese forms ask for, each with its code system: ethnic (54 ethnic groups, codes 01–54 of Quyết định 121-TCTK/PPCĐ, with common aliases such as Việt, Khmer, Mông), religion (the 16 religions recognised by the State, Công văn 6955/BNV-TGCP), nationality (ISO 3166-1 alpha-2 / alpha-3 / numeric with Vietnamese names), occupation (Danh mục nghề nghiệp Việt Nam VSCO 2020, Quyết định 34/2020/QĐ-TTg, levels 1–4), education (general education levels and the 8 levels of the Vietnamese qualifications framework with ISCED codes), marital_status, blood_type, gender (ISO/IEC 5218), id_document (căn cước, CCCD, passport…) and relationship.

Get a whole list (/v1/vn-catalogs/religion), one code (/v1/vn-catalogs/ethnic/08, nationality/VNM), or search with q, accents optional (q=kinh, q=han quoc, q=lap trinh in occupations). Occupations list level 1 by default; use level or parent=25 to go down the tree.

Ethnic groups, religions and occupations are rebuilt by a checked script from the HL7 Vietnam VN Core implementation guide, which transcribes the official texts; the small lists are maintained by hand and reviewed yearly. Codes marked as apibox codes are not official.

Parameters

Name	In	Type	Required
`catalog`	path\|query	string	no	`ethnic`, `religion`, `nationality`, `occupation`, `education`, `marital_status`, `blood_type`, `gender`, `id_document` or `relationship`; none lists the catalogs.
`code`	path\|query	string	no	One code (path `/ethnic/08` or `?code=`); nationalities accept alpha-2, alpha-3 or numeric.
`q`	query	string	no	Search by name, accents optional.
`level`	query	number	no	Occupations: level 1–4.
`parent`	query	string	no	Occupations: children of this code.
`limit`	query	number	no	Maximum items (1–1000).

Example

curl "https://apibox.io.vn/v1/vn-catalogs/ethnic?q=mong" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-catalogs/ethnic?q=mong');
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

{
  "catalog": "ethnic",
  "name_vi": "Dân tộc",
  "name_en": "Ethnic groups",
  "code_system": "QĐ 121-TCTK/PPCĐ (Tổng cục Thống kê, 02/03/1979): 01–54; 55 người nước ngoài, 99 không rõ are technical codes",
  "source": "HL7 Vietnam VN Core FHIR IG (https://vncore-ig.pages.dev/core), version 0.10.0",
  "reviewed": "2026-11-11",
  "query": "mong",
  "count": 1,
  "items": [
    {
      "code": "08",
      "name_vi": "HMông",
      "name_en": "H'Mong",
      "aliases": [
        "Mông",
        "H'Mông",
        "Hmong",
        "Mèo"
      ],
      "official": true
    }
  ]
}

Use cases

Fill dropdowns in public-service, HR or school forms
Map patient demographics in HIS / FHIR systems
Validate ethnic and religion codes in eKYC data
Classify job titles with VSCO 2020 codes

FAQ

Which ethnic code list is it?

The General Statistics Office list (QĐ 121-TCTK/PPCĐ): 01 Kinh … 54 Rơ Măm, plus technical codes 55 (foreigner) and 99 (unknown).

How are religions coded?

In the order of the official list of recognised religions (CV 6955/BNV-TGCP), as 2-digit codes like the HL7 VN Core code system; 00 means no religion.

Can I search without Vietnamese accents?

Yes, every search folds accents and đ, and ethnic groups have common aliases (Việt, Khmer, Mèo…).

Related APIs

{✓}

Vietnam Form Catalogs API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON