FHIR and VNeID: Vietnam's national digital health record

1. What VNeID and the PHR actually are

VNeID stands for Vietnam Electronic Identification — the national digital ID app developed by the Department of Police for Administrative Management of Social Order under the Ministry of Public Security. The app issues Level-1 and Level-2 electronic ID accounts to citizens, tightly bound to the 12-digit national ID card (CCCD). It has become the single front door for many public services, including residence registration, driver's licenses, social insurance, and social health insurance (BHYT — Vietnam's mandatory social health insurance covering most of the population).

The personal health record (PHR), known locally as "Sổ sức khỏe điện tử", is one section inside VNeID. It surfaces a citizen's summary clinical information: medical history, allergies, immunizations, prescriptions, basic lab results, and discharge summaries. The Ministry of Health defines the PHR's data scope, hospital systems supply the data, and VNeID acts as the consumer-facing display channel. Each citizen has one VNeID account tied to a 12-digit CCCD, and therefore exactly one PHR.

PHR rollout is expanding gradually through official Ministry of Health channels. Nationally, the rollout schedule is tied to Circular 13/2025/TT-BYT, Decision 1551/QĐ-BYT, and the Ministry of Health's shared digital-platform decisions; this article describes the public data and integration layer and does not assign pilot-site names unless a stable public list is available.

2. Decision 1332/QĐ-BYT and the PHR scope

Decision 1332/QĐ-BYT (Ministry of Health) issued the personal health record for integration into the VNeID app, together with technical documentation describing the data scope and display format. The Decision positions the PHR as a platform whose content the Ministry of Health governs, while VNeID acts as the citizen distribution channel. The PHR structure covers basic demographics, encounter history, prescriptions, diagnostic results, and discharge summaries.

Alongside Decision 1332, the Ministry of Health's downstream decisions on shared digital platforms — for example Decision 4048/QĐ-BYT (2025) on the deployment plan for shared digital platforms — continue to position the PHR as a Ministry of Health platform. The Department of Medical Service Administration and the National Health Information Center are the units directly responsible for operations. This is worth getting right, lest one mistakenly assume that the Ministry of Public Security owns the health data itself.

When designing VN Core FHIR, this article treats Decision 1332 as the authority for the PHR data scope. The reference inside the VNLegalDocumentRefCS CodeSystem uses the code QD-1332-VNeID to lock onto this exact document and avoid collisions with other decisions that share the number 1332.

3. Circular 13/2025 and the digital ID linkage requirement

Circular 13/2025/TT-BYT (Ministry of Health, issued 06/06/2025, effective 21/07/2025) regulates electronic medical records and replaces Circular 46/2018/TT-BYT. The Circular requires the EMR to interoperate with the citizen's national personal ID number or electronic ID account. This is an identifier requirement, not a clause mandating integration with any specific VNeID API.

Integrating with VNeID is one viable path that satisfies the requirement, since the national electronic ID account today is in fact VNeID. The technical surface must be split into two directions. Facility-to-Ministry-of-Health synchronization now has official specifications under Decision 1551/QĐ-BYT Appendix 02 and Appendix 03. Citizen-facing VNeID Health read/display — OAuth scopes, ID-token claims, document-level authorization, refresh and revocation semantics — still depends on separate guidance from the responsible authorities. Vendors and hospitals should not hardcode citizen-facing scopes or endpoints until they hold an integration agreement and technical documentation from the responsible authority.

4. FHIR-to-VNeID integration pattern — reference architecture

The diagram below describes the reference architecture after Decision 1551: the facility-to-Ministry-of-Health synchronization direction now has public technical detail, while the citizen-facing VNeID Health read/display direction remains an integration contract. The goal is to help hospital engineering teams prepare the FHIR layer without inventing app-side scopes or endpoints.

[Hospital EMR (FHIR-native)]
       │
       │ FHIR Bundle / DocumentReference (reference architecture)
       ↓
[Health integration gateway (orchestrated by the Ministry of Health)]
       │
       │ Upload/sync: Decision 1551 Appendix 02/03 · Citizen read: separate guidance
       ↓
[VNeID app on the patient's smartphone]

Two data directions are plausible in this model: Push and Pull. Push means the hospital posts the discharge summary and prescriptions to the integration gateway as soon as the patient consents. Pull means VNeID or the gateway actively queries the hospital on the patient's behalf. Both modes require explicit Consent under Law 91/2025/QH15 (the Personal Data Protection Law) and Decree 356/2025/NĐ-CP, which provides implementation guidance.

The hospital-side FHIR layer should have these components ready: a VNCorePatient profile with CCCD as the primary identifier, Composition for the medical record header, DocumentReference for digitally signed PDFs, an IPS-shaped Bundle to package the summary, and Provenance and AuditEvent capturing every access from the VNeID side.

5. FHIR and VNeID inside the PHR: Patient.identifier uses CCCD only

This is a frequent point of confusion in the field. In VN Core, Patient.identifier uses the CCCD as the core identifier, complemented by auxiliary slices for BHYT, BHXH (Vietnam Social Security), birth certificate, passport, and the hospital's internal medical record number (MRN). The NamingSystem for VNeID has been marked retired in this project to prevent modeling a VNeID account as an identifier on par with the CCCD. The reason: VNeID is an authentication and display channel, not the patient's independent clinical identifier.

An excerpt from the actual profile at input/fsh/profiles/VNCorePatient.fsh illustrates the identifier slicing:

Profile: VNCorePatient
Parent: Patient

* identifier ^slicing.discriminator.type = #value
* identifier ^slicing.discriminator.path = "system"
* identifier ^slicing.rules = #open
* identifier contains
    CCCD 1..1 MS and
    BHYT 0..1 MS and
    BHXH 0..1 MS and
    GKS  0..1 MS and    // Birth certificate — fallback for children without a CCCD
    HC   0..1 MS and    // Passport — for foreign nationals
    MRN  0..* MS

* identifier[CCCD].system = $vn-sid-cccd (exactly)
* identifier[HC].system   = $vn-sid-passport (exactly)

// VNeID has NO dedicated slice in VNCorePatient core (VNVNeIDNS is retired).
// References to a VNeID account (when needed) live in the integration layer
// via AuditEvent / Provenance, not in Patient.identifier core.

When the system needs to record which VNeID account performed an action — for example, in the audit log when the patient self-views their record through the app — the system points Provenance.agent or AuditEvent.agent.policy at the VNeID account URI in the integration layer. This separates the clinical identifier (CCCD) from the authentication-session identifier (VNeID), in line with HL7's security guidance and Law 91/2025.

6. FHIR IPS — the canonical pattern for the PHR

The International Patient Summary (IPS) is an Implementation Guide co-developed by HL7 and CEN, grounded in ISO 27269. IPS defines a FHIR Bundle that carries the minimum information needed for cross-border emergency care. The structure maps naturally onto the PHR's goals: compact, fast to load on a mobile device, and readable abroad when a Vietnamese citizen travels or works overseas.

An IPS Bundle is a document (type=document) anchored by a root Composition that describes its sections and links to clinical resources. The resources inside use the standard FHIR R4 datatypes — no new ones are invented. Vietnam can re-profile IPS to bind locally meaningful terminology (for example, ICD-10 VN for Condition or the Ministry of Health's drug list for Medication), but the Bundle structure stays intact to preserve global readability.

7. IPS STU2 structure — Required, Recommended, and Optional

The IPS STU2 reference — specifically the "Structure of the International Patient Summary" — defines three explicit obligation levels for sections inside the Composition.

Required (3 mandatory sections)

1. Problem List — uses Condition with clinical-status active/inactive/resolved and verification-status confirmed.
2. Allergies and Intolerances — uses AllergyIntolerance.
3. Medication Summary — uses MedicationStatement (preferred) or MedicationRequest.

Recommended (4 sections)

4. Immunizations — uses Immunization, aligned with the Expanded Program on Immunization (EPI/TCMR) under the 2025 Disease Prevention Law.
5. Diagnostic Results — uses Observation (laboratory) and DiagnosticReport.
6. Procedures (History of) — uses Procedure.
7. Medical Devices — uses DeviceUseStatement for hearing aids, pacemakers, and other implanted medical devices.

Optional (depending on clinical context)

• History of Past Illness — Condition with clinical-status resolved or inactive.
• Pregnancy Status / History — Observation.
• Functional Status — ClinicalImpression.
• Plan of Care — CarePlan.
• Advance Directives — modeled with Consent using an appropriate category, or DocumentReference for the source document. FHIR R4 has no resource named AdvanceDirective.
• Vital Signs — Observation (vital-signs category).
• Social History — Observation (social-history category).

A skeleton for an IPS Bundle (simplified pseudo-code, not full validation-ready JSON) looks like the following. In a real implementation, the Bundle must carry a timestamp, every entry must have a fullUrl, and the Composition must include the FHIR R4 mandatory fields (status, type, subject, date, author, title).

// Pseudo-code for illustration — NOT directly validatable
Bundle {
  resourceType: "Bundle",
  type: "document",
  timestamp: "2026-04-30T17:00:00+07:00",
  identifier: { system: "http://fhir.hl7.org.vn/core/sid/skdt-bundle", value: "..." },
  entry: [
    { fullUrl: "urn:uuid:composition-1",
      resource: Composition { status, type, subject, date, author, title, section[...] } },
    { fullUrl: "urn:uuid:patient-1",     resource: Patient { ... } },
    { fullUrl: "urn:uuid:allergy-1",     resource: AllergyIntolerance { ... } },
    { fullUrl: "urn:uuid:condition-1",   resource: Condition { ... } },
    { fullUrl: "urn:uuid:medstmt-1",     resource: MedicationStatement { ... } },
    { fullUrl: "urn:uuid:immun-1",       resource: Immunization { ... } }
  ]
}

8. DocumentReference for discharge PDFs

Discharge summaries in Vietnam typically exist as PDFs digitally signed by the attending physician and the department head. When pushed into the PHR, the PDF is referenced through a DocumentReference. The document type uses the matching LOINC code — for example 18842-5 Discharge summary — together with a subject pointing to the Patient and an author pointing to the signing Practitioner.

{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "18842-5",
      "display": "Discharge summary"
    }]
  },
  "subject": { "reference": "Patient/vn-001" },
  "date": "2026-04-30T17:00:00+07:00",
  "author": [{ "reference": "Practitioner/bs-001" }],
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://bv.local/discharge/abc.pdf",
      "hash": "...",
      "size": 245000
    }
  }]
}

Inside an IPS Bundle, DocumentReference can sit alongside the FHIR-ized Observations and Conditions. When the patient opens the PHR in VNeID, they see the structured summary with a link to the original PDF for full detail and the digital signature.

9. Consent for the VNeID PHR

Law 91/2025/QH15 (the Personal Data Protection Law) and Decree 356/2025/NĐ-CP set a high bar for informed consent. Health data is classified as sensitive personal data, so sharing with any third party — including the VNeID integration gateway — requires an explicit, auditable Consent. The FHIR Consent resource is where this decision is modeled.

{
  "resourceType": "Consent",
  "status": "active",
  "scope": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/consentscope",
      "code": "patient-privacy"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-consent-category-cs",
      "code": "vneid-data-sharing",
      "display": "Share data with the VNeID PHR"
    }]
  }],
  "patient": { "reference": "Patient/vn-001" },
  "dateTime": "2026-04-30T16:00:00+07:00",
  "policy": [{ "uri": "https://vneid.gov.vn/policy" }],
  "provision": {
    "type": "permit",
    "actor": [{
      "role": { "coding": [{ "code": "VNEID" }] },
      "reference": { "reference": "Organization/vneid" }
    }],
    "action": [{ "coding": [{ "code": "access" }] }]
  }
}

Consent must be captured before any Bundle or DocumentReference is pushed to the integration gateway. When the patient withdraws consent, the hospital system updates Consent.status to inactive and creates a Provenance record capturing the revocation. This mechanism supports the rights of access, rectification, and erasure mandated by Law 91/2025.

10. Authentication and authorization — sync specs published, citizen read pending

A plausible integration path is OAuth 2.0 with OpenID Connect, with VNeID acting as the citizen-side Identity Provider. The patient logs in to VNeID, receives an access token, and the health integration gateway uses that token to authorize the hospital to push or pull data. The pattern mirrors Apple HealthKit and Google Health Records, which is why it dominates conversations in the Vietnamese vendor community.

It is important to distinguish two data directions. Upload/synchronization (healthcare facility → Ministry of Health) now has official specifications: Decision 1551/QĐ-BYT (31/05/2026) Appendix 02 defines synchronization to the Ministry of Health health-data gateway (RESTful/JSON, OAuth2 + Bearer Token, base64 payload envelope + SHA256RSA digital signature), and Appendix 03 defines intake from Vietnam Social Security through NDOP/National Data Exchange Platform G12 (API Key, signed XML). Citizen-facing read/display through VNeID Health — scopes, ID-token claims, document-level authorization, refresh, and revocation — remains under separate Ministry of Public Security and Ministry of Health guidance and is not publicly complete. This article does not invent scope names like health-record.read, since fabricated scopes would mislead engineering teams.

11. Frequently asked questions

Does VNeID have a public FHIR specification yet?

The facility-to-Ministry-of-Health synchronization direction has official technical specifications in Decision 1551/QĐ-BYT (31/05/2026, Appendix 02 and Appendix 03). The citizen-facing VNeID Health read/display contract — OAuth scopes, ID-token claims, read endpoints, and revocation semantics — is still separate and not publicly complete. Hospitals and vendors work through official Ministry of Health channels when participating in pilots; VN Core models the synchronization envelopes and keeps the citizen-app adapter outside Patient.identifier.

What if a patient does not use VNeID?

The 12-digit CCCD remains the core identifier in VNCorePatient. A patient who does not use VNeID still has a complete FHIR record inside the hospital system. VNeID is only an additional display channel — it does not replace the source-of-truth medical record at the hospital.

Is there a sandbox to test the VNeID API?

There is no public sandbox today. Vendors must register with the Ministry of Public Security or join the Ministry of Health's pilot program. Participants receive technical documentation, a test environment, and developer-scoped accounts.

Where is the PHR stored?

According to public documents (including Decision 1332/QĐ-BYT and Decision 4048/QĐ-BYT), the PHR is a platform managed by the Ministry of Health and surfaced through VNeID. The official physical storage location should be confirmed via concrete architecture documentation — it is not appropriate to draw conclusions without an authoritative source.

Is FHIR mandatory for the PHR?

Current legal documents do not mandate FHIR for the PHR. That said, IPS is the most natural technical pattern: it is compatible with VN Core's direction and with the trajectory of other countries that run national smartphone-based health records.

12. Legal and technical references

Vietnamese legal documents

• Decision 1332/QĐ-BYT — the personal health record on VNeID. Code in VN Core: QD-1332-VNeID.
• Decision 1551/QĐ-BYT (31/05/2026) — periodic health-check interoperability and Appendix 02/03 synchronization API specifications. Code in VN Core: QD-1551-2026.
• Decision 4048/QĐ-BYT (2025) — deployment plan for the Ministry of Health's shared digital platforms.
• Circular 13/2025/TT-BYT (issued 06/06/2025, effective 21/07/2025) — electronic medical records, mandating linkage with the national personal ID number or electronic ID account.
• Law 91/2025/QH15 — Personal Data Protection Law, effective 01/01/2026. Code in VN Core: L-91-2025.
• Decree 356/2025/NĐ-CP — implementation guidance for Law 91/2025, effective 01/01/2026.
• Decree 102/2025/NĐ-CP — management of digital health data, effective 01/07/2025.
• Full reference at the VN Core legal corpus.

International technical specifications

• FHIR R4 (4.0.1) — the version used by VN Core.
• International Patient Summary STU2 — FHIR Bundle pattern for summary records.
• Structure of the International Patient Summary — Required, Recommended, Optional sections.
• LOINC — document-type codes for DocumentReference.
• FHIR Security — guidance on AuditEvent and Provenance.

Sources from the VN Core project

• input/fsh/profiles/VNCorePatient.fsh — defines the CCCD/BHYT/BHXH/GKS/HC/MRN identifier slices.
• input/fsh/naming-systems/VNVNeIDNS.fsh — the retired VNeID NamingSystem, with a note on why it is not used as a core identifier.
• input/fsh/terminology/VNLegalDocumentRefCS.fsh — the CodeSystem of legal documents referenced across the IG.

Further reading