Practitioner Search API Documentation

Endpoint

GET /v1/practitioner-search

This is the primary API for searching and retrieving professional license and registration information for health workers from the Health Worker Registry (HWR). It searches the local registry first and asynchronously falls back to querying the upstream regulator API if the record is not found locally.

Input Parameters

All parameters are passed as query string parameters (GET) or form-encoded body (POST).

Parameter Combinations

You can search using any of the following combinations:

Default Regulator Behaviour

• If identification_type and identification_number are provided without a regulator, the system defaults to Pharmacy and Poisons Board.
• If no regulator is specified at all (and no identification fields), the system defaults to KMPDC.

Supported Regulators

The regulator parameter must be one of the following values (case-insensitive):

Sub-categories under KMPDC

KMPDC handles three sub-categories determined automatically by the prefix of the registration_number:

Registration Number Formats & Examples

Each regulator has a distinct registration number format. Below are the patterns and illustrative examples.

KMPDC — Local Practitioners

• Format: Alphanumeric, typically a letter prefix followed by digits
• Examples: A1234, P5678, B9012
• Lookup: Uses registration_number directly to query KMPDC single-practitioner API
• Primary ID type: National ID

KMPDC — Foreign Practitioners (prefix C or D)

• Format: Letter C or D followed by digits
• Examples: C1234, D5678
• Lookup: Uses registration_number to query KMPDC foreign-practitioner API
• Primary ID type: Passport

KMPDC — COHO (prefix E)

• Format: Letter E followed by digits
• Examples: E1234, E5678
• Lookup: Uses registration_number to query KMPDC COHO API
• Primary ID type: National ID

Nursing Council

• Format: Numeric or alphanumeric registration number
• Examples: 12345, NCK-67890
• Lookup: Searches by id_no (national ID) or reg_no (registration number) against NCK API
• Primary ID type: National ID (also supports Passport and Birth Certificate)
• Note: For Nursing Council, identification_number (national ID) is the primary lookup key when searching from the regulator. The registration_number alone may not be sufficient if the record isn't already in the local registry.

Clinical Officers Council

• Format: Alphanumeric registration number
• Examples: CO-1234, 5678
• Lookup: Uses registration_number as the registration query parameter against COC API
• Primary ID type: National ID

Pharmacy and Poisons Board

• Format: Numeric — typically the practitioner's national ID number is used as the lookup key
• Examples: 12345678 (national ID number)
• Lookup: Uses identification_number (national ID) as the nationalid query parameter against PPB API
• Primary ID type: National ID
• Note: For PPB, the identification_number (national ID) is the primary and most reliable search key rather than a separate registration number. If only registration_number is provided along with identification_number, the system will prefer the national ID for the regulator lookup.

Success Response

{
  "membership": {
    "id": "PUID-0001234",
    "status": "Licensed",
    "salutation": "Dr.",
    "full_name": "JOHN PETER DOE",
    "first_name": "JOHN",
    "middle_name": "PETER",
    "last_name": "DOE",
    "gender": "Male",
    "registration_id": "PLR-KMPDC-00123",
    "external_reference_id": "A1234",
    "licensing_body": "KMPDC",
    "specialty": "MEDICINE",
    "is_active": 1,
    "is_withdrawn": 0,
    "withdrawal_reason": "",
    "withdrawal_date": "",
    "license_expires_in_days": 145
  },
  "licenses": [
    {
      "id": "PLR-REC-00456",
      "external_reference_id": "LIC-789",
      "license_type": "Annual",
      "license_start": "2025-01-01",
      "license_end": "2025-12-31"
    },
    {
      "id": "PLR-REC-00123",
      "external_reference_id": "LIC-456",
      "license_type": "Annual",
      "license_start": "2024-01-01",
      "license_end": "2024-12-31"
    }
  ],
  "professional_details": {
    "professional_cadre": "MEDICINE",
    "practice_type": "General Practice",
    "specialty": "General Surgery",
    "subspecialty": "",
    "discipline_name": "Medicine",
    "educational_qualifications": "MBChB"
  },
  "contacts": {
    "phone": "+254712345678",
    "email": "john.doe@example.com",
    "postal_address": "P.O. Box 123, Nairobi"
  },
  "identifiers": {
    "identification_type": "National ID",
    "identification_number": "12345678",
    "client_registry_id": "",
    "student_id": ""
  }
}

Response Field Descriptions

membership object

licenses array

Each entry represents a license period:

professional_details object

contacts object

identifiers object

Error Responses

All error responses follow this format:

{
  "error": "Error message string"
}

Possible Error Messages

Quick Reference: Regulator Lookup Summary