VssID data API: BHXH book, BHYT card and benefits

Bảo hiểm xã hội Việt Nam · Identity

VssID is the official self-care app of Vietnam Social Security (Bảo hiểm xã hội Việt Nam), the agency that runs the country's social-insurance and health-insurance schemes. Citizens sign in with a BHXH account or through VNeID, then open an electronic social-insurance book, a digital BHYT health card with a scannable QR, contribution history, benefit-regime status and a social-insurance wallet that can cash in through partner banks such as BIDV. The same client files administrative procedures with an SMS OTP, looks up nearby social-security offices on a map, and keeps hospital and province catalogs for registered care. It serves workers, pensioners and dependants across Vietnam, sitting next to VNeID as the identity rail and competing with hospital-issued paper cards at the clinic counter.

Every signed-in VssID citizen maps onto a Vietnam Social Security ledger keyed by maBhxh and a health-insurance card maTheBhyt. The session itself carries an OAuth access_token issued after BHXH login or a VNeID code exchange, plus identity fields hoTen, ngaySinh, gioiTinh and soCMND. The health-card record adds ngayHieuLuc, ngayHetHan and a QR payload; the electronic book lists contribution rows with namDong, thangDong and mucDong; benefit regimes return under cheDoHuong; the SS-wallet exposes soTien next to a linked bank account.

Hospital visits page by year as KCB rows; the catalog returns maTinh, maHuyen and hospital codes maBV / tenBV; administrative filings confirm with an SMS otp; cash-in through BIDV records requestId amounts against the live wallet balance.

Clinic intake teams confirm a live BHYT card from the QR, payroll desks match contribution months to the agency book, benefits-payment agents top up only known wallets, and kiosk staff quote the right province before a dossier goes in — and openData Studio turns that social-insurance ledger into callable open data.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Sign in with a BHXH account
POST /v1/auth/dvc osint
Signs a citizen into VssID with a Vietnam Social Security account and returns the access_token, maBhxh and identity fields used by later book and card calls.
Auth: Unauthenticated. Body is the BHXH username/password. The returned access_token is attached on later calls.
- username
- password
- access_token
- maBhxh
- hoTen
- soCMND
```
POST /v1/auth/dvc HTTP/1.1
Content-Type: application/json

{
  "username": "0123456789",
  "password": "********"
}
```
```
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.example",
  "maBhxh": "7912345678",
  "hoTen": "Nguyen Van An",
  "soCMND": "079123456789"
}
```
Exchange a VNeID OAuth code
GET /v1/auth/vneid-code osint
Exchanges a VNeID authorization code for the VssID access_token used as the citizen session.
Auth: Unauthenticated OAuth redirect. Query carries code from VNeID (client_id=vssid). Returns access_token.
- code
- client_id
- redirect_uri
- response_type
- access_token
- token_type
- maBhxh
```
GET /v1/auth/vneid-code?code=spl_abc123&client_id=vssid HTTP/1.1
```
```
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.example",
  "token_type": "Bearer",
  "maBhxh": "7912345678"
}
```
Read electronic BHXH book
GET /v1/ss-book opendata
Returns the signed-in citizen's electronic social-insurance book: maBhxh, legal name, date of birth, gender, ID number and address shown on the e-book screen.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- maBhxh
- hoTen
- ngaySinh
- gioiTinh
- soCMND
- diaChi
```
GET /v1/ss-book HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "maBhxh": "7912345678",
  "hoTen": "Nguyen Van An",
  "ngaySinh": "1990-04-12",
  "gioiTinh": "Nam",
  "soCMND": "079123456789",
  "diaChi": "Q.1, TP.HCM"
}
```
Read BHYT health-insurance card
GET /v1/health-card opendata
Returns the digital BHYT card shown in the app: card number, holder identity, validity window and registered hospital used at clinic intake.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- maTheBhyt
- hoTen
- ngaySinh
- gioiTinh
- ngayHieuLuc
- ngayHetHan
- noiKham
```
GET /v1/health-card HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "maTheBhyt": "DN4791234567890",
  "hoTen": "Nguyen Van An",
  "ngaySinh": "1990-04-12",
  "gioiTinh": "Nam",
  "ngayHieuLuc": "2026-01-01",
  "ngayHetHan": "2026-12-31",
  "noiKham": "BV Cho Ray"
}
```
Read BHYT card QR payload
GET /v1/health-card/qr opendata
Returns the scannable QR payload for the live BHYT card, used by clinic intake instead of a paper card.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- maTheBhyt
- qr
- hoTen
```
GET /v1/health-card/qr HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "maTheBhyt": "DN4791234567890",
  "qr": "DN4791234567890|Nguyen Van An|19900412|1|20260101-20261231",
  "hoTen": "Nguyen Van An"
}
```
Page contribution history
GET /v1/contributions/history opendata
Pages the citizen's social-insurance contribution history (quaTrinh): year, month, contribution amount and employer, from the contribution screens.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- quaTrinh
- namDong
- thangDong
- mucDong
- donVi
```
GET /v1/contributions/history HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "quaTrinh": [
    {
      "namDong": 2026,
      "thangDong": 9,
      "mucDong": 4680000,
      "donVi": "Cong ty TNHH ABC"
    }
  ]
}
```
Read benefit-regime entitlements
GET /v1/benefits/entitlements opendata
Returns social-insurance benefit regimes the citizen currently holds (cheDoHuong): regime code, name, status and amount shown on the benefits screen.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- cheDoHuong
- maCheDo
- tenCheDo
- trangThai
- soTien
```
GET /v1/benefits/entitlements HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "cheDoHuong": [
    {
      "maCheDo": "OM_DAU",
      "tenCheDo": "Om dau",
      "trangThai": "DANG_HUONG",
      "soTien": 3500000
    }
  ]
}
```
Read SS-wallet account
GET /v1/ss-wallet/account openbanking
Returns the linked social-insurance wallet account: bank, masked account number, holder name and LINKED status used before cash-in.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- accountNo
- bankCode
- hoTen
- status
```
GET /v1/ss-wallet/account HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "accountNo": "970418xxxxxx1234",
  "bankCode": "BIDV",
  "hoTen": "Nguyen Van An",
  "status": "LINKED"
}
```
Read SS-wallet balance
GET /v1/ss-wallet/balance openbanking
Returns the live SS-wallet soTien in VND shown on the wallet home before cash-in or cash-out.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- soTien
- currency
```
GET /v1/ss-wallet/balance HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "soTien": 1250000,
  "currency": "VND"
}
```
Start SS-wallet cash-in
POST /v1/ss-wallet/cash-in openfinance
Starts a BIDV (or other linked-bank) cash-in into the SS-wallet and returns requestId plus fee so the citizen can confirm with a bank OTP.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls. Completing the top-up uses a bank-OTP confirm step.
- soTien
- bankCode
- requestId
- fee
- status
```
POST /v1/ss-wallet/cash-in HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "soTien": 500000,
  "bankCode": "BIDV"
}
```
```
{
  "requestId": "ci-9c21e4",
  "soTien": 500000,
  "fee": 0,
  "status": "PENDING_OTP"
}
```
Send procedure-filing OTP
POST /v1/procedures/otp osint
Sends the SMS OTP that confirms an administrative filing before the dossier is submitted.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- thuTucId
- soDienThoai
- otpRequestId
- status
```
POST /v1/procedures/otp HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "thuTucId": "GDDT_653",
  "soDienThoai": "0901234567"
}
```
```
{
  "otpRequestId": "otp-8f21a4",
  "status": "SENT"
}
```
Page hospital visits by year
GET /v1/visits/by-year opendata
Pages the citizen's KCB (medical-visit) history for a year: visit date, hospital, diagnosis and amount.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls. Query: year.
- year
- visits
- ngayKham
- benhVien
- chanDoan
- soTien
```
GET /v1/visits/by-year?year=2026 HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "year": 2026,
  "visits": [
    {
      "ngayKham": "2026-09-12",
      "benhVien": "BV Cho Ray",
      "chanDoan": "Kham tong quat",
      "soTien": 180000
    }
  ]
}
```
List provinces and hospitals
GET /v1/catalog/provinces opendata
Returns the administrative catalog used by lookup and filing screens: provinces, districts and hospitals.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- tinh
- maTinh
- tenTinh
- huyen
- maHuyen
- tenHuyen
- benhVien
- maBV
- tenBV
```
GET /v1/catalog/provinces HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "tinh": [{"maTinh": "79", "tenTinh": "TP. Ho Chi Minh"}],
  "huyen": [{"maHuyen": "760", "tenHuyen": "Quan 1"}],
  "benhVien": [{"maBV": "79001", "tenBV": "BV Cho Ray"}]
}
```
Read BHYT card-renewal quote
GET /v1/payments/card-renewal openfinance
Returns the quote to renew the BHYT card: amount due, current expiry and term, used before the in-app payment.
Auth: Session access_token from POST /v1/auth/dvc or the VNeID code exchange, sent on later first-party calls.
- maTheBhyt
- soTien
- ngayHetHan
- kyHan
```
GET /v1/payments/card-renewal HTTP/1.1
Authorization: Bearer eyJhbGciOi...
```
```
{
  "maTheBhyt": "DN4791234567890",
  "soTien": 804600,
  "ngayHetHan": "2026-12-31",
  "kyHan": "12T"
}
```

Data categories

identity
health-card
contributions
benefits
wallet
procedures
catalog

Where teams use this data

Clinic eligibility check at intake
Hospital front desks read GET /v1/health-card (maTheBhyt, hoTen, ngaySinh, ngayHetHan) and GET /v1/health-card/qr so a scanned QR confirms the live BHYT card before the visit is opened, instead of relying on a paper card that may already have expired.
Contribution and benefit reconciliation
Payroll or union tooling pulls GET /v1/ss-book (maBhxh, hoTen) plus GET /v1/contributions/history (namDong, thangDong, mucDong) and GET /v1/benefits/entitlements so HR can match declared months and benefit regimes against the agency ledger.
SS-wallet cash-in desk
A benefits-payment console reads GET /v1/ss-wallet/account and GET /v1/ss-wallet/balance then posts POST /v1/ss-wallet/cash-in so agents only top up a wallet whose soTien and linked BIDV account are already known.
Procedure OTP and hospital catalog
Citizen-service kiosks send POST /v1/procedures/otp for administrative filings and join GET /v1/catalog/provinces with GET /v1/visits/by-year so staff can quote the right province and last-year KCB visits before the dossier is submitted.

Frequently asked questions

How does VssID authenticate citizen API calls?

POST /v1/auth/dvc signs in with a BHXH account. GET /v1/auth/vneid-code exchanges a VNeID OAuth code (client_id=vssid) for an access_token. Later calls send that token on first-party routes.

Which endpoints expose the BHXH book and BHYT card?

GET /v1/ss-book returns the electronic social-insurance book (maBhxh, hoTen). GET /v1/health-card returns the BHYT card (maTheBhyt, ngayHieuLuc, ngayHetHan). GET /v1/health-card/qr returns the scannable QR used at clinic intake. GET /v1/contributions/history pages namDong, thangDong and mucDong.

What is the VssID social-insurance wallet?

GET /v1/ss-wallet/account and GET /v1/ss-wallet/balance return the linked account and soTien. POST /v1/ss-wallet/cash-in starts a BIDV cash-in and returns requestId plus fee. Completing the top-up uses the bank OTP confirm step.

Can the VssID API see benefit regimes and hospital visits?

Yes. GET /v1/benefits/entitlements returns cheDoHuong. GET /v1/visits/by-year pages KCB visits. GET /v1/catalog/provinces lists maTinh / maHuyen / hospitals. POST /v1/procedures/otp confirms administrative filings.

Apps similar to VssID

VNeID — VNeID is Vietnam's national digital-identity app from the Ministry of Public Security: citizens use it as the eID wallet and as an SSO rail that VssID consumes via OAuth.
DigiLocker — DigiLocker is India's government document wallet where citizens store issued IDs and certificates on the phone, in the same class as VssID's electronic BHXH book and BHYT card.
Pak Identity — Pak Identity is NADRA's citizen-identity app for CNIC documents, a digital ID vault and family records — a South-Asian analogue of VssID's insurance-identity wallet.
Налоги ФЛ — Налоги ФЛ is Russia's Federal Tax Service cabinet for individual taxpayers, another national-agency self-care app that signs in through a government identity rail.

More Identity apps

Topics

vssid api
vssid data api
vietnam social security api
bhxh api
bhyt card api
vssid wallet
vssid contribution history
vneid vssid
bao hiem xa hoi viet nam api

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

VssID data API: BHXH book, BHYT card and benefits

Screenshots

API surface

Sign in with a BHXH account

Exchange a VNeID OAuth code

Read electronic BHXH book

Read BHYT health-insurance card

Read BHYT card QR payload

Page contribution history

Read benefit-regime entitlements

Read SS-wallet account

Read SS-wallet balance

Start SS-wallet cash-in

Send procedure-filing OTP

Page hospital visits by year

List provinces and hospitals

Read BHYT card-renewal quote

Data categories

Where teams use this data

Clinic eligibility check at intake

Contribution and benefit reconciliation

SS-wallet cash-in desk

Procedure OTP and hospital catalog

Frequently asked questions

Related apps

Apps similar to VssID

More Identity apps

Microsoft Authenticator

Pak Identity

Налоги ФЛ

Topics

Need this app's data API integrated?