HPR

hpr_dto

GenerateAadhaarOtpRequestSchema

Bases: BaseModel

Request schema for generating Aadhaar OTP.

Attributes:

Name	Type	Description
aadhaar	str	Aadhaar number.

GenerateAadhaarOtpResponseSchema

Bases: BaseModel

Response schema for generating Aadhaar OTP.

Attributes:

Name	Type	Description
txnId	str	Transaction ID.
mobileNumber	str	Mobile number.

VerifyAadhaarOtpRequestSchema

Bases: BaseModel

Request schema for verifying Aadhaar OTP.

Attributes:

Name	Type	Description
domainName	str	Domain name.
idType	str	ID type.
otp	str	OTP.
restrictions	Optional[str]	Restrictions (optional).
txnId	str	Transaction ID.

validate_required_field classmethod

validate_required_field(value: str, info: ValidationInfo) -> str

Reusable function to validate required fields.

VerifyAadhaarOtpResponseSchema

Bases: BaseModel

Response schema for verifying Aadhaar OTP.

Attributes:

Name	Type	Description
txnId	str	Transaction ID.
mobileNumber	Optional[str]	Mobile number.
profilePhoto	Optional[str]	Profile photo.
gender	str	Gender.
name	str	Name.
email	Optional[str]	Email.
pincode	str	Pincode.
birthDate	Optional[str]	Birth date.
careOf	Optional[str]	Care of.
house	Optional[str]	House.
street	Optional[str]	Street.
landmark	Optional[str]	Landmark.
locality	Optional[str]	Locality.
villageTownCity	Optional[str]	Village/Town/City.
subDist	Optional[str]	Sub-district.
district	str	District.
state	str	State.
postOffice	Optional[str]	Post office.
address	str	Address.

CheckAccountExistRequestSchema

Bases: BaseModel

Request schema for checking account existence.

Attributes:

Name	Type	Description
txnId	str	Transaction ID.
preverifiedCheck	bool	Whether to check for preverified account.

HprAccountResponse

Bases: BaseModel

Response schema for checking account existence when HPR ID is present.

Attributes:

Name	Type	Description
token	str	Token.
hprIdNumber	str	HPR ID number.
hprId	str	HPR ID.
categoryId	int	Category ID.
subCategoryId	int	Sub-category ID.
new	bool	Indicates if the account is new.
categoryName	str	Category name.
categorySubName	str	Category sub name.

NonHprAccountResponse

Bases: BaseModel

Response schema for checking account existence when HPR ID is not present.

Attributes:

Name	Type	Description
txnId	Optional[str]	Transaction ID.
token	str	Token.
hprIdNumber	str	HPR ID number.
name	Optional[str]	Name.
firstName	Optional[str]	First name.
lastName	Optional[str]	Last name.
middleName	Optional[str]	Middle name.
gender	Optional[str]	Gender.
yearOfBirth	Optional[str]	Year of birth.
monthOfBirth	Optional[str]	Month of birth.
dayOfBirth	Optional[str]	Day of birth.
districtCode	Optional[str]	District code.
stateCode	Optional[str]	State code.
stateName	Optional[str]	State name.
districtName	Optional[str]	District name.
address	Optional[str]	Address.
pincode	Optional[str]	Pincode.
profilePhoto	Optional[str]	Profile photo.
categoryId	int	Category ID.
subCategoryId	int	Sub-category ID.
new	bool	Indicates if the account is new.

DemographicAuthViaMobileRequestSchema

Bases: BaseModel

Request schema for demographic authentication via mobile.

Attributes:

Name	Type	Description
txnId	str	Transaction ID.
mobileNumber	str	Mobile number.

DemographicAuthViaMobileResponseSchema

Bases: BaseModel

Response schema for demographic authentication via mobile.

Attributes:

Name	Type	Description
verified	bool	Verification status.

GenerateMobileOtpRequestSchema

Bases: BaseModel

Request schema for generating mobile OTP.

Attributes:

Name	Type	Description
mobile	str	Mobile number.
txnId	str	Transaction ID.

validate_required_fields classmethod

validate_required_fields(value: str, info: FieldValidationInfo) -> str

Ensure the field is not empty.

MobileOtpResponseSchema

Bases: BaseModel

Response schema for generating mobile OTP.

Attributes:

Name	Type	Description
txnId	str	Transaction ID.
mobileNumber	Optional[str]	Mobile number (always null).

VerifyMobileOtpRequestSchema

Bases: BaseModel

Request schema for verifying mobile OTP.

Attributes:

Name	Type	Description
otp	str	OTP.
txnId	str	Transaction ID.

HpIdSuggestionRequestSchema

Bases: BaseModel

Request schema for HP ID suggestion.

Attributes:

Name	Type	Description
txnId	str	Transaction ID.

HprIdSuggestionResponse

Bases: RootModel[list[str]]

Response schema for HPR ID suggestions, which is a list of strings.

CreateHprIdWithPreVerifiedRequestBody

Bases: BaseModel

Request body schema for creating HPR ID with pre-verified data.

Attributes:

Name	Type	Description
address	str	Address.
dayOfBirth	str	Day of birth.
districtCode	str	District code.
email	str	Email.
firstName	str	First name.
hpCategoryCode	str	HP category code.
hpSubCategoryCode	str	HP subcategory code.
hprId	str	HPR ID.
lastName	str	Last name.
middleName	Optional[str]	Middle name (optional).
monthOfBirth	str	Month of birth.
password	str	Password.
pincode	str	Pincode.
profilePhoto	Optional[str]	Profile photo (optional).
stateCode	str	State code.
txnId	str	Transaction ID.
yearOfBirth	str	Year of birth.

CreateHprIdWithPreVerifiedResponseBody

Bases: BaseModel

Response body schema for creating HPR ID with pre-verified data.

Attributes:

Name	Type	Description
token	str	Token.
hprIdNumber	str	HPR ID number.
name	str	Name.
gender	str	Gender.
yearOfBirth	str	Year of birth.
monthOfBirth	str	Month of birth.
dayOfBirth	str	Day of birth.
firstName	str	First name.
hprId	str	HPR ID.
lastName	str	Last name.
middleName	Optional[str]	Middle name.
stateCode	str	State code.
districtCode	Optional[str]	District code.
stateName	str	State name.
districtName	Optional[str]	District name.
email	Optional[str]	Email.
kycPhoto	str	KYC photo.
mobile	str	Mobile number.
categoryId	int	Category ID.
subCategoryId	int	Subcategory ID.
authMethods	list[str]	Authentication methods.
new	bool	New flag.

HPRService

HPRService(config: ClientConfig)

Bases: BaseService

Service for handling HPR (Healthcare Professional Registry) registration-related operations.

This service provides methods for interacting with the HPR registration API, including: - Aadhaar OTP generation and verification - Mobile OTP generation and verification - Demographic authentication via mobile - Checking for existing HPR accounts - Retrieving HPR ID suggestions - Creating HPR IDs with pre-verified data

All methods handle validation, error logging, and robust exception management.

Parameters:

Name	Type	Description	Default
config	ClientConfig	Configuration object containing API credentials and settings.	required

Returns:

Name	Type	Description
HPRService		An instance of the HPRService class.

Raises:

Type	Description
EhrApiError	If any API call fails or if validation errors occur.
ValidationError	If input data does not conform to expected schemas.

Example usage

config = ClientConfig(
    api_key="your_api_key"
)
hpr_service = HPRService(config)
otp_response = await hpr_service.generate_aadhaar_otp({"aadhaar": "123456789012"})

validate_data async

validate_data(dto_type: Type[BaseModel], request_data: dict[str, Any]) -> dict[str, Any]

Validates the provided data dict against a Pydantic DTO schema.

Args:

dto_type (Type[BaseModel]): The Pydantic model class to validate against.
request_data (dict[str, Any]): The input data dictionary.

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Validated data serialized with alias names.

Raises:

Type	Description
EhrApiError	If validation fails with detailed error message.

Example:

await hpr_service.validate_data(GenerateAadhaarOtpRequest, {"aadhaar":"123456789012"})
{'aadhaar': '123456789012'}

generate_aadhaar_otp async

generate_aadhaar_otp(request_data: dict[str, Any]) -> GenerateAadhaarOtpResponseSchema

Initiate Aadhaar OTP flow for user authentication.

This method validates the Aadhaar number, sends it to the API, and returns a transaction ID to be used in the next step.

Parameters:

Name	Type	Description	Default
request_data	GenerateAadhaarOtpRequestSchema	Must include 'aadhaar' (12-digit string).	required

Returns:

Name	Type	Description
GenerateAadhaarOtpResponseSchema	GenerateAadhaarOtpResponseSchema	Includes: - txnId (str): Transaction/session ID for the OTP flow. - mobileNumber (str): Mobile number (masked) registered with the Aadhaar record.

Raises:

Type	Description
EhrApiError	On missing/invalid Aadhaar number or API error.

Example

resp = await hpr_service.generate_aadhaar_otp({'aadhaar': '123456789012'})
print(resp.txnId, resp.mobileNumber)

Response:

Sample Output:
{
    "txnId": "txn_abcdef123456",
    "mobileNumber": "9871XXXX23"
}

verify_aadhaar_otp async

verify_aadhaar_otp(request_data: dict[str, Any]) -> VerifyAadhaarOtpResponseSchema

Verify the OTP received on Aadhaar-linked mobile number.

Validates all required fields and verifies the OTP via the API. Returns all fetched demographic profile details.

Parameters:

Name	Type	Description	Default
request_data	VerifyAadhaarOtpRequestSchema	Must include - 'otp' (str), 'txnId' (str), 'domainName' (str), 'idType' (str) - 'restrictions' (Optional[str])	required

Returns:

Name	Type	Description
VerifyAadhaarOtpResponseSchema	VerifyAadhaarOtpResponseSchema	Includes: - txnId (str), gender (str), name (str), address (str), etc.

Raises:

EhrApiError: On missing/invalid OTP or API error.

Example

resp = await hpr_service.verify_aadhaar_otp({
    "otp": "123456", "txnId": "txn_abcdef123456", "domainName": "ndhm.gov.in", "idType": "aadhaar"
})
print(resp.txnId, resp.name, resp.gender)

Response:

Sample Output:
{
    "txnId": "txn_abcdef123456",
    "mobileNumber": "9871XXXX23",
    "gender": "M",
    "name": "John Doe",
    "address": "123 Main St, Delhi",
    ...
}

check_account_exist async

check_account_exist(request_data: dict[str, Any]) -> Union[HprAccountResponse, NonHprAccountResponse]

Checks if there is an existing HPR account for the provided transaction.

Returns rich account info if present, or demographic info indicating non-existence.

Parameters:

Name	Type	Description	Default
request_data	CheckAccountExistRequestSchema	Must include: - 'txnId' (str): The OTP or auth transaction ID. - 'preverifiedCheck' (bool): Flag for existence of preverified account.	required

Returns:

Name	Type	Description
HprAccountResponse	Union[HprAccountResponse, NonHprAccountResponse]	if account exists,
NonHprAccountResponse	Union[HprAccountResponse, NonHprAccountResponse]	else.

Raises:

Type	Description
EhrApiError	On validation or API errors.

Example

resp = await hpr_service.check_account_exist({"txnId": "txn_abcdef123456", "preverifiedCheck": True})
if isinstance(resp, HprAccountResponse):
    print("Account exists:", resp.hprIdNumber)
else:
    print("No existing account.")

Response:

Sample Output (existing):
{
    "token": "auth.jwt.token",
    "hprIdNumber": "HPR123456",
    "hprId": "HPR123456",
    "categoryId": 10,
    "subCategoryId": 1,
    "new": False,
    "categoryName": "Physician",
    "categorySubName": "Allopathic"
}

Sample Output (non-existing):
{
    "txnId": "txn_abcdef123456",
    "token": "auth.jwt.token",
    "hprIdNumber": "",
    "name": "John Doe",
    "gender": "M",
    "address": "New Delhi",
    ...
}

demographic_auth_via_mobile async

demographic_auth_via_mobile(request_data: dict[str, Any]) -> DemographicAuthViaMobileResponseSchema

Authenticates user demographics using a mobile number.

Parameters:

Name	Type	Description	Default
request_data	DemographicAuthViaMobileRequestSchema	Must include: - 'txnId': The authentication transaction ID - 'mobileNumber': The mobile number to authenticate	required

Returns:

Name	Type	Description
DemographicAuthViaMobileResponseSchema	DemographicAuthViaMobileResponseSchema	verified (bool): Whether the provided details matched

Raises:

Type	Description
EhrApiError	On API or validation failure

Example

resp = await hpr_service.demographic_auth_via_mobile({"txnId": "txn_abc123", "mobileNumber": "9876543210"})
print(resp.verified)

Response:

Sample Output:
{"verified": True} if the mobile number matches the transaction ID,
{"verified": False} if it does not match.

generate_mobile_otp async

generate_mobile_otp(request_data: dict[str, Any]) -> MobileOtpResponseSchema

Initiates OTP generation for mobile number verification/authentication.

Parameters:

Name	Type	Description	Default
request_data	GenerateMobileOtpRequestSchema	Must include: - 'mobile' (str): The mobile number - 'txnId' (str): Transaction/session ID	required

Returns:

Name	Type	Description
MobileOtpResponseSchema	MobileOtpResponseSchema	txnId: Transaction ID mobileNumber: Always null for this API

Raises:

Type	Description
EhrApiError	On input validation or API error

Example

resp = await hpr_service.generate_mobile_otp({"mobile": "9876543210", "txnId": "txn_xyz123"})
print(resp.txnId)

Response:

Sample Output:
{
    "txnId": "txn_xyz123",
    "mobileNumber": null
}

verify_mobile_otp async

verify_mobile_otp(request_data: dict[str, Any]) -> MobileOtpResponseSchema

Verifies a provided mobile OTP code.

Parameters:

Name	Type	Description	Default
request_data	VerifyMobileOtpRequestSchema	Must include: - 'otp': The OTP code - 'txnId': The related transaction ID	required

Returns:

Name	Type	Description
MobileOtpResponseSchema	MobileOtpResponseSchema	txnId (str)

Raises:

Type	Description
EhrApiError	On input/API error

Example

resp = await hpr_service.verify_mobile_otp({"otp": "654321", "txnId": "txn_abcdefgh"})
print(resp.txnId)

Response:

Sample Output:
{
    "txnId": "txn_abcdefgh",
    "mobileNumber": null
}

get_hpr_suggestion async

get_hpr_suggestion(request_data: dict[str, Any]) -> list[str]

Retrieves a list of HPR ID suggestions appropriate for the current session/transaction.

Parameters:

Name	Type	Description	Default
request_data	HpIdSuggestionRequestSchema	Must include - 'txnId' (str)	required

Returns:

Type	Description
list[str]	list[str]: Suggested unique HPR IDs for user selection.

Raises:

Type	Description
EhrApiError	On missing txnId, validation, or service error.

Example

suggestions = await hpr_service.get_hpr_suggestion({"txnId": "txn_abcdef123456"})
print(suggestions)  # ["DrJohnDoe", "JohnD123", "J.Doe_Med"]

Response:

Sample Output:
[
    "DrJohnDoe123",
    "DrJohnDoe987",
    "JohnDae01"
]

create_hpr_id_with_preverified async

create_hpr_id_with_preverified(request_data: dict[str, Any]) -> CreateHprIdWithPreVerifiedResponseBody

Register a new HPR ID using pre-verified demographic and professional data.

Parameters:

Name	Type	Description	Default
request_data	CreateHprIdWithPreVerifiedRequestBody	Must include all KYC, professional and session details (see DTO for fields).	required

Returns:

Name	Type	Description
CreateHprIdWithPreVerifiedResponseBody	CreateHprIdWithPreVerifiedResponseBody	Details of the created HPR ID, token, and participant metadata.

Raises:

Type	Description
EhrApiError	On missing input, validation or API failure.

Example

resp = await hpr_service.create_hpr_id_with_preverified({
    "address": "123 Main St",
    "firstName": "John",
    "lastName": "Doe",
    "yearOfBirth": "1980",
    "monthOfBirth": "01",
    "dayOfBirth": "15",
    "email": "john.doe@example.com",
    "hpCategoryCode": "DOC",
    "hpSubCategoryCode": "GEN",
    "hprId": "JDoeDoc80",
    "password": "StrongPass123!",
    "pincode": "110001",
    "stateCode": "DL",
    "txnId": "txn_abcdef123456",
    ...
})
print(resp.hprIdNumber, resp.token)

Response:

Sample Output:
{
    "token": "eyJhbGciOi...",
    "hprIdNumber": "HPR987654",
    "hprId": "HPR987654",
    "name": "John Doe",
    "gender": "M",
    "yearOfBirth": "1980",
    "monthOfBirth": "01",
    "dayOfBirth": "15",
    "firstName": "John",
    "lastName": "Doe",
    "stateCode": "DL",
    "districtCode": "DL001",
    "stateName": "Delhi",
    "districtName": "New Delhi",
    "email": "john.doe@example.com",
    "kycPhoto": "...",
    "mobile": "9876543210",
    "categoryId": 1,
    "subCategoryId": 2,
    "authMethods": ["PIN", "Biometric"],
    "new": True
}

CreateHPR

CreateHPR(config: ClientConfig)

Orchestrates the multi-step Healthcare Professional Registry (HPR) registration process.

This class streamlines the HPR registration by managing the sequence of API calls required, simplifying the backend workflow and enabling guided UI flows.

It coordinates OTP generation and verification for Aadhaar and mobile, checks for existing accounts, performs demographic authentication, fetches HPR ID suggestions, and finally creates the HPR ID.

Each step returns a detailed message, API response data, the next step in the flow, and hints specifying the payload required for subsequent steps, enabling low-code or UI-driven implementations.

Parameters:

Name	Type	Description	Default
config	ClientConfig	Configuration containing API credentials and service endpoints.	required

Raises:

Type	Description
EhrApiError	If any step in the registration process fails or if an unexpected error occurs.
ValidationError	If the provided payload does not meet the expected schema.

Returns:

Type	Description
	dict[str, Any]: A dictionary containing the API response data, a user-friendly message, the next step in the registration flow, and hints for the next step's payload.

Example usage

hpr_creator = CreateHPR(config)
# Step 1: Generate Aadhaar OTP
step1_result = await hpr_creator.start_registration("123456789012")

# Step 2: Verify Aadhaar OTP using OTP and txnId from step1_result
step2_result = await hpr_creator.registration_flow(
    HprRegistrationSteps.VERIFY_AADHAAR_OTP,
    {
        "otp": "<otp_value>",
        "txnId": step1_result["data"]["txnId"],
        "domainName": "<domain_name>",
        "idType": "aadhaar",
        "restrictions": None  # or any applicable restrictions
    }
)

# Proceed with subsequent steps as guided by step2_result["next_step"]

start_registration async

start_registration(aadhaar_number: str) -> dict[str, Any]

Initiates the HPR registration process by generating an Aadhaar OTP.

Sends the Aadhaar number to the backend to receive an OTP on the linked mobile number.

Parameters:

Name	Type	Description	Default
aadhaar_number	str	12-digit Aadhaar number of the healthcare professional.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary containing: - message (str): Informational message about the OTP generation. - data (dict): API response data including txnId and masked mobileNumber. - next_step (str): The next registration step name ('VERIFY_AADHAAR_OTP'). - next_step_payload_hint (dict): Guidance on required fields for next step payload.

Raises:

Type	Description
EhrApiError	When the OTP generation fails or unexpected error occurs.

Example

result = await hpr_creator.start_registration("123456789012")
print(result["message"])
print("Transaction ID:", result["data"]["txnId"])
print("Next step:", result["next_step"])

Response:

Sample Output:
{
    "txnId": "3b440ecf-6cd5-4059-9fdd-12e4c14b931a",
    "mobileNumber": "9871XXXX123",
    "next_step": "VERIFY_AADHAAR_OTP",
    "next_step_payload_hint": {
        "description": "Provide the OTP received via SMS and the transaction ID.",
        "required_fields": ["otp", "txnId"],
        "source_of_data": {"txnId": "from current step's data.txnId"},
    }
}

registration_flow async

registration_flow(step: HprRegistrationSteps, payload: dict[str, Any]) -> dict[str, Any]

Executes a specific step in the HPR registration workflow, providing guidance for subsequent steps.

This method handles

• Aadhaar OTP verification,
• Checking existing HPR account,
• Demographic authentication via mobile,
• Mobile OTP generation and verification,
• Retrieving HPR ID suggestions,
• Creating HPR ID with preverified data.

Parameters:

Name	Type	Description	Default
step	HprRegistrationSteps	The current registration step to execute.	required
payload	dict[str, Any]	Data required to complete the current step, varying by step.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Contains - message (str): Informative status message relevant to the step. - data (dict): API response data aligned with the step’s DTO. - next_step (str or None): The next step identifier or None if registration completed. - next_step_payload_hint (dict or None): Guidance on fields required for the next step.

Raises:

Type	Description
EhrApiError	For invalid steps, validation failures, or backend errors.

Detailed Steps and Payload Requirements

1. VERIFY_AADHAAR_OTP
2. Payload must include: otp, txnId, domainName, idType, restrictions (optional)
3. Returns txnId and profile data.

4. Next step: CHECK_ACCOUNT_EXIST

5. CHECK_ACCOUNT_EXIST

6. Payload must include: txnId, preverifiedCheck (boolean indicating pre-verified lookup)
7. If account exists, registration ends.

8. Else, next step: DEMOGRAPHIC_AUTH_VIA_MOBILE

9. DEMOGRAPHIC_AUTH_VIA_MOBILE

10. Payload must include: txnId, mobileNumber
11. If demographic auth verified (verified == True), implies failure in your flow? (as per your code)
    • Next step: GET_HPR_ID_SUGGESTION

12. Else demographic auth successful, next step: GENERATE_MOBILE_OTP

13. GENERATE_MOBILE_OTP

14. Payload must include: mobile, txnId
15. Returns txnId for OTP verification.

16. Next step: VERIFY_MOBILE_OTP

17. VERIFY_MOBILE_OTP

18. Payload must include: otp, txnId
19. Returns txnId.

20. Next step: GET_HPR_ID_SUGGESTION

21. GET_HPR_ID_SUGGESTION

22. Payload must include: txnId
23. Returns a list of HPR ID suggestions.

24. Next step: CREATE_HPR_ID_WITH_PREVERIFIED

25. CREATE_HPR_ID_WITH_PREVERIFIED

26. Payload must include: hprId, password, txnId, firstName, middleName, lastName, yearOfBirth, dayOfBirth, monthOfBirth, gender, email, mobile, address, etc. (from previous steps)
27. Returns final HPR ID details.
28. Next step: None (registration complete)

Example

# Step: VERIFY_AADHAAR_OTP
resp = await hpr_creator.registration_flow(
    HprRegistrationSteps.VERIFY_AADHAAR_OTP,
    {
        "otp": "123456",
        "txnId": "3b440ecf-6cd5-4059-9fdd-12e4c14b931a",
        "domainName": "ndhm.gov.in",
        "idType": "aadhaar",
        "restrictions": None,
    }
)
print(resp["message"])
print("Next step:", resp["next_step"])

Sample Response for VERIFY_AADHAAR_OTP

{ "message": "Aadhaar OTP verified. Now, check if an HPR account exists.", "data": { "txnId": "3b440ecf-6cd5-4059-9fdd-12e4c14b931a", "gender": "M", "mobileNumber": "9871XXXX123", "name": "Dr. John Doe", "email": "john.doe@example.com", ... }, "next_step": "CHECK_ACCOUNT_EXIST", "next_step_payload_hint": { "description": "Provide the transaction ID from current step's response data.", "required_fields": ["txnId"], "source_of_data": {"txnId": "from previous response"}, } }

Sample Response when account exists (at CHECK_ACCOUNT_EXIST): { "message": "An HPR account already exists for this user. The registration flow is complete.", "data": { "hprIdNumber": "HPR12345678", "hprId": "HPR12345678", "token": "...", "categoryId": 1, "subCategoryId": 2, "new": false, "categoryName": "General Physician", "categorySubName": "General Medicine", ... }, "next_step": None, "next_step_payload_hint": None }

Sample Response when account does not exist (at CHECK_ACCOUNT_EXIST): { "message": "No HPR account found. Proceed to demographic authentication via mobile.", "data": { "txnId": "3b440ecf-6cd5-4059-9fdd-12e4c14b931a", "token": "some_token", "new": true, ... }, "next_step": "DEMOGRAPHIC_AUTH_VIA_MOBILE", "next_step_payload_hint": { "description": "Provide mobileNumber and txnId for demographic auth", "required_fields": ["mobileNumber", "txnId"] } }