M4 operations and fields

Every Milestone 4 call for the HPR and the HFR, with its parameters, its codes and the rules that apply to it. Two operations carry a published path and have their own pages under APIs. The rest are here.

Session token​

The first call you make. Same session pattern as M1, issued by the HIE-CM gateway.

Both hosts are listed under Base URLs.

Headers:

Request body:

{
  "clientId": "<CLIENT_ID_FROM_SANDBOX_SIGNUP>",
  "clientSecret": "<CLIENT_SECRET_FROM_SANDBOX_SIGNUP>",
  "grantType": "client_credentials"
}

Response shape:

{
  "accessToken": "<JWT>",
  "expiresIn": 1200,
  "refreshExpiresIn": 1800,
  "refreshToken": "<JWT>",
  "tokenType": "bearer"
}

Read expiresIn from your own response rather than hard coding a value.

Every later call carries this token. The Authorization header value is the word Bearer, one space, then the access token.

Encryption​

Three fields below are sent encrypted: the mobile number in mobile match, the OTP in the HPR mobile login, and the email and password in create HPID. All use the same public certificate, so fetch it once.

The cipher is RSA/ECB/PKCS1Padding, under this certificate and no other. M1 uses RSA-OAEP with SHA-1 under the ABHA certificate, so an M1 encryption path reused here produces a value the NHPR cannot read.

Check the response format before you parse it. Where it arrives as bare base64 rather than beginning -----BEGIN PUBLIC KEY-----, add the PEM armour yourself, wrapping at 64 characters per line, as the ABHA certificate call requires.

HPID creation​

Nine calls, in order. Method and path are not yet published for these.

Codes for create HPID​

Category:

Subcategory, as used by create HPID:

Role:

Getting an HPR token​

The HPR token is not the gateway access token: it represents the professional, not your client. There are three ways to get one, and all three carry the gateway access token in the Authorization header as well.

Login by password​

One call. The professional supplies their HPR ID and password.

{
  "idType": "hpr_id",
  "domainName": "@hpr.abdm",
  "hprId": "<USERNAME_CHOSEN_AT_CREATE_HPID>@hpr.abdm",
  "password": "<PASSWORD_THE_PROFESSIONAL_SET>"
}

The token in the response is the HPR token. The HPR Swagger page at https://apihspsbx.abdm.gov.in/v4/int/swagger-ui/index.html?urls.primaryName=HPR lets you try the call in a browser.

The sample expiresIn is 1739710198, which reads as a Unix timestamp rather than seconds. The other two login flows return 1800. The call has not been run, so which reading is right is unknown.

Login by mobile OTP​

Four calls.

The verify OTP path is not yet published: the published value repeats the send OTP path, loginViaMobileSendOTP. Take the verify endpoint from the HPR Swagger page.

Step 1 response:

{
  "txnId": "061c660d-8752-4639-945d-e77a7ea6f564",
  "mobileNumber": null
}

Step 3 response, listing the HPR IDs linked to that mobile number:

{
  "txnId": "fc6d879c-e535-4ff1-9443-5dc6031efcc1",
  "mobileLinkedHpIdDTO": [
    {
      "hprIdNumber": "**-****-0326-3829",
      "name": "Test",
      "hprId": "*****@hpr.abdm"
    }
  ]
}

Step 4 response, which is the HPR token:

{
  "token": "<HPR_TOKEN_JWT>",
  "expiresIn": 1800,
  "refreshToken": "<REFRESH_JWT>",
  "refreshExpiresIn": 10800
}

Login by Aadhaar OTP​

Two calls.

Step 1 returns { "txnId": "..." }. Step 2 returns the same token object as step 4 of the mobile flow.

Register professional​

The one HPR write call with a published path.

The hprToken from create HPID goes in the payload, not the header. The gateway access token goes in the Authorization header.

The payload is grouped into personal information, communication address, registration data, qualification data and current work details. Selected fields and their rules:

Three conditional rules apply separately:

• When chooseWorkStatus is 1 or 2, category inside personalInformation must be C for central government or S for state. When it is 0, send an empty string. Mandatory either way.
• When chooseWorkStatus is 1 or 2, facilityDeclarationData is mandatory.
• Without facilityId, then facilityName, facilityAddress, facilityPincode, state, district and facilityType are mandatory. With it, facilityDepartment and facilityDesignation are mandatory.

Degree codes​

Attachments​

Every attachment in the payload uses the same shape:

{
  "fileType": "image/jpeg",
  "data": "<BASE64_ENCODED_FILE>"
}

Accepted file types are JPEG, PNG and PDF, sent in fileType. Read the exact value back from your own response rather than hard coding one.

A note on nurses​

The SMD ID identifies doctors only. Searching nurse colleges by SMD returns a null college or university name. That is expected, not a failure. For nurses, SMD is always null.

The other professional calls​

Upload rules: profile photo 1 MB or smaller, other documents 5 MB or smaller, accepted types png, jpeg, jpg and PDF. The document types are profilePhoto, degreeCertificate, registrationCertificate, proofOfWorkCertificate, proofOfNameChangeRegCertificate and proofOfNameChangeQualCertificate. Which identifier you send as document_id depends on the type:

HFR onboarding​

Five calls, in order. Method and path are not yet published; the parameter tables are.

1. Deduplicate search​

Run this before you create anything, so you do not create a second record for a facility that already exists.

LGD codes come from the Local Government Directory at lgdirectory.gov.in, and from the LGD lookup calls below.

2. Basic facility information​

Creates the record and returns a tracking ID that acts as the facility ID for every later call. Needs an HPR token in the header, generated from an HPR ID and password.

Mandatory fields:

Optional fields include facilityRegion (R rural or U urban), the contact block, the address proof block and abdmCompliantSoftware.

3. Additional information​

The tracking ID plus yes or no flags, each answered with a code from master data type=GENERAL-INFO-OPTIONS: hasDialysisCenter, hasPharmacy, hasBloodBank, hasCathLab, hasDiagnosticLab, hasImagingCenter. With an imaging centre, servicesByImagingCenter carries a service code and equipment count per service.

It also carries the facility's existing scheme identifiers, all optional: nhrrId, nin, abpmjayId, rohiniId, echsId, cghsId, ceaRegistration and stateInsuranceSchemeId.

4. Detailed information​

The tracking ID plus the sections that apply, which depends on the facility type, the type of service and the system of medicine. The rules:

• Specialities are required for most facility types, but not for blood bank, cath laboratory, diagnostic laboratory, dialysis centre, imaging centre or pharmacy.
• Medical infrastructure is mandatory for IPD and day care. For IPD at least one bed count must be greater than zero; for day care at least one day care bed count must be.
• For OPD where the system of medicine is dentistry, countDentalChairs is mandatory.
• For imaging centre, diagnostic laboratory, blood bank and pharmacy, medical infrastructure is not required.
• totalNumberOfBeds must be equal to or greater than the sum of the individual bed counts.
• The pharmacy, blood bank, diagnostic and imaging sections are each required when the facility is of that type or offers that service.

5. Submit facility​

Needs an x-hpird-auth token in the header. Until you make this call the facility stays in draft.

Bridge linkage​

Links one facility to one or more bridges. Path not in text.

HFR search and master data​

Paths are not yet published. Two appear inside other parameter descriptions: v1.5/facility/fetchfacilitytype and /v1.5/facility/get-specialities.

HPR master data​

There are 17 master data calls, in four groups:

• Qualifications: system of medicine, medical councils, languages, universities, courses, colleges
• Geography: countries, states, districts, sub districts
• Nursing bodies: nurse affiliated boards, nurse councils, nurse college by state, affiliated board by state councils
• Classification: get all ministry, HPRID categories, HPRID subcategories

The only master data paths the document carries in text:

Three appear as complete URLs: countries, states and nurse affiliated boards. The other four appear only as path fragments inside field descriptions, so the /v4/int/ prefix on those is our reading of the base URL, not a quote.

Path variables are optional. Drop one and you get the full list. Countries returns:

{
  "id": 356,
  "alpha_2_code": "IN",
  "alpha_3_code": "IND",
  "enShortName": "India",
  "nationality": "Indian"
}

Two calls take parameters:

A published system of medicine table carries a twelfth row, 12 Registered Pharmacist, filed under nurse. Fetch the list from the master API rather than copying either table.

Error codes​

There are 150 error codes, all prefixed HIS-, in six groups.

The full list is in the sandbox documentation for the healthcare professional registry.

Where to go next​

• The interactive reference: M4 API reference.
• The order of calls, as diagrams: M4 user journeys.
• A path missing here that you need now: ask on support.