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. Several flagship hospitals — including Bach Mai Hospital, K Hospital, and a number of facilities in Ho Chi Minh City — have piloted publishing discharge summaries to the PHR. Nationally, the rollout schedule is tied to Circular 13/2025/TT-BYT and the Ministry of Health's decisions on shared digital platforms.

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. However, the technical contract for calling VNeID Health — payload format, push-versus-pull semantics — still depends on official specifications from the Ministry of Public Security and the Ministry of Health. Vendors and hospitals should not hardcode OAuth scopes or specific 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 a reference architecture, borrowing patterns familiar from Apple HealthKit and Google Health Records. It is not the official VNeID Health specification. The goal is to help hospital engineering teams visualize a plausible architecture and prepare the FHIR layer ahead of the public spec.

[Hospital EMR (FHIR-native)]
       │
       │ FHIR Bundle / DocumentReference (reference architecture)
       ↓
[Health integration gateway (orchestrated by the Ministry of Health)]
       │
       │ Concrete protocol awaiting the VNeID Health spec
       ↓
[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 — awaiting the VNeID Health spec

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.

Even so, the concrete scopes, the claims inside the ID token, the authorization granularity across document types (discharge summaries, prescriptions, lab results), the refresh cadence, and the revocation model all live inside the VNeID Health API specification — and the Ministry of Public Security and the Ministry of Health have not published it as of April 2026. This article does not invent scope names like health-record.read, since fabricated scopes would mislead engineering teams. Once the official specification ships, this page will be updated with real claims, scopes, and endpoints.

11. Frequently asked questions

Does VNeID have a public FHIR specification yet?

As of April 2026, the official VNeID Health API specification has not been published by the Ministry of Public Security or the Ministry of Health. Hospitals and vendors work through official Ministry of Health channels when participating in pilots. Every technical recommendation in this article is reference architecture, awaiting official confirmation.

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 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