What Happens When You Tap a My Number Health Insurance Card — Reading Online Eligibility Verification and Its Integration with the Medical Billing System from ORCA's Source Code

Tap a My Number health insurance card on the card reader at a clinic’s reception desk and identity confirmation and insurance eligibility verification are done in a few seconds. What systems are running behind those few seconds, and in what order — and in particular, how does the eligibility information reach the medical billing system that ultimately handles the claim? Surprisingly few engineers can explain it.

Two articles ago we established that ORCA (the JMA Standard Receipt Software) is a medical billing system, and last time we covered how to grasp the whole Nichi-Rece API from the source code. This time, as an application of both, we dissect online eligibility verification (in Japanese shorthand, on-shi) from the medical billing system’s side.

• The end-to-end flow from tapping a My Number health insurance card to eligibility information being registered in the medical billing system
• What the “file-based integration” that connects the eligibility verification terminal to the medical billing system actually consists of
• The receiving side in ORCA — the 20 eligibility-verification APIs and the tbl_onshi_* tables
• The chronology of regulatory work from 2020 to 2026, carved into the COBOL revision histories

Statements about the scheme itself are based on published materials from the Ministry of Health, Labour and Welfare and from ORCA officially; statements about the source code are the result of actually reading the officially published Nichi-Rece 5.2 series source (the snapshot published on 1 July 2026).

Table of Contents

1. The Bottom Line First — Eligibility Verification Is a Relay Between “Four Actors”
2. The Scheme in Brief — What Online Eligibility Verification Is
3. Between Terminal and Billing System — The OQS File Integration Interface
4. The Receiving Side in ORCA — Counting the 20 Eligibility-Verification APIs from the Source
5. Where the Data Goes — The 13 tbl_onshi_* Tables
6. Reading tbl_onshi_kaku — What a Single Eligibility Verification Leaves Behind
7. The Revision History Is a Chronology of the Scheme — 2020 to 2026
8. Reflection into Patient Registration — The Result Does Not Become Insurance Information “As Is”
9. Practical Points for Those Building Integrating Systems
10. Summary
11. References

1. The Bottom Line First — Eligibility Verification Is a Relay Between “Four Actors”

Put the journey from tapping a My Number health insurance card to eligibility information landing in the medical billing system on a single page, and there are four actors.

flowchart LR
    subgraph clinic["Inside the medical institution"]
        CR["Card reader with<br/>facial recognition"]
        TERM["Eligibility verification terminal"]
        REN["Integration program<br/>(onshi-tools on Nichi-Rece)"]
        ORCA["ORCA/Nichi-Rece<br/>accumulates in tbl_onshi_*"]
        UKE["Reception & patient registration workflows"]
        CR --> TERM
        TERM <-->|"shared folder<br/>OQS~.xml"| REN
        REN -->|"eligibility verification APIs<br/>(registration)"| ORCA
        ORCA --> UKE
    end
    TERM <-->|"IP-VPN /<br/>IPsec+IKE"| OQS["Online Eligibility Verification System<br/>(Payment Fund & NHI Central Organisation)"]

1. The card reader with facial recognition reads the My Number card and confirms identity (by facial recognition or PIN).
2. The eligibility verification terminal queries the Online Eligibility Verification System (operated by the Social Insurance Medical Fee Payment Fund and the National Health Insurance Organisations Central Association) over the system’s network (a carrier IP-VPN, or an IPsec+IKE connection over the internet) and receives the eligibility information as XML.
3. Between the terminal and the medical billing system, file-based integration is the norm. The result XML is placed in a shared folder, and an integration program ingests it into the medical billing system. In Nichi-Rece’s case, the official program that plays this role is onshi-tools.
4. The ingested results accumulate first in a dedicated set of eligibility-verification tables inside ORCA (tbl_onshi_*), from which the reception and patient registration workflows reflect them into patient and insurance information.

The key point is that the eligibility verification result is not written directly into the patient master, but pools first in dedicated tables. This two-stage arrangement — separating “the record of the enquiry” from “reflection into the patient master” — is the key to understanding ORCA’s eligibility verification integration (Sections 6 and 8).

2. The Scheme in Brief — What Online Eligibility Verification Is

Before getting into the systems, here is the shortest possible summary of the scheme itself.

• What it does: a mechanism for confirming a patient’s insurance eligibility online and instantly, keyed on a My Number card (a My Number health insurance card) or the symbol and number on an insurance card. Because changes of eligibility across insurers (a change of job, a house move, and so on) are reflected as of the moment of the enquiry, the greatest significance from the claims side is that it reduces returned receipts caused by eligibility errors.
• Since when: full operation began in October 2021, and from April 2023 system adoption became mandatory in principle for insurance-covered medical institutions and pharmacies. In December 2024 the issuance of new health insurance cards ended, moving to an arrangement based on the My Number health insurance card.
• What comes through besides eligibility: if the patient consents at the card reader, the medical institution can view drug information, specific health checkup information, and treatment information. The scope has since widened to eligibility verification for medical assistance (public assistance) and the linkage of local authority medical expense subsidy information (PMH: Public Medical Hub).

Although it is named “eligibility verification”, the way to see where it stands today is that it is becoming a trunk line for medical information exchange in which eligibility is merely the entry point and treatment information flows through as well. How this “widening scope” shows up in the medical billing system’s code is laid out as a chronology in Section 7.

3. Between Terminal and Billing System — The OQS File Integration Interface

How is the interface inside the medical institution — between the eligibility verification terminal and the medical billing system (or the electronic medical record system) — actually connected?

The government’s published materials for system vendors set out several approaches for connecting existing systems to the Online Eligibility Verification System: file-based integration via an integration application, plus web application integration, facial recognition integration, and Web API integration. The central one, file-based integration, is roughly speaking the classic but dependable arrangement of “put an XML file with an agreed name into an agreed folder, and an answer XML file comes back”.

Nichi-Rece follows this approach. ORCA’s official “Nichi-Rece online eligibility verification” page gives the following naming for the files exchanged with the eligibility verification terminal:

• Request: OQSsiquc01req_Oxxxxxxxxxxxx.xml
• Result: OQSsiquc01res_Oxxxxxxxxxxxx.xml

and these are passed back and forth through a shared folder. Handling this file exchange and the ingest into Nichi-Rece is the officially supplied onshi-tools, available in Ubuntu and Windows editions (tools for monitoring the ingest service and for checking the environment are published alongside it).

This “OQS” vocabulary also surfaces in ORCA’s published source. For example, the response definition record/xml_onlinequares1.db for the API that assembles and returns enquiry request data for the integration program (onlinequa1, which we look at in Section 4) contains fields such as InsurerNumber, InsuredCardSymbol, QualificationConfirmationDate, and LimitApplicationCertificateRelatedConsFlg (the consent flag related to the certificate of maximum copayment). The XML field names on the Online Eligibility Verification System’s side run straight through to the medical billing system’s API. For anyone building an integrating system, that is a welcome design: you can cross-reference the government’s specifications and ORCA’s source using the same vocabulary.

4. The Receiving Side in ORCA — Counting the 20 Eligibility-Verification APIs from the Source

Now let us count the receiving side in ORCA. Using the same method as last time, picking up bindapi declarations from the LD definitions (lddef/*.ld) in the 5.2 series source gives 20 eligibility-verification endpoints spread across three LD files. The function names are transcriptions of the “component name” written in the header of the responsible COBOL program.

(Creation dates are taken from the creation-date field in each program header. The parenthetical note on onlinequa1 is our own gloss based on what the implementation does.)

This list divides into three groups by role.

1. Registration (terminal side → Nichi-Rece): onlinequa2 (facial recognition) and onlinequa3 (insurance card), plus the “registration and update” APIs for drug information, specific health checkups, treatment information, OCR images, medical assistance, and medical expense subsidies. These are the intake points that push results arriving from the eligibility verification terminal into Nichi-Rece.
2. Request assembly (integration program → Nichi-Rece): from its name, onlinequa1 looks like a “result enquiry API”, but reading the implementation shows otherwise. Given a uuid (mandatory), it reads the latest record in tbl_onshi_kaku and from it assembles and returns the content of the enquiry request (the OQS request) to be sent to the eligibility verification terminal — the insurer number, symbol and number and consent flags to use for eligibility verification, and the request file names for drug information and specific health checkup information (YZKsiquc01req_~.xml, TKKsiquc01req_~.xml, where “~” is the tail of the patient number padded with X to a fixed 20 characters). It is the API through which an integration program that has received a PushAPI enquiry instruction fetches “what to ask the terminal”, not an API that searches and returns accumulated results.
3. Retrieval (electronic medical record and similar → Nichi-Rece): the three under /api01rv2/ are APIs through which an integrating system fetches the accumulated drug, specific health checkup, and treatment information. That they sit in api01rv2, where the read APIs gather, is exactly in line with the Nichi-Rece API placement rules we saw last time.

The source also contains a definition called record/push_onlinequa.db, showing that PushAPI events for eligibility verification (Bulk_Qualification and patient_qualification) exist. Reading where they are issued from, enquiry instruction events are emitted by the enquiry screens, by the eligibility verification subroutine called from reception and patient registration (ORCSONSHI001.CBL), by the bulk appointment-patient enquiry screen (ORCGY06.CBL), and by a batch job (ORCBONSHIPUSH.CBL). In other words, this event is primarily a channel through which Nichi-Rece instructs the integration program to “go and do an eligibility verification”. The content, however, differs by issuer. The class may contain Rreq (enquiry request) but in some cases carries the value of a verification-required flag (Yes) directly, and the meaning of the uuid is not consistent either: for individual events it is the uuid of a tbl_onshi_kaku record, for bulk appointment-patient enquiries it is a job management uuid, and for the batch bulk instruction there is no uuid at all. The receiving side has to dispatch between onlinequa1 (assembling an individual request), onlinequaapp1 (bulk for appointment patients), and onlinerefall1 (bulk registration of enquiry numbers) according to the event name, the class, and the meaning of the uuid. The comment at the top of record/xml_onlinequareq1.db describes the flow in which the receiving program handling the push notification (onshi_receiver) fetches the request data via onlinequa1, and for individual events at least you can read off the full circuit: push (enquiry instruction) → onlinequa1 (assembling the request) → request file to the terminal → onlinequa2/onlinequa3 (registering the result). Conversely, the facial-recognition and insurance card result registration APIs (onlinequa2/onlinequa3) do not issue this event. Build a reception screen expecting PushAPI to give you “a notification the moment a result is registered” and you will sit waiting for a notification that never arrives — be careful (Section 9).

5. Where the Data Goes — The 13 tbl_onshi_* Tables

Where does the data received by the registration APIs go? Pulling the tables containing onshi out of the DB table list (lddef/orcadb.inc) gives 13. Just reading the names shows that the kinds of information flowing through eligibility verification are mapped directly onto them.

The two-stage arrangement described in Section 1 is clearly visible here. Data originating from eligibility verification is not written directly into the patient master (tbl_ptinf) or the insurance tables; it lands first in tbl_onshi_* — tables kept in the vocabulary of eligibility verification itself. It is a design that puts a buffer zone between the vocabulary of the national scheme (eligibility, drugs, specific health checkups, treatment information, and so on) and the internal vocabulary of the medical billing system (patient, insurance, public expense, and so on) — and you can read off how it has absorbed the scheme’s expansion (the very fact that the tables have grown to thirteen being the evidence) without breaking the schema of the billing system proper.

6. Reading tbl_onshi_kaku — What a Single Eligibility Verification Leaves Behind

Reading the central table tbl_onshi_kaku (defined in record/tbl_onshi_kaku.db) tells you concretely what a single eligibility verification records. Here are the main groups of fields.

• A bundle of UUIDs: alongside TBL_UUID (this record itself) sit AITE_UUID, OYA_UUID, KOUHI_UUID (public expense), FUJYO_UUID (medical assistance) and PMH_UUID (medical expense subsidy) — uuids pointing at related records. Eligibility verification, public expense verification, assistance verification, and subsidy information are registered as separate records and bound together into a single reception event by a chain of uuids. This is why the request-assembly API from Section 4 (onlinequa1) makes the uuid mandatory.
• The search conditions used in the enquiry (SHO_*): the insurer number, symbol, number, branch number, date of birth, and so on specified at enquiry time. These derive from the “eligibility confirmation search information” (QualificationConfirmSearchInfo) on the request side, and are a record of “what we asked about” (the insurer number and symbol/number are not printed on the face of a My Number card, so this is not “a copy of the card face”).
• The eligibility information returned (RES_*): insurer number, symbol, number, branch number, principal/dependant category, insured person’s name, and so on. This is the record of “what the eligibility verification system answered”. Because the enquiry conditions (SHO) and the results (RES) are held in separate fields, you can trace on the record any discrepancy between the symbol/number you held locally and the latest eligibility (an eligibility change from a job move, a house move, and so on).
• Result and status: processing result (RESULT_*), error code and message (ERR_*), eligibility validity (SIKAKU_YUKO), insured card classification (CARD_CLASS — derived from InsuredCardClassification, the classification of the eligibility record returned, not the type of physical card), verification timestamp, linkage to the patient number (PTID), a multiple-match flag (FUKUSU_GAITO), and so on.
• Consent-related fields: there is not one consent flag but a separate flag per information type. Drugs (YAKUZAI_DOUIFLG), specific health checkups (KENSHIN_DOUIFLG), and treatment information (SHINRYO_DOUIFLG), plus the certificate of maximum copayment (GENDO_DOUIFLG) and the certificate for specific disease treatment (SIKKAN_DOUIFLG), subdivided further down to units such as operations, diagnoses, infectious diseases, allergies, tests, and prescriptions. The “consent-based information viewing” touched on in Section 2 is implemented as table fields in a form that distinguishes what exactly is being consented to, by type.

The comments in the definition file also record when fields were added: the insurance card OCR file name field is annotated July 2022, and PMH_UUID November 2025. The table definition itself is part of the history of regulatory work we look at in the next section.

7. The Revision History Is a Chronology of the Scheme — 2020 to 2026

Two articles ago I wrote that “the revision histories in COBOL headers form a chronology of regulatory revisions”. The eligibility verification programs are the most vivid example of that. Here are the creation dates and revision histories from the Section 4 table, lined up against developments on the scheme side.

Two articles ago I wrote that “the essential difficulty of a medical billing system is sustaining regulatory compliance for decades” — and eligibility verification is that difficulty in present progressive tense. From its creation in 2020 through to 2026, an API or a table has been added almost every year. That fact is also a practical warning that eligibility verification integration must not be treated as a build-it-once-and-you’re-done integration (Section 9).

Note too that if you diff the published source monthly, expansions of this kind can be detected as differences in lddef and record around the time of the official announcements. The monthly snapshot diff monitoring proposed last time is particularly effective in the eligibility verification area.

8. Reflection into Patient Registration — The Result Does Not Become Insurance Information “As Is”

How are the results accumulated in tbl_onshi_kaku finally reflected into the patient master?

Counting the programs that reference the eligibility verification result table, the largest group by far is patient registration (cobol/orca12/) with 16 programs, with further references from reception (orca11) and the enquiry workflows. Simply picking out the section comments in ORCGP02.CBL, the central patient registration program, reveals the flow of processing.

* Online eligibility verification UID search
* Online eligibility verification data: new patient handling
* Online eligibility verification information: basic information handling
* Online eligibility verification information: address update handling
* Online eligibility verification information: insurance information handling
* Online eligibility verification information: adding maximum copayment and other public expense
* Online eligibility verification information: public expense start date check

In other words, Nichi-Rece does not mechanically overwrite with the eligibility verification result. It decomposes reflection into individual judgements within the context of patient registration — “create a new patient”, “update name and address”, “reconcile and update insurance information”, “add maximum copayment certification and public expense”, “check the validity of start dates”. The eligibility verification result is input to a decision; the authoritative source for the patient and insurance masters remains firmly with patient registration. The two-stage arrangement from Section 1 can be read as a design for exactly this division of responsibility.

The implication for anyone building an electronic medical record or reception system is clear. If you build a shortcut that reflects eligibility verification results directly into a patient master on your own side, you bypass this reconciliation logic. Reflection should go through ORCA’s own workflows (or the APIs equivalent to them).

9. Practical Points for Those Building Integrating Systems

Here are the key points when a reception system, electronic medical record system, appointment system and the like touches eligibility verification.

1. There are two interfaces. The interface to the eligibility verification terminal (OQS file integration) and the interface to the medical billing system (the Nichi-Rece API) are different things. In a Nichi-Rece configuration, onshi-tools handles the file integration and the ingest, so decide first whether your integrating system really needs to handle OQS files itself, or whether the data after ingest into Nichi-Rece is enough (retrieval APIs for drug, specific health checkup and treatment information; the ordinary patient information APIs for the reflected patient and insurance results). In most cases the latter suffices.
2. Build the uuid chain into your design. Eligibility verification, public expense verification, medical assistance, and medical expense subsidies are separate records chained by uuid (Section 6). Working out the key design that reconstructs “a single reception event” up front, from the record/ definitions in the source, pays off later.
3. Check the “meaning” of PushAPI events in the source before using them. The push_onlinequa events exist, but as far as their issue sites go the main purpose is instructing an enquiry request (Rreq); the result registration APIs (onlinequa2/onlinequa3) do not issue them. onlinequa1 is likewise not an API that returns results but one that assembles requests (Section 4). If you want coordination such as an “eligibility verified” indicator on a reception screen, you cannot assume a notification of the result’s arrival will come from Nichi-Rece. The first party to know a result has arrived is the party registering it (the integration program), so if you need that coordination, either emit a notification to your own system at the same place as the ingest path (at the point the registration completes), or design the screen on the assumption that reflection happens through Nichi-Rece’s reception and patient registration workflows.
4. Respect the consent state per information type. Drug, specific health checkup, and treatment information flow through on the basis of the patient’s consent, and tbl_onshi_kaku provides a consent flag per information type: YAKUZAI_DOUIFLG, KENSHIN_DOUIFLG, SHINRYO_DOUIFLG and others. Do not design on the basis that “if calling the retrieval API returns something, it can be used” without checking the consent state for the relevant type.
5. Design maintenance on the assumption that it grows every year. As Section 7 shows, both APIs and tables in the eligibility verification area are extended almost annually. We recommend building diff monitoring of lddef/record in the monthly source release into your operational practice, and getting into the habit of reading it as the release notes for regulatory work.
6. Start verification with the official tooling. Beyond the integration program, ORCA officially publishes verification pattern files, environment checking tools, and bulk retrieval tools for medical assistance, home-visit care and online care. Check what official verification means exist before inventing your own test data.

10. Summary

• Checking in with a My Number health insurance card is processed as a relay: card reader → eligibility verification terminal → (file integration) → integration program → medical billing system. Between the terminal and the billing system, the exchange of XML files under the OQS naming is the norm, and in Nichi-Rece the official onshi-tools bridges the two.
• The receiving side in ORCA is 20 eligibility-verification APIs (registration, request assembly, and retrieval). Eligibility verification results are not written directly into the patient master; they accumulate first in the 13 tbl_onshi_* tables, in a two-stage arrangement where patient registration holds the judgement about reconciliation and updates.
• tbl_onshi_kaku holds the search conditions used in the enquiry (SHO_*) and the eligibility information returned (RES_*) separately, letting you trace on the record any discrepancy between enquiry conditions and latest eligibility. Related records are bundled by a chain of uuids.
• The COBOL revision histories of the eligibility verification programs are a chronology of the scheme’s expansion itself, from their creation in 2020 through facial recognition, OCR, treatment information, medical assistance, PMH, and online care. Eligibility verification integration is not “build it and you’re done”; it is an area that should be designed on the assumption of maintenance that keeps up with yearly expansion.
• As ever, all of this can be confirmed as primary information from the published source. Because the vocabulary of the government’s specifications (the OQS XML field names) runs straight through to the medical billing system’s API, you can cross-reference the regulatory materials and the source in the same language.

The next article in the series is planned to cover the logic of receipt checking and assessment. We will break down what the in-house data check (ORCA’s orca41 workflow) and the computerised checks on the claims review and payment organisations’ side are each looking at — again from the source and from published materials.

11. References

• About Online Eligibility Verification (for Medical Institutions, Treatment Facilities and System Vendors) - Ministry of Health, Labour and Welfare
• Comprehensive Portal Site for Medical Institutions (technical materials for integration applications and the like)
• Nichi-Rece Online Eligibility Verification - JMA Standard Receipt Software - ORCA Project (onshi-tools, OQS file integration, verification materials)
• Online Eligibility Verification Bulk Retrieval Tool - JMA Standard Receipt Software - ORCA Project
• About the JMA Standard Receipt Software’s Support for Online Eligibility Verification - Japan Medical Association ORCA Management Organization
• Nichi-Rece 5.2 series source code (snapshot published July 2026) lddef/orca14.ld / lddef/orca71.ld / lddef/api01rv2.ld / cobol/orca14/ORAPION*.CBL / cobol/orca71/ORAPION*.CBL / record/tbl_onshi_*.db / record/xml_onlinequares1.db / record/push_onlinequa.db / cobol/orca12/ORCGP02.CBL and others — the API list, table fields, and revision history statements in this article are all based on this snapshot

Related Articles

Recent articles sharing the same tags. Deepen your understanding with closely related topics.

Related Topics

These topic pages place the article in a broader service and decision context.

Where This Topic Connects

This article connects naturally to the following service pages.

Frequently Asked Questions

Common questions about the topic of this article.

When a patient checks in with a My Number health insurance card, how does the insurance eligibility information get into the medical billing system?

Once identity has been confirmed at a card reader with facial recognition, the eligibility verification terminal queries the Online Eligibility Verification System run by the Payment Fund and the National Health Insurance Organisations, and receives the eligibility information as an XML file. The link to the medical billing system is fundamentally a file-based integration via a shared folder; in the case of ORCA (Nichi-Rece), the officially supplied integration program (onshi-tools) ingests the result files. The ingested results accumulate in the eligibility-verification tables inside Nichi-Rece (tbl_onshi_kaku and others), and are reflected into patient and insurance information by the reception and patient registration workflows.

Is insurance eligibility the only information that comes through online eligibility verification?

No, not only eligibility information. With the patient's consent, the medical institution can also view drug information, specific health checkup information, and treatment information. ORCA's source likewise provides, separately from eligibility verification results, dedicated registration APIs and tables for drug information, specific health checkup information, and treatment information (medical and dental). The scope has been widening year on year, extending to eligibility verification for medical assistance (public assistance) and to the linkage of medical expense subsidy information (PMH).

How many online eligibility verification APIs does ORCA (Nichi-Rece) have?

Counting the LD definitions in the published 5.2 series source (July 2026 snapshot) gives 20 endpoints related to online eligibility verification. They break down into registration APIs that push eligibility results and drug, specific health checkup, and treatment information into Nichi-Rece; request-assembly APIs that build and return the enquiry request data the integration program sends to the eligibility verification terminal; and retrieval APIs through which systems such as electronic medical records fetch the accumulated data. The first three were created in November 2020, and APIs have been added with every subsequent expansion of the scheme.

What should I watch out for when building an integrating system around online eligibility verification?

First, internalise the premise that the link between the eligibility verification terminal and the medical billing system is fundamentally an exchange of XML files (the integration-application approach). On top of that, in an ORCA integration you need to be aware that related records are traced through uuids by design, that registration APIs and retrieval APIs play different roles, and that the patient's consent state governs viewing of drug, specific health checkup, and treatment information. And because APIs and tables are extended almost every year through regulatory work, we recommend building diff monitoring of the monthly source releases into your operational practice.

Author Profile

Profile page for the article author.

Go Komura

Representative of KomuraSoft LLC

Focused on Windows software development, technical consulting, and investigations into failures that are difficult to reproduce.