Skip to content
Healthcare integration · ABDM V3

ABDM V3 API migration: from v0.5 and ABHA V1/V2 to V3 without losing a month

A working guide for teams whose ABDM integration predates V3: every gateway path that moved, the new linking flow, headers, error bodies and ABHA encryption, the errors other integrators hit on the ABDM forum and how they fixed them, and what DHIS and WASA mean for your release plan.

Laptop screen showing source code in a dark-themed code editor
At a glance
  • Old-to-new path mapCalls and callbacks, v0.5 to V3
  • Nine forum errors, with fixesFrom the ABDM sandbox forum
  • DHIS stops without V3Corrigendum 7, from July 2026
  • Checklist and test planFor M1, M2 and M3

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.

For teams already on ABDM

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 seeWhat it actually isMilestoneTypical sandbox host
v0.5The original health-information gateway: discovery, linking, consent, data flowM2, M3dev.abdm.gov.in/gateway
V1, V2The old Health ID service for creating and verifying ABHA numbersM1healthidsbx.abdm.gov.in/api
"V1" in NHA’s wrapperThe wrapper’s own first release, which called the v0.5 gateway underneathM2, M3As v0.5
V3The current generation for both: ABHA under /abha/api/v3, gateway under /api/hiecmM1, M2, M3abhasbx.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.

PurposeBefore (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 familyPATCH /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.

EventOld route on your bridgeNew 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 seeThreadReported cause and fix
900908 "Resource forbidden", "API Subscription validation failed" on any V3 call8226, 7975, 8807Your 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-token8576V3 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 calls7746Format 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 answers7558, 8868Wrong 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 login8812A 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 card8697Send 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 attempts8299The 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 calls5788The 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 202Our own checklistThe 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

  1. Inventory every ABDM call and callback in the code base, with the version each one uses today. Most products we see are mixed.
  2. Ask integration support to enable V3 for your sandbox client; confirm with a session call and one ABHA call before writing more code.
  3. Put base URLs, X-CM-ID, the bridge URL and the ABHA host in configuration, one set per environment.
  4. Add the facility ID to the data model: patient links, care contexts, consents, transfers.
  5. Build one header helper (request ID, timestamp, CM ID, facility header) and one error parser that accepts every shape.
  6. Rewrite hospital-initiated linking around the link token: request, callback, cache, X-LINK-TOKEN, care contexts with hiType.
  7. Map every HMIS document type to an ABDM hiType, and decide how visits with several record types are sent.
  8. Move ABHA flows to /abha/api/v3: new certificate, OAEP-SHA-1 encryption, the login sequences for each mode, and X-token handling.
  9. Add the /api/v3/ callback routes beside the old ones; deploy, then register the V3 bridge URL.
  10. Make every callback idempotent on request ID and transaction ID, and acknowledge before calling the HMIS.
  11. Run the test plan below, then NHA’s current test cases, and file the evidence.
  12. 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

AreaCases to runPass when
M1 enrolmentAadhaar OTP enrolment, mobile update, ABHA address creation, existing-ABHA login by each mode you support, card downloadEvery mode works end to end; the card renders; OTP retries are rate-limited on your side too
Scan & ShareProfile share for a new patient, a known patient and a duplicate scanToken issued once; no duplicate patient records
Hospital-initiated linkingOne care context, several, one visit with two hiType values, an update, an expired link tokenon_carecontext confirms each; expired token is refreshed once, not looped
Patient-initiated linkingDiscovery by ABHA, by demographics, no match, several matches, wrong OTPCorrect care contexts offered; no data leaks on a weak match
Consent and transfer (HIP)Grant, revoke, expiry, date range narrower than the data, unsupported hiTypeOnly consented records are sent; transfer notice matches what was sent
HIURequest, approve, deny, expiry, decrypt and display each record typeFetched data deleted on schedule; denied consents show clearly
ResilienceDuplicate callbacks, callbacks out of order, gateway timeout, clock skew of a few minutesNo double actions; retries back off; skew is caught by monitoring
Multi-facilityTwo HFR facilities on one deployment, callbacks for eachEvery record, consent and log line carries the right facility
SecuritySecrets out of logs, OTP and token handling, callback authentication, dependency scanNothing 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

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
Effort

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.

3–5 days

Readiness review

Inventory, logs, gap list, plan and questions for NHA.

5–10 days

Foundations

Configuration per environment, header and error helpers, facility ID through the data model.

8–15 days

M1 on ABHA V3

Enrolment and login modes, new certificate and encryption, card, Scan & Share answer.

12–25 days

M2 on V3

Link-token flow, hiType mapping, new callbacks, consent and transfer routes, idempotency.

6–12 days

M3 on V3

Consent requests and events, data request and receipt on the new routes.

6–12 days

Testing and evidence

Our test plan, NHA’s current cases, fixes and the evidence pack.

3–10 days

WASA fixes and cutover

Findings from the retest, production switch per facility, removal of old routes.

Senior engineers firstYour first call is with someone who will do the work, not a sales script.
You own everythingCode, configuration, reports and documentation stay in your accounts and are handed over.
We run our own products15 live platforms we build and operate, so we feel production pain too.
Honest about fitIf a cheaper route or another provider suits you better, we will say so.
FAQ

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.

Last updated