Doctor Verification

Endpoint Overview

POST /api/v1/south-africa/doctor-verification

Description

This API endpoint allows you to verify the registration status and professional details of medical doctors in South Africa. By providing a doctor's registration number, you can retrieve comprehensive information about their qualifications, practice categories, registration status, and location details. This verification helps confirm the legitimacy and credentials of healthcare professionals.

Key Benefits

Instant verification of doctor registration status with South African medical authorities

Access to detailed qualification history and specialization information

Verification of practice type, location, and current registration status

Streamlined compliance for healthcare organizations and insurance providers

Use Cases

Healthcare

Insurance

Telemedicine

Verify credentials of doctors before hiring at hospitals and clinics

Confirm registration status when granting practice privileges

Validate specializations for referral networks

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
registration_number	String	Yes	The doctor's registration number issued by South African medical authorities

Example Request

{
    "registration_number": "DA73248238"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains all verification details
data.client_id	String	Unique identifier for the verification request
data.registration_number	String	Doctor's registration number
data.doctor_name	String	Full name of the doctor
data.city	String	City where the doctor is located
data.province	String	Province where the doctor is located
data.post_code	String	Postal code of the doctor's location
data.registration_status	String	Current status of the doctor's registration (e.g., ACTIVE, ERASED)
data.register	String	Type of register the doctor is listed under
data.board	String	Governing medical board
data.qualification_information	Array	List of qualification details
data.qualification_information[].qualification_name	String	Name of the qualification
data.qualification_information[].date_obtained	String	Date the qualification was obtained (YYYY-MM-DD)
data.category_details	Array	List of practice category details
data.category_details[].practice_type	String	Type of practice
data.category_details[].practice_field	String	Field of practice
data.category_details[].speciality	String	Speciality of practice
data.category_details[].sub_speciality	String	Sub-speciality of practice
data.category_details[].from_date	String	Start date of the practice category (YYYY-MM-DD)
data.category_details[].end_date	String	End date of the practice category (YYYY-MM-DD)
data.category_details[].status	String	Status of the practice category
status_code	Integer	HTTP status code
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code indicating the type of message

Example Successful Response

{
    "data": {
        "client_id": "south_africa_doctor_verification_cqqBozwPwayveHsxHDRe",
        "registration_number": "BAA0650714",
        "doctor_name": "STEVE SMITH",
        "city": "DURBAN",
        "province": "KWAZULU NATAL",
        "post_code": "4001",
        "registration_status": "ERASED",
        "register": "Practitioner",
        "board": "EMB",
        "qualification_information": [
            {
                "qualification_name": "Cert.Basic Amb.Asst.Meditrax Academy",
                "date_obtained": "2006-10-05"
            }
        ],
        "category_details": [
            {
                "practice_type": "SUPERVISED PRACTICE",
                "practice_field": "",
                "speciality": "",
                "sub_speciality": "",
                "from_date": "2006-10-18",
                "end_date": "2020-03-31",
                "status": "ERASED"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Registration Number

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid registration number format",
    "message_code": "invalid_input"
}

The registration number provided is not in a valid format or does not exist in the system.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Rotate JWT tokens periodically and implement token expiration

Use HTTPS for all API communications

User Experience Guidelines

Implement caching for frequently verified doctors to improve response times

Display verification status clearly to end-users with appropriate visual indicators

Provide clear error messages when verification fails

Include timestamp of verification in user interfaces to indicate recency

Code Samples

cURL

Python

Node.js

Related APIs

South Africa ID Verification - Verify South African identity documents

South Africa Business Verification - Verify South African business entities

South Africa Address Verification - Verify South African physical addresses

Compliance and Legal Considerations

This API accesses medical practitioner data regulated by South African healthcare authorities. Usage must comply with the Protection of Personal Information Act (POPIA) and other relevant healthcare data regulations. Ensure you have appropriate consent or legal basis before verifying doctor information, and handle the returned data in accordance with data protection requirements.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/south-africa/doctor-verification' \ --header 'Content-Type: application/json' \ --data-raw '{ "registration_number": "DA73248238" }'

{ "data": { "client_id": "south_africa_doctor_verification_cqqBozwPwayveHsxHDRe", "registration_number": "BAA0650714", "doctor_name": "STEVE SMITH", "city": "DURBAN", "province": "KWAZULU NATAL", "post_code": "4001", "registration_status": "ERASED", "register": "Practitioner", "board": "EMB", "qualification_information": [ { "qualification_name": "Cert.Basic Amb.Asst.Meditrax Academy", "date_obtained": "2006-10-05" } ], "category_details": [ { "practice_type": "SUPERVISED PRACTICE", "practice_field": "", "speciality": "", "sub_speciality": "", "from_date": "2006-10-18", "end_date": "2020-03-31", "status": "ERASED" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Doctor Verification

Doctor Verification#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Doctor Verification

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples