What an ABDM V3 migration involves
Moving to ABDM V3 means changing three things at once: gateway calls move from the v0.5 paths to new V3 prefixes under /api/hiecm, hospital-initiated linking switches to a link-token flow with the record type on each care context, and ABHA (M1) calls move from the V1/V2 Health ID service to /abha/api/v3 with different encryption. Under DHIS Corrigendum 7, software not on V3 for M1, M2 and M3 has earned no incentive since July 2026.
V3 is a rewrite of the edges, not a version bump
If your HMIS, LIS or EMR went live on ABDM before 2025, it almost certainly talks to the v0.5 gateway for health records and to the V1 or V2 Health ID APIs for ABHA. Neither is a search-and-replace job. Paths change shape rather than just a number, one linking flow is replaced outright, every call needs a facility header, the record type moves into the care context, error bodies change, and the ABHA service expects a different RSA padding. Most teams find that out one failed request at a time.
This page is the map we work from. It lists each old path beside its V3 replacement, taken from the configuration of NHA’s own open-source ABDM Wrapper, which ships both versions. It collects the errors integrators have reported on the ABDM sandbox forum with the fixes that worked, and it sets out what the incentive scheme and the security audit mean for your release date. For the wider picture of milestones, consent artefacts, encryption between HIP and HIU and the sandbox exit, see our main ABDM integration services page; this one is only about the move to V3.
We do this work in your repository and your sandbox account, alongside your engineers. Radiatus is not an NHA testing agency or a WASA auditor, and we cannot speed up NHA’s reviews; we can make sure the code and the evidence are ready when they happen.
Which "version" are you on? Decoding v0.5, V1, V2 and V3
ABDM’s version labels confuse everyone, because two services carried separate numbers until V3 brought them together.
| Label you see | What it actually is | Milestone | Typical sandbox host |
|---|---|---|---|
| v0.5 | The original health-information gateway: discovery, linking, consent, data flow | M2, M3 | dev.abdm.gov.in/gateway |
| V1, V2 | The old Health ID service for creating and verifying ABHA numbers | M1 | healthidsbx.abdm.gov.in/api |
| "V1" in NHA’s wrapper | The wrapper’s own first release, which called the v0.5 gateway underneath | M2, M3 | As v0.5 |
| V3 | The current generation for both: ABHA under /abha/api/v3, gateway under /api/hiecm | M1, M2, M3 | abhasbx.abdm.gov.in, dev.abdm.gov.in/api/hiecm |
So "migrate to V3" means two migrations: the ABHA client for M1 and the gateway client for M2 and M3. They can ship separately, but DHIS only counts you as compliant when all three milestones are on V3.
Gateway calls: the v0.5 to V3 path map
These are the calls your system makes to the gateway. Left column from the wrapper’s application-v1.properties, right column from application-v3.properties, both in NHA’s ABDM Wrapper repository, read on 13 November 2026. The sandbox base moves from https://dev.abdm.gov.in/gateway to https://dev.abdm.gov.in/api/hiecm, and production from https://apis.abdm.gov.in/hiecm to https://apis.abdm.gov.in/api/hiecm.
| Purpose | Before (v0.5) | After (V3) |
|---|---|---|
| Session token | /v0.5/sessions | /gateway/v3/sessions |
| Hospital-initiated linking | /v0.5/users/auth/init, /v0.5/users/auth/confirm, then /v0.5/links/link/add-contexts | /v3/token/generate-token, then /hip/v3/link/carecontext (no patient OTP step) |
| Discovery answer (patient-initiated) | /v0.5/care-contexts/on-discover | /user-initiated-linking/v3/patient/care-context/on-discover |
| Link init and confirm answers | /v0.5/links/link/on-init, /on-confirm | /user-initiated-linking/v3/link/care-context/on-init, /on-confirm |
| New-record notice | /v0.5/links/context/notify | /hip/v3/link/context/notify |
| SMS deep link | /v0.5/patients/sms/notify2 | /hip/v3/link/patient/links/sms/notify2 |
| Scan & Share answer | /v1.0/patients/profile/on-share | /patient-share/v3/on-share |
| HIP consent acknowledgement | /v0.5/consents/hip/on-notify | /consent/v3/request/hip/on-notify |
| HIP data request answer | /v0.5/health-information/hip/on-request | /data-flow/v3/health-information/hip/on-request |
| Transfer status notice | /v0.5/health-information/notify | /data-flow/v3/health-information/notify |
| HIU consent request, status, fetch | /v0.5/consent-requests/init, /status, /v0.5/consents/fetch | /consent/v3/request/init, /consent/v3/request/status, /consent/v3/fetch |
| HIU consent acknowledgement | /v0.5/consents/hiu/on-notify | /consent/v3/request/hiu/on-notify |
| HIU data request | /v0.5/health-information/cm/request | /data-flow/v3/health-information/request |
| Bridge URL and services | /v1/bridges family | PATCH /gateway/v3/bridge/url, GET /gateway/v3/bridge-services |
Callbacks: the routes the gateway now calls on your bridge
Your bridge must answer at new paths, all under /api/v3/. If you keep the old routes alive during the switch, nothing breaks while you test; just do not register the V3 bridge URL until the new handlers are deployed.
| Event | Old route on your bridge | New route on your bridge |
|---|---|---|
| Patient discovers records | /v0.5/care-contexts/discover | /api/v3/hip/patient/care-context/discover |
| Patient starts and confirms a link | /v0.5/links/link/init, /confirm | /api/v3/hip/link/care-context/init, /confirm |
| Link token issued | /v0.5/users/auth/on-init, /on-confirm | /api/v3/hip/token/on-generate-token |
| Care contexts added | /v0.5/links/link/on-add-contexts | /api/v3/link/on_carecontext (note the underscore) |
| Consent granted or revoked (HIP) | /v0.5/consents/hip/notify | /api/v3/consent/request/hip/notify |
| Records requested (HIP) | /v0.5/health-information/hip/request | /api/v3/hip/health-information/request |
| Scan & Share profile arrives | /v1.0/patients/profile/share | /api/v3/hip/patient/share |
| Acknowledgements for notices and SMS | /v0.5/links/context/on-notify, /v0.5/patients/sms/on-notify | /api/v3/links/context/on-notify, /api/v3/patients/sms/on-notify |
| HIU consent events | /v0.5/consent-requests/on-init, /on-status, /v0.5/consents/hiu/notify, /v0.5/consents/on-fetch | /api/v3/hiu/consent/request/on-init, /on-status, /notify, /api/v3/hiu/consent/on-fetch |
| HIU data request acknowledged | /v0.5/health-information/hiu/on-request | /api/v3/hiu/health-information/on-request |
What changed besides the paths
1. Headers on every request
V3 calls carry REQUEST-ID (a new UUID per call), TIMESTAMP, X-CM-ID (sbx or abdm) and, for anything done on behalf of a facility, X-HIP-ID or X-HIU-ID. A session request in the sandbox looks like this:
POST https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions
Content-Type: application/json
REQUEST-ID: 6f1c2a9e-0d4b-4c51-9a77-3e2b8f0d9c11
TIMESTAMP: 2026-11-13T09:15:42.318Z
X-CM-ID: sbx
{"clientId": "<client id>", "clientSecret": "<secret>", "grantType": "client_credentials"}
NHA’s wrapper generates the timestamp as an ISO-8601 UTC instant with milliseconds. The same code base carries a comment that production timestamps sometimes arrive without the trailing Z, so parse leniently on the way in and format strictly on the way out.
2. One deployment, many facilities
NHA’s own migration note for the wrapper says the facility ID now travels "across" every operation: patients, discovery, linking and record fetches all name the HIP or requester. If your v0.5 build assumed one facility per bridge, this is the largest data-model change. Store the HFR facility ID against every patient link, care context and consent, and route inbound callbacks by the X-HIP-ID they carry.
3. Hospital-initiated linking without a patient OTP
Under v0.5 the hospital authenticated the patient (users/auth/init and confirm), received a link token, then added care contexts. Under V3 the HIP asks for a link token with /v3/token/generate-token, sending the ABHA address with the patient’s name, gender and year of birth, receives the token asynchronously at /api/v3/hip/token/on-generate-token, and sends it in an X-LINK-TOKEN header on /hip/v3/link/carecontext. The body names the ABHA, your patient reference and the care contexts, grouped by record type:
{
"abhaNumber": "91-0000-0000-0000",
"abhaAddress": "rajesh.k@sbx",
"patient": [{
"referenceNumber": "PT-000418",
"display": "Rajesh K",
"careContexts": [
{"referenceNumber": "OPD-2026-11-13-0042", "display": "OPD visit, 13 Nov 2026"}
],
"hiType": "OPConsultation",
"count": 1
}]
}
Illustrative values. The field names match the request classes in NHA’s wrapper (AddCareContexts and PatientCareContextHIType); check them against the current sandbox specification before you code.
4. Every linked record now declares its type
V3 asks you to say what kind of record you are linking. NHA’s migration note is explicit: the hiType travels with the care context, a visit that produced two record types is sent twice with the same reference and different hiType values, and an update uses the same call again. In the gateway body above, that means one patient entry per record type, each with its own care contexts and count. Corrigendum 7 links this to the incentive rates, which differ by record category, so a wrong hiType is now a money bug as well as a data bug.
5. Error bodies
The same NHA note says V3 errors are not consistent in shape and that the wrapper wraps them all in an errors array. Write one parser that accepts a single error object, an errors array, or a plain message, and log the raw body every time. Codes worth recognising, as listed in Eka Care’s published ABDM error mapping: ABDM-1016 (invalid timestamp), ABDM-1026 (invalid link token), ABDM-1030 (invalid request ID), ABDM-1032 (invalid header), ABDM-1035 (invalid HIP ID), ABDM-1038 (ABHA address and link token mismatch) and ABDM-1064 (a request with this request ID already exists).
6. ABHA V3: new host, new key, new padding
M1 moves from healthidsbx.abdm.gov.in/api/v2/... (for example registration/aadhaar/generateOtp) to abhasbx.abdm.gov.in/abha/api/v3/... (for example enrollment/request/otp). The V2 public key came from /v2/auth/cert and forum posts show it used with RSA PKCS#1 v1.5 padding. For V3, a public sandbox client on GitHub reports fetching the key from /v3/profile/public/certificate and finding by test that RSA/ECB/OAEPWithSHA-1AndMGF1Padding is accepted while PKCS#1 v1.5 is rejected (abha-bridge-console, a third-party project). In practice:
- Java:
Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding"). - .NET:
rsa.Encrypt(bytes, RSAEncryptionPadding.OaepSHA1). - Node.js:
crypto.publicEncrypt({key, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha1'}, buf). - PHP:
openssl_public_encrypt($data, $out, $key, OPENSSL_PKCS1_OAEP_PADDING), which uses SHA-1 for both hash and MGF1. - Python:
padding.OAEP(mgf=padding.MGF1(hashes.SHA1()), algorithm=hashes.SHA1(), label=None).
Encrypt the Aadhaar number, OTP, mobile number and password values before they leave your server, and base64-encode the result. Cache the certificate, but refetch it on the first decryption error rather than retrying blindly.
Errors integrators report on the ABDM forum, and what fixed them
Collected from threads on the ABDM sandbox forum in November 2026. Fixes are what posters or NHA’s integration support reported; confirm each against your own logs.
| What you see | Thread | Reported cause and fix |
|---|---|---|
900908 "Resource forbidden", "API Subscription validation failed" on any V3 call | 8226, 7975, 8807 | Your sandbox client ID is not yet subscribed to the V3 APIs. Integration support enables it when you give the client ID (never post the secret). Retesting before that only burns time. |
The same 900908 on /v3/token/generate-token | 8576 | V3 access for HIP linking was not enabled for that client. A third-party client also reports 403s on bridge and consent endpoints until the bridge is registered with services and an active facility. |
ABDM-1016 Invalid TimeStamp on M1 calls | 7746 | Format mismatch. The poster found enrollment/request/otp accepted yyyy-MM-dd'T'HH:mm:ss.SSS while enrol/byAadhaar wanted a space instead of the T. Build timestamps in one helper, in UTC, from an NTP-synced clock, and keep any per-endpoint exception in that helper with a link to the thread. |
| Enrolment fails with an invalid login ID, "access denied" or wrong-OTP answers | 7558, 8868 | Wrong public key or wrong cipher: V2 code reused against V3. Use the V3 certificate and OAEP with SHA-1 as above. |
| 403 or "X-Token expired" on ABHA profile calls after a mobile OTP login | 8812 | A step was missing: the poster had to call the user-verification step (profile/login/verify/user) that the mobile route needs and the Aadhaar route does not. |
| 406 "Not accepted" when downloading the ABHA card | 8697 | Send the patient’s user token in the X-token header as well as your bearer token in Authorization. |
| Link-token requests blocked after a few attempts | 8299 | The sandbox limits repeated token generation for the same patient. Generate once per ABHA address, store the token from the callback, reuse it for every care context until it expires, and rotate test ABHAs in automated runs. |
| Swagger file lacks the care-context calls | 5788 | The shared specification covered token generation only. Cross-check against the sandbox documentation, the Postman collection and NHA’s wrapper source rather than one file. |
| Callbacks never arrive although calls return 202 | Our own checklist | The bridge URL still points at the v0.5 routes, or a proxy strips the /api/v3 prefix. Call GET /gateway/v3/bridge-services and compare what is registered with what your router serves. |
DHIS, WASA and re-certification: the business side of V3
Incentives. DHIS Corrigendum 7, dated 9 April 2026 (copy published by Rajasthan’s health department), gave software companies April to June 2026 to complete V3. During that window, transactions from software not yet on V3 were paid at the lower Category 2 rate. From July 2026, neither the software company nor the facility receives anything until the software is "fully compliant with the v3 versions of M1, M2 and M3". Its Illustration 9 spells out the cost of lateness: a company compliant on 25 July 2026 earns nothing for July, and both it and its facilities are paid again from August. The corrigendum runs from April to September 2026; on 13 November 2026 we found no later corrigendum or extension, so check abdm.gov.in/dhis before you put incentive income in a plan.
WASA. The same corrigendum makes a valid web application security assessment a condition of payment: a software company’s transactions before a valid WASA report are not eligible, and payment starts from the month after the renewed certificate is submitted. A migration rewrites authentication, encryption and callback handling, which are exactly the areas an auditor tests, so line up the retest with the release rather than after it.
Re-certification. We found no NHA notice, as of 13 November 2026, saying that moving an already certified product to V3 means a fresh sandbox exit. We also found nothing saying it does not. Ask NHA integration support, in writing, three questions before you start: whether your production client is enabled for V3, whether they want V3 test evidence or a demo, and whether your current WASA certificate covers the release. Keep the answers with your release notes.
Activity. NHA’s advisory of 14 October 2026 says integrators inactive for a year or more without milestone progress are liable to have sandbox access disabled. A migration that has been "next quarter" for a year is now a risk to the sandbox account itself.
Migration checklist
- Inventory every ABDM call and callback in the code base, with the version each one uses today. Most products we see are mixed.
- Ask integration support to enable V3 for your sandbox client; confirm with a session call and one ABHA call before writing more code.
- Put base URLs,
X-CM-ID, the bridge URL and the ABHA host in configuration, one set per environment. - Add the facility ID to the data model: patient links, care contexts, consents, transfers.
- Build one header helper (request ID, timestamp, CM ID, facility header) and one error parser that accepts every shape.
- Rewrite hospital-initiated linking around the link token: request, callback, cache,
X-LINK-TOKEN, care contexts withhiType. - Map every HMIS document type to an ABDM
hiType, and decide how visits with several record types are sent. - Move ABHA flows to
/abha/api/v3: new certificate, OAEP-SHA-1 encryption, the login sequences for each mode, andX-tokenhandling. - Add the
/api/v3/callback routes beside the old ones; deploy, then register the V3 bridge URL. - Make every callback idempotent on request ID and transaction ID, and acknowledge before calling the HMIS.
- Run the test plan below, then NHA’s current test cases, and file the evidence.
- Book the WASA retest, switch production configuration per facility, and remove the v0.5 routes once traffic has stopped.
Test plan for a V3 migration
| Area | Cases to run | Pass when |
|---|---|---|
| M1 enrolment | Aadhaar OTP enrolment, mobile update, ABHA address creation, existing-ABHA login by each mode you support, card download | Every mode works end to end; the card renders; OTP retries are rate-limited on your side too |
| Scan & Share | Profile share for a new patient, a known patient and a duplicate scan | Token issued once; no duplicate patient records |
| Hospital-initiated linking | One care context, several, one visit with two hiType values, an update, an expired link token | on_carecontext confirms each; expired token is refreshed once, not looped |
| Patient-initiated linking | Discovery by ABHA, by demographics, no match, several matches, wrong OTP | Correct care contexts offered; no data leaks on a weak match |
| Consent and transfer (HIP) | Grant, revoke, expiry, date range narrower than the data, unsupported hiType | Only consented records are sent; transfer notice matches what was sent |
| HIU | Request, approve, deny, expiry, decrypt and display each record type | Fetched data deleted on schedule; denied consents show clearly |
| Resilience | Duplicate callbacks, callbacks out of order, gateway timeout, clock skew of a few minutes | No double actions; retries back off; skew is caught by monitoring |
| Multi-facility | Two HFR facilities on one deployment, callbacks for each | Every record, consent and log line carries the right facility |
| Security | Secrets out of logs, OTP and token handling, callback authentication, dependency scan | Nothing for the WASA auditor to find that you could have found first |
Keep the request and response IDs from every run. When a case fails in NHA’s testing, those IDs are the fastest way to a useful answer from support.
How we help with the move to V3
Three ways to engage, each scoped after we have read your code and logs. Credentials and certificates stay in your organisation’s name.
V3 readiness review
The problem
You know you are behind on V3 but not by how much, and nobody can say what it will cost.
How we do it
We read your ABDM code, configuration and recent gateway logs, list every call and callback by version, and return a written plan: what changes, in what order, the data-model work for multiple facilities, the effort in engineer-days, and the questions to put to NHA before you start.
What you get
- Call and callback inventory by version
- Gap list against V3
- Effort and sequence
- Questions for NHA integration support
Migration build with your team
The problem
Your engineers own the product but are tied up, and the DHIS clock keeps running.
How we do it
We do the migration in your repository on a branch your team reviews: header and error helpers, the link-token flow with hiType, ABHA V3 with the new encryption, the new callback routes, idempotency and per-facility configuration. Old and new routes run side by side until the switch.
What you get
- Merged V3 code with tests
- Per-facility switch in configuration
- Updated runbook
- Handover session
Test evidence and WASA fixes
The problem
The code is migrated, but you are not sure it will pass NHA’s cases or the security retest.
How we do it
We run the test plan above and NHA’s current test cases against your sandbox build, fix what fails, close findings from your auditor’s report, and assemble the evidence pack your team submits.
What you get
- Test run report with request IDs
- Fixed defects
- Closed WASA findings
- Evidence pack
Typical effort for an ABDM V3 migration
Illustrative ranges in engineer-days for a web HMIS already live on v0.5 and ABHA V2 with an API layer, confirmed after the readiness review. They exclude NHA’s and the auditor’s time.
Readiness review
Inventory, logs, gap list, plan and questions for NHA.
Foundations
Configuration per environment, header and error helpers, facility ID through the data model.
M1 on ABHA V3
Enrolment and login modes, new certificate and encryption, card, Scan & Share answer.
M2 on V3
Link-token flow, hiType mapping, new callbacks, consent and transfer routes, idempotency.
M3 on V3
Consent requests and events, data request and receipt on the new routes.
Testing and evidence
Our test plan, NHA’s current cases, fixes and the evidence pack.
WASA fixes and cutover
Findings from the retest, production switch per facility, removal of old routes.
Sources behind this page
Read on 13 November 2026. ABDM changes paths and rules without much notice, so we re-read them at the start of every migration.
NHA ABDM Wrapper
Ships both v0.5 and V3 configurations side by side; our path maps come from its properties files and callback constants.
NHA “V1 to V3 Migration doc”
The wrapper team’s list of changes: facility ID everywhere, hiType in care contexts, error format.
DHIS Corrigendum 7
The V3 window, the July 2026 cut-off and the WASA condition, dated 9 April 2026.
Sandbox activity advisory
NHA’s 14 October 2026 notice on inactive integrators.
ABDM sandbox forum
Threads cited above for each error, with the fixes reported there.
Eka Care ABDM error mapping
A published list of ABDM error codes and meanings from an integrator’s documentation.
Tools we use alongside it
- Postman
- Bruno
- BouncyCastle
- OpenSSL
- HAPI FHIR
- HL7 FHIR Validator
- Docker
- OpenTelemetry
Facts, versions and vendor details checked 13 November 2026.
Guides and related pages
Guides
Technologies
Glossary
Where we work
Questions about ABDM V3 migration
v0.5 is the original health-information gateway used for discovery, linking, consent and data flow (M2 and M3). V3 replaces it with new paths under /api/hiecm, a facility header on every call, a link-token flow for hospital-initiated linking, the record type (hiType) on each care context and a different error format. V3 also replaces the V1 and V2 ABHA APIs used for M1.
For incentives, yes in effect: under DHIS Corrigendum 7, from July 2026 neither a software company nor its facilities receive DHIS incentives until the software is on V3 for M1, M2 and M3. Separately, NHA’s own reference code and documentation now target V3, and older versions should be treated as legacy. Ask NHA integration support about any deadline for switching off older APIs in production.
We found no NHA notice, as of 13 November 2026, that says so either way. Ask NHA integration support in writing whether your production client is enabled for V3, whether they want V3 test evidence or a demo, and whether your WASA certificate covers the release, and keep the answers.
V2 code typically used RSA with PKCS#1 v1.5 padding and the key from /v2/auth/cert. For V3, integrators report that the key comes from /v3/profile/public/certificate and that RSA/ECB/OAEPWithSHA-1AndMGF1Padding is accepted while PKCS#1 v1.5 is rejected. Reusing V2 code against V3 produces invalid login ID, access denied or wrong-OTP errors.
It is the gateway saying that your client is not subscribed to the API you called, usually shown as Resource forbidden or API Subscription validation failed. Forum threads show it is fixed by NHA integration support enabling V3 for the sandbox client ID. Share the client ID, never the secret.
Send the TIMESTAMP header as a UTC ISO-8601 value with milliseconds from a clock synced by NTP, generated in one helper. One forum poster found that an M1 enrolment endpoint expected a space instead of the T separator, so if a single endpoint still rejects the value, test that variant and keep the exception in the helper.
For a web HMIS already live on v0.5 and ABHA V2, we typically see about 45 to 90 engineer-days across review, foundations, M1, M2, M3, testing and WASA fixes. Calendar time depends on V3 access being enabled, NHA testing slots and the auditor.
The latest instrument we found is Corrigendum 7, which covers April to September 2026. On 13 November 2026 we found no later corrigendum or extension. Check the DHIS page on abdm.gov.in before counting on incentive income.
Behind on ABDM V3?
Tell us which milestones you run, which API versions they use today, how many facilities are on your product and any error codes you are stuck on. A senior engineer will reply with what we would check first and a typical effort range, confirmed after a readiness review. Or book a free 30-minute call.






Compliance-first delivery