Glossary & Data Model

Terms

NPHIES — National Platform for Health Information Exchange Services. Saudi Arabia's national exchange through which providers and payers transact eligibility, pre-authorization and claims.

DHS — the Motalabate Health platform that Dentolize actually talks to. It fronts NPHIES. Throughout the code and UI, "DHS" is the integration; "NPHIES" is the identifier scheme.

NPHIES code / provider code — identifies a place of care. In Dentolize this lives on Branch.nphiesCode, not on the company. Every eligibility check and approval is filed under one branch's code, sent as the OrganizationCode header.

Payer — the insurer. Identified in requests by InsuranceCompany.nphiesCode.

NPHIES insurer id — InsuranceCompany.nphiesInsuranceCompanyId, distinct from nphiesCode. Part of the composite unique [companyId, nphiesInsuranceCompanyId] used to recognise an insurer returned by discovery. It cannot be edited after creation — editInsuranceCompany accepts only nphiesCode (schema.graphql:703-704).

Client secret — the clinic's DHS credential, exchanged at /api/Login for a bearer token. Stored encrypted; only a ****#### mask is ever returned.

Coverage — one insurance arrangement for one person: insurer + policy + class + limits + dates. Discovery may return several.

Eligibility check — a point-in-time answer to "is this person covered right now?" Recorded as a DHSEligibilityCheck; the latest is pointed at by Patient.currentEligibilityId.

Pre-authorization (pre-auth / approval) — asking the payer to commit, before treatment, to covering specific services. Recorded as a DHSApproval. Not the same as a claim.

Approval number — the payer's identifier for a pre-auth. Also stamped onto each linked Operation.preAuth.

Iqama — Saudi residency permit. Its number is a 10-digit identifier starting with 2 (national IDs start with 1). In the DHS mappings iqama and residency are treated as the same thing.

SCFHS — Saudi Commission for Health Specialties. The practitioner's licence number, required on every pre-auth.

Deductible rate — the share the patient pays. Dentolize's insurancePercentage is the inverse: a 20% deductible becomes 80% cover (DHSCheckInsurance.utils.ts:24-33). Returned by DHS as a string.

Operation — Dentolize's term for a single planned or performed treatment on the chart. What becomes a "service line" in a pre-auth.

insuranceDiscount: false — the "not subject to insurance" flag on an operation. Such operations are excluded from DHS submission, client- and server-side.

Enums

DHSApprovalStatus

schema.prisma:5602 · enums.graphql:1304 — identical in both.

EligibilityStatus

schema.prisma:5613 — ELIGIBLE, NON_ELIGIBLE. There is no "unknown" state; anything not explicitly eligible is stored as NON_ELIGIBLE.

Permission — DHS values

schema.prisma:6348-6356 · enums.graphql:622-630:

VIEW_DHS_INTEGRATION   EDIT_DHS_INTEGRATION   VIEW_DHS_APPROVALS
CHECK_DHS_INSURANCE    CHECK_DHS_ELIGIBILITY  CREATE_DHS_APPROVAL
CANCEL_DHS_APPROVAL    CREATE_MANUAL_DHS_APPROVAL   GET_DHS_APPROVAL

Orphaned values. Migration 20260615152553_dhs_permissions added MANAGE_DHS_INTEGRATION, MANAGE_DHS_APPROVALS and CHECK_INSURANCE to the Postgres enum. They were superseded a day later by the nine above. Postgres cannot drop enum values, so they persist in the database type while being absent from schema.prisma and enums.graphql. A repo-wide grep for MANAGE_DHS returns zero hits. The PR description still names them.

Data model

DHSIntegration — schema.prisma:5541

One per company (companyId @unique). Holds the encrypted credential.

No plaintext column exists. The GraphQL type exposes only hasSecret, clientSecretMask and secretUpdatedAt (types.graphql:5468-5476).

DHSEligibilityCheck — schema.prisma:5555

Indexes: [patientId], [companyId, patientId].

DHSApproval — schema.prisma:5575

Indexes: [patientId], [companyId, status], [status, updatedAt] — the last one serves the cron's PENDING + orderBy: updatedAt scan.

Two load-bearing comments in the schema:

• :5586 — status === 'CANCELED' is the source of truth for "canceled?"; canceledAt/By

carry audit information the status does not.

• :5591 — manualUpdateById != null is the source of truth for "manually updated?"

DHS fields on existing models

InsurancePolicy and PolicyClass have no DHS fields at all. They connect to DHS only indirectly, through InsuranceCompany.nphiesInsuranceCompanyId and the ResolveInsuranceCoverage response type. Their identity keys matter for resolution: InsurancePolicy.@@unique([insuranceCompanyId, policyNumber]) (:1349) and PolicyClass.@@unique([insurancePolicyId, name]) (:1383).

Migrations

Eight touch DHS.

GraphQL surface

Queries — schema.graphql:597-604

getDHSClientSecret: GetDHSClientSecretResponse!
dhsBranches: DHSBranchesResponse!
getInsuranceCompanyDhsInsuranceHierarchy(input: GetDhsInsuranceHierarchyInput!): GetDhsInsuranceHierarchyResponse!
resolveInsuranceCoverages(input: ResolveInsuranceCoverageInput!): ResolveInsuranceCoverageResponse!
getDHSApprovals(input: GetDHSApprovalsInput!): GetDHSApprovalsResponse!
totalDHSApprovals(input: TotalDHSApprovalsInput!): Int!
dhsApprovalDetails(dhsApproval: ID!): DHSApproval!

Mutations — schema.graphql:1378-1390

dhsAuthentication: DHSAuthenticationResponse!
saveDHSIntegration(input: SaveDHSIntegrationInput!): SaveDHSIntegrationResponse!
testDHSConnection: TestDHSConnectionResponse!
rotateDHSClientSecret(newSecret: String!): RotateDHSClientSecretResponse!
updateBranchesNphiesCodes(input: UpdateBranchesNphiesCodesInput!): UpdateBranchesNphiesCodesResponse!
checkInsuranceEligibility(input: CheckInsuranceEligibilityInput!): CheckInsuranceEligibilityResponse!
dhsCheckEligibility(input: DHSCheckEligibilityInput!): DHSCheckEligibilityResponse!
updatePatientDetails(input: UpdatePatientDetailsInput!): updatePatientDetailsResponse!
dhsApprovalSubmission(input: DHSApprovalSubmissionInput!): DHSApprovalSubmissionResponse!
dhsGetApproval(input: DHSGetApprovalInput!): DHSGetApprovalResponse!
dhsCancelApproval(input: DHSCancelApprovalInput!): DHSCancelApprovalResponse!
dhsManualUpdateOperations(input: DHSManualUpdateOperationsInput!): DHSManualUpdateOperationsResponse!

Note rotateDHSClientSecret and dhsApprovalDetails take bare scalars rather than input objects, unlike everything else.

Key response types

Outbound DHS endpoints

All carry Authorization: Bearer <token> and OrganizationCode: <branch.nphiesCode>.

Coding tables

Identifier type → systemTypeId (Check Insurance)

DHSIdentifierMappings.ts:76-96. There is no code 4; unknown → 1.

Identifier type → eligibility / approval code

DHSIdentifierMappings.ts:22-43. Unknown → 7, logged, never thrown.

DHS type → legacy patient type

DHSIdentifierMappings.ts:50-73, applied before updatePatientDetails. Pass-through: national_id, passport, driver_license, residency, OTHER. Mapped: other → OTHER, iqama → residency, visa | border_number | displaced_person → OTHER. Unmapped → OTHER, logged.

Other codings

DHSCheckEligibility.utils.ts (duplicated verbatim in DHSApprovalSubmission.utils.ts:167-198):

Hardcoded in the eligibility payload: subscriberRelated: 6 (Self), fallback NPHIES code 'INS-FHIRss', fallback DOB '2000-01-01', fallback names 'Unknown', fallback policy holder 'Holder'.

Hardcoded in the approval payload: vatPercentage: 15, deductible: 0, durationOfDrugSupply: 1, estimatedLengthOfStay: 1, specialityCode: '08.26', specialityName: 'General', exactly one visit dated now.

Protected fields

packages/server/src/utils/dhsFieldGuards.js:

Arrays are compared order-insensitively as multisets; Dates by getTime(); only fields present in the incoming payload are checked.