Video summary

#ABDM M1 milestone API Integration Workflow

Main summary

Key takeaways

Technology

Summary of the video (Milestone 1 ABDM API Integration Workflow)

The video walks through the API workflow and integration steps for ABDM Milestone 1, focusing on how to create, verify, and retrieve ABHA (Ayushman Bharat Digital Mission identifiers and profiles), and how to use Scan & Share to exchange patient profile data securely between systems.

1) ABDM ecosystem basics (concepts + roles)

  • ABHA / ABHA Address: a unique identifier (username) created/selected by the citizen; used for sign-in to the health information exchange.
  • ABHA Number: described as a randomly generated 14-digit identifier to uniquely recognize and link patient records across systems.
  • Consent Manager (HI ECM): a consent management system enabling controlled sharing of personal health records.
  • Health Information Provider (HIP): entities (hospitals, labs, clinics, pharmacies, etc.) that create medical data and participate in the federated record system.
  • Health Information User (HIU): entities that request access to patient digital health information from HIPs (hospitals, companies, analytics, insurers, researchers, government, etc.), typically for a limited time with consent.
  • Sandbox: an isolated testing environment to run integration safely without affecting production.

2) Where to find integration guidance (tutorial workflow)

The speaker instructs viewers to use the ABDM sandbox website documentation:

  • Documentation tab → Milestones: M1, M2, M3
  • Postman collection tab → updated collections synced with documentation
  • Test cases tab → required cases to comply with integration rules
  • FAQ tab → common technical/functional questions for M1–M3
  • Upcoming sessions / Resources tab → webinars and recorded material

3) UI walkthrough (ABHA creation)

Key UI behaviors described:

  • Users can create/login using ABHA number.
  • During ABHA creation, options include:
    • Create ABHA using Aadhaar (Adar) (presented as the demo path)
    • Create ABHA using driving license
  • Consent collection is required in the flow.
  • OTP step:
    • OTP is sent to a registered mobile number (shown as partially masked)
    • Users can resend OTP
    • Emphasis on validation + clear success/failure messaging
  • Privacy/security UX notes:
    • Aadhaar input is masked, with suggested show/hide toggle
  • ABHA card generation includes fields like:
    • ABHA number, ABHA address, DOB, gender, mobile, photo
    • Option to download ABHA card
    • If already enrolled, show a message and option to view profile

4) Postman setup (integration tooling)

  • Create a dedicated Postman workspace (recommended team collaboration option: “everyone in team”).
  • Import the downloaded ABDM Postman collections to organize requests for development/testing.

5) API walkthrough: ABHA enrollment via Aadhaar (Milestone 1)

The workflow is presented as sequential API calls for enrollment, using encryption + session token + OTP verification + profile creation.

A. Retrieve public key (for encryption)

  • Endpoint: .../get public key (described as v? /outsert with GET)
  • No auth headers/body required
  • Returns a public key used for data encryption
  • Important: the key expires after ~3 months, so it must be refreshed.

B. Create a session (get access token)

  • Endpoint: v3 /sessions
  • POST request
  • Requires custom headers:
    • request ID
    • timestamp (ISO format)
    • xcm ID = SBX (sandbox identifier)
  • Body includes OAuth-style credentials:
    • client_id
    • client_secret
    • grant_type (shown as using client credentials)
  • Returns:
    • access token for subsequent calls
    • Token type mentioned as “Bearer” style (token type referenced as “Bea/ Bear” in subtitles)
  • Session expiry: 1200 seconds
  • If required headers are missing/incorrect → 403 Forbidden.

C. Enrollment step-by-step (OTP request + verify + profile creation)

  1. Request OTP (Aadhaar OTP)

    • POST with Bearer token authorization
    • Body contains:
      • scope = abha enroll
      • login_hint = encrypted Adar/Aadhaar
      • otp_system = Adar

  2. Encrypt Aadhaar/OTP values

    • Demo tool described:
      • Use RSA encryption with:
        • RSA key type
        • public key retrieved earlier
        • algorithm using SHA1 + MGF1 padding
      • Output is encrypted Aadhaar/OTP used in API bodies

  3. Verify OTP (link Aadhaar to ABHA enrollment)

    • POST with Bearer token
    • Body includes OTP verification block:
      • OTP method = OTP
      • includes txn ID from request OTP response
      • OTP value = encrypted OTP
      • mobile field included to ensure OTP destination
      • code = abha enrollment
      • protocol version stated as 1.4
    • Handles “account already exists” vs “new user” behaviors.

  4. Mobile update: send OTP (for updating communication mobile)

    • POST (same endpoint as OTP flow but different body fields)
    • Body changes:
      • scope includes mobile verify
      • login_hint = encrypted mobile
      • otp_system updated to follow ABDM process
    • Expects 200 OK + txn ID, OTP sent to entered mobile.

  5. Mobile update: verify OTP

    • POST with OTP verification:
      • scope includes mobile verify
      • OTP value = encrypted OTP
    • On success → mobile linked and ABHA details returned (as described).

  6. Email verification

    • POST to verify email via a verification link
    • Uses X-token from OTP verification response
    • Body includes:
      • emailing query (email verification query)
      • login_hint = encrypted email
      • otp_system = abdm

  7. Fetch ABHA address suggestions

    • GET request
    • Requires txn/request headers (no body)
    • Errors mapped:
      • invalid access token → “unclassified authentication failure”
      • invalid txn ID → “invalid transaction ID”

  8. Confirm ABHA address

    • POST
    • Body includes:
      • txn ID
      • chosen ABHA address
      • preferred = one to indicate selection

  9. Retrieve full profile

    • GET profile details
    • Uses x-token from token response section
    • Returns ABHA number/address, name, DOB, mobile, gender, photo, full address, creation date

  10. Download ABHA card

    • Uses “account / ABHA card” endpoint
    • Returns the card in response

6) ABHA verification methods (authentication options)

The video lists five verification scenarios for ABHA authentication:

  1. Adhaar OTP
  2. ABHA OTP
  3. Password
  4. Mobile number verification
  5. Adhaar verification (Adar)

It then demonstrates the Adhaar OTP-based login/verification flow:

  • Uses the same ABHA verification endpoint but changes request body fields:
    • scope: abha login + Adar verification
    • login_hint: encrypted Aadhaar or encrypted ABHA/mobile depending on method
    • otp_system: set according to the method (Adar vs abdm)
  • Verification uses:
    • txn ID from OTP send response
    • encrypted OTP
  • Emphasizes that requests require validating headers (request ID, timestamp, access token) and passing txn ID + encrypted OTP.

7) Profile management & benefit APIs (overview)

The video mentions additional APIs and that some are handled earlier in the flow:

  • Government integrator benefit APIs (covered in a separate video):

    • link & link abha benefit
    • benefit search
    • demo authentication
    • find ABHA and child ABHA

  • Forgot ABHA / enrollment retrieval APIs:

    • recover via mobile OTP or Adhaar OTP
    • enrollment retrieval especially for cases where ABHA was created with driving license

  • Profile management APIs (mentioned as re-usable):

    • get profile details
    • get QR code
    • update user photo
    • download ABHA card
    • update registered email
    • update mobile number
    • eKYC (electronic KYC) verification

8) Scan & Share functionality (patient data sharing via QR)

Purpose

Allow a patient to share basic profile information with healthcare facilities via QR code and consent/token flow.

HIP/Facility registration prerequisites (important steps)

Before Scan & Share:

  • Register the healthcare facility in HIP registry / facility registry
  • Steps include:
    • Create Health Professional ID (HP ID)
    • Register the facility in HFR (health facility registry)
  • Mentions references to production registry URL and sandbox registry URL (noted as nh... and hp... domains)
  • Emphasis: facility registration is required to participate and issue/handle health records.

API flow described

  1. Create session (already covered earlier)
  2. Update bridge URL
    • POST with access token
    • Requires xcm ID = SBX along with request ID/timestamp
    • Returns 202 Accepted
  3. Bridge service API (verify callback/registration)
    • GET with access token
    • Confirms registered HIP/callback URLs

QR code generation & token validity

  • Example uses:
    • generate QR using HIP ID + counter code
    • download and scan QR using a PHR app
  • Scanning returns facility details to the app and generates a token:
    • token validity: 30 minutes (sandbox noted as 60 minutes, configurable)

Callback + data retrieval (10-second rule)

  • On scan, the facility receives callback via Share API
  • Callback includes:
    • request ID
    • patient ABHA number and ABHA address
  • Facility must call profile-on-share API using:
    • the request ID and ABHA address (copied from callback)
  • Constraint:
    • must complete within 10 seconds, otherwise error is returned.
  • Notable claim:
    • during this step, ABHA address does not need encryption (per the subtitles).

Consent UI in PHR app

  • After QR scan, a popup requests consent (“I agree”).
  • If facility processing takes too long:
    • popup message indicates the facility is taking longer → try again later.

Main speakers/sources

  • Speaker/host: the unnamed presenter conducting the ABDM integration walkthrough (only “hello everyone…” intro is present).
  • Source references used in the video:
    • ABDM sandbox site / ABDM documentation
    • ABDM webinars and recorded sessions
    • Support contact: integration.support.nh.gov.in (mentioned)
  • No other specific individual names are provided in the subtitles.

Original video