Patients

Patients are the core entity in MediLoop. Each patient is assigned a unique Uganda Health Identifier (UHID) that follows the national standard format. Patient data is stored in the national FHIR server as the single source of truth.

Endpoints

POST/api/v1/uhid/register/Register a new patient

GET/api/v1/uhid/{uhid}/Retrieve a patient by UHID

GET/api/v1/uhid/List patients

GET/api/v1/uhid/search/Search patients

PUT/api/v1/uhid/{uhid}/Update a patient

GET/api/v1/uhid/{uhid}/validate/Validate patient UHID

The Patient Object

Attributes

uhidstring

Uganda Health Identifier. Auto-generated on registration.

ninstringnullable

National Identification Number (for Ugandan citizens).

passport_numberstringnullable

Passport number (for foreigners).

first_namestring

Patient's first name.

middle_namestringnullable

Patient's middle name.

last_namestring

Patient's last name.

date_of_birthstring

Date of birth (YYYY-MM-DD).

genderstring

Patient's gender: M (Male) or F (Female).

phone_numberstringnullable

Phone number in E.164 format (+256...).

emailstringnullable

Email address.

districtstringnullable

District of residence.

physical_addressstringnullable

Physical address.

countrystring

Country code (default: UG).

nationalitystringnullable

Nationality.

emergency_contact_namestringnullable

Emergency contact name.

emergency_contact_phonestringnullable

Emergency contact phone.

fhir_patient_idstring

Reference to the FHIR Patient resource.

is_activeboolean

Whether the patient record is active.

created_atstring

Timestamp when the patient was created.

updated_atstring

Timestamp when the patient was last updated.

RESPONSE200

{
  "uhid": "UG123456789A",
  "nin": "CM12345678ABCDE",
  "first_name": "John",
  "middle_name": "Mukasa",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "gender": "M",
  "phone_number": "+256700123456",
  "email": "john.doe@example.com",
  "district": "Kampala",
  "physical_address": "Plot 123, Kampala Road",
  "country": "UG",
  "nationality": "Ugandan",
  "emergency_contact_name": "Jane Doe",
  "emergency_contact_phone": "+256700654321",
  "fhir_patient_id": "fhir-patient-123-456",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Register a Patient

Registers a new patient and auto-generates a UHID. The patient is created in the national FHIR server first (source of truth), then cached locally. Duplicate detection prevents creating multiple records for the same person.

POST/api/v1/uhid/register/

Request Body

first_namestringrequired

Patient's first name

last_namestringrequired

Patient's last name

date_of_birthstringrequired

Date of birth (YYYY-MM-DD)

genderstringrequired

M (Male) or F (Female)

ninstringoptional

National ID (for Ugandan citizens)

passport_numberstringoptional

Passport number (for foreigners)

phone_numberstringoptional

Phone in E.164 format (+256...)

emailstringoptional

Email address

districtstringoptional

District of residence

physical_addressstringoptional

Physical address

emergency_contact_namestringoptional

Emergency contact name

emergency_contact_phonestringoptional

Emergency contact phone

Request

bash

curl -X POST https://api.mediloop.co/api/v1/uhid/register/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-05-15",
    "gender": "M",
    "nin": "CM12345678ABCDE",
    "phone_number": "+256700123456",
    "district": "Kampala"
  }'

RESPONSE201

{
  "uhid": "UG123456789A",
  "nin": "CM12345678ABCDE",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "gender": "M",
  "phone_number": "+256700123456",
  "district": "Kampala",
  "fhir_patient_id": "fhir-patient-123-456",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}

Duplicate Detection

MediLoop enforces zero-tolerance duplicate prevention. Registration will fail with a 409 Conflict if a patient with matching NIN, passport, phone number, or name + date of birth already exists.

Retrieve a Patient

Retrieves a patient by their UHID from the national FHIR server.

GET/api/v1/uhid/{uhid}/

Path Parameters

uhidstringrequired

The patient's UHID

Request

bash

curl https://api.mediloop.co/api/v1/uhid/UG123456789A/ \
  -H "Authorization: Bearer sk_test_..."

RESPONSE200

{
  "uhid": "UG123456789A",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "gender": "M",
  "phone_number": "+256700123456",
  "district": "Kampala",
  "fhir_patient_id": "fhir-patient-123-456",
  "is_active": true
}

Search Patients

Search for patients by various criteria. All searches query the national FHIR server.

GET/api/v1/uhid/search/

Query Parameters

uhidstringoptional

Search by exact UHID

ninstringoptional

Search by National ID

passport_numberstringoptional

Search by passport number

phone_numberstringoptional

Search by phone number

first_namestringoptional

Search by first name

last_namestringoptional

Search by last name

date_of_birthstringoptional

Search by date of birth (YYYY-MM-DD)

Request

bash

curl "https://api.mediloop.co/api/v1/uhid/search/?first_name=John&last_name=Doe" \
  -H "Authorization: Bearer sk_test_..."

RESPONSE200

{
  "results": [
    {
      "uhid": "UG123456789A",
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-05-15",
      "gender": "M",
      "phone_number": "+256700123456"
    }
  ],
  "count": 1,
  "source": "fhir"
}

List Patients

Returns a paginated list of patients from the national FHIR server.

GET/api/v1/uhid/

Query Parameters

pageintegeroptional

Page number

Default: 1

page_sizeintegeroptional

Results per page (max 100)

Default: 20

Request

bash

curl "https://api.mediloop.co/api/v1/uhid/?page=1&page_size=20" \
  -H "Authorization: Bearer sk_test_..."

RESPONSE200

{
  "results": [
    {
      "uhid": "UG123456789A",
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-05-15"
    }
  ],
  "count": 1,
  "page": 1,
  "page_size": 20,
  "next": null,
  "previous": null,
  "source": "fhir"
}

Update a Patient

Updates a patient's information. Changes are written to the FHIR server first, then cached locally.

PUT/api/v1/uhid/{uhid}/

Request

bash

curl -X PUT https://api.mediloop.co/api/v1/uhid/UG123456789A/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+256700999888",
    "district": "Wakiso"
  }'

RESPONSE200

{
  "uhid": "UG123456789A",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+256700999888",
  "district": "Wakiso",
  "updated_at": "2024-01-16T14:30:00Z"
}

Validate Patient UHID

Validates a UHID and returns basic patient information. Useful for service integrations that need to verify patient identity before proceeding.

GET/api/v1/uhid/{uhid}/validate/

Request

bash

curl https://api.mediloop.co/api/v1/uhid/UG123456789A/validate/ \
  -H "Authorization: Bearer sk_test_..."

RESPONSE200

{
  "valid": true,
  "uhid": "UG123456789A",
  "name": "John Mukasa Doe",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+256700123456",
  "email": "john.doe@example.com",
  "fhir_patient_id": "fhir-patient-123-456",
  "address": "Plot 123, Kampala Road, Kampala, UG",
  "date_of_birth": "1990-05-15",
  "gender": "M",
  "active": true
}

UHID Format

The Uganda Health Identifier (UHID) is auto-generated during patient registration:

UG[0-9]{9}[A-Z]

Prefix: UG (Uganda)
Numeric: 9 random digits
Check character: 1 uppercase letter