TB GeneXpert - Patients

Patient-level search endpoints for TB GeneXpert results. These endpoints allow searching for individual patient records by name, health facility, sample type, or result type. All responses are paginated and include detailed patient demographics, facility information, specimen data, and full GeneXpert results including drug resistance markers.

Common parameters

All patient search endpoints accept the following query parameters for filtering and pagination.

Name
interval_dates
Type
JSON array
Description
Date range filter as a JSON array with two dates in YYYY-MM-DD format: ["2025-01-01","2025-12-31"]. Defaults to the last 12 months if not provided.
Name
province
Type
string
Description
Filter by province name. Supports multi-select.
Name
district
Type
string
Description
Filter by district name. Supports multi-select.
Name
genexpert_result_type
Type
string
Description
Filter by cartridge type: "Ultra 6 Cores" or "XDR 10 Cores".
Name
page
Type
integer
Description
Page number for pagination. Defaults to 1.
Name
per_page
Type
integer
Description
Number of results per page. Defaults to 20.

Request with parameters

GET

/tb/gx/patients/by_name/

curl -G https://api.openldr.org.mz/tb/gx/patients/by_name/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "first_name=Maria" \
  --data-urlencode "surname=Silva" \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=20"

GET/tb/gx/patients/by_name/

Search by name

Search for patient GeneXpert results by first name and/or surname. Returns paginated results with full patient details, facility information, specimen data, and test results including drug resistance markers.

Name
first_name
Type
string
Description
Patient first name to search for. Partial matching supported.
Name
surname
Type
string
Description
Patient surname to search for. Partial matching supported.

Response fields:

Name
status
Type
string
Description
Request status ("success" or "error").
Name
page
Type
integer
Description
Current page number.
Name
per_page
Type
integer
Description
Number of results per page.
Name
total_count
Type
integer
Description
Total number of matching records.
Name
total_pages
Type
integer
Description
Total number of pages available.
Name
data
Type
array
Description
Array of patient result objects containing: RequestID, First_Name, Surname, Age, Sex, Requesting_Facility, Testing_Facility, Province, District, Final_Result (MTB Detected/Not Detected), MTB_Trace, Rifampicin_Resistance, Isoniazid_Resistance, Fluoroquinolone_Resistance, Sample_Type, Collection_Date, Registration_Date, Analysis_Date, Validation_Date.

Request

GET

/tb/gx/patients/by_name/

curl -G https://api.openldr.org.mz/tb/gx/patients/by_name/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "first_name=Maria" \
  --data-urlencode "surname=Silva" \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores"

Response

{
  "status": "success",
  "page": 1,
  "per_page": 20,
  "total_count": 3,
  "total_pages": 1,
  "data": [
    {
      "RequestID": "GX-2025-00142",
      "First_Name": "Maria",
      "Surname": "Silva",
      "Age": 34,
      "Sex": "Female",
      "Requesting_Facility": "CS Machava II",
      "Testing_Facility": "Hospital Central de Maputo",
      "Province": "Maputo Cidade",
      "District": "KaMpfumo",
      "Final_Result": "MTB Detected",
      "MTB_Trace": "Low",
      "Rifampicin_Resistance": "Not Detected",
      "Isoniazid_Resistance": null,
      "Fluoroquinolone_Resistance": null,
      "Sample_Type": "Sputum",
      "Collection_Date": "2025-03-10",
      "Registration_Date": "2025-03-12",
      "Analysis_Date": "2025-03-13",
      "Validation_Date": "2025-03-13"
    }
  ]
}

GET/tb/gx/patients/by_facility/

Search by facility

Search for patient GeneXpert results filtered by health facility. Returns the same paginated response structure as the name search endpoint.

Name
health_facility
Type
string
Description
Name of the health facility to filter by.

Response fields:

Name
status
Type
string
Description
Request status ("success" or "error").
Name
page
Type
integer
Description
Current page number.
Name
per_page
Type
integer
Description
Number of results per page.
Name
total_count
Type
integer
Description
Total number of matching records.
Name
total_pages
Type
integer
Description
Total number of pages available.
Name
data
Type
array
Description
Array of patient result objects (same structure as search by name).

Request

GET

/tb/gx/patients/by_facility/

curl -G https://api.openldr.org.mz/tb/gx/patients/by_facility/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "health_facility=CS Machava II" \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=20"

Response

{
  "status": "success",
  "page": 1,
  "per_page": 20,
  "total_count": 310,
  "total_pages": 16,
  "data": [
    {
      "RequestID": "GX-2025-00142",
      "First_Name": "Maria",
      "Surname": "Silva",
      "Age": 34,
      "Sex": "Female",
      "Requesting_Facility": "CS Machava II",
      "Testing_Facility": "Hospital Central de Maputo",
      "Province": "Maputo Cidade",
      "District": "KaMpfumo",
      "Final_Result": "MTB Detected",
      "MTB_Trace": "Low",
      "Rifampicin_Resistance": "Not Detected",
      "Sample_Type": "Sputum",
      "Collection_Date": "2025-03-10",
      "Registration_Date": "2025-03-12",
      "Analysis_Date": "2025-03-13",
      "Validation_Date": "2025-03-13"
    }
  ]
}

GET/tb/gx/patients/by_sample_type/

Search by sample type

Search for patient GeneXpert results filtered by specimen type. Returns the same paginated response structure.

Name
sample_type
Type
string
Description
Specimen type to filter by. Accepted values: "sputum", "feces", "urine", "blood".

Response fields:

Name
status
Type
string
Description
Request status ("success" or "error").
Name
page
Type
integer
Description
Current page number.
Name
per_page
Type
integer
Description
Number of results per page.
Name
total_count
Type
integer
Description
Total number of matching records.
Name
total_pages
Type
integer
Description
Total number of pages available.
Name
data
Type
array
Description
Array of patient result objects (same structure as search by name).

Request

GET

/tb/gx/patients/by_sample_type/

curl -G https://api.openldr.org.mz/tb/gx/patients/by_sample_type/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "sample_type=feces" \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=20"

Response

{
  "status": "success",
  "page": 1,
  "per_page": 20,
  "total_count": 185,
  "total_pages": 10,
  "data": [
    {
      "RequestID": "GX-2025-00287",
      "First_Name": "Joao",
      "Surname": "Tembe",
      "Age": 3,
      "Sex": "Male",
      "Requesting_Facility": "CS 1 de Junho",
      "Testing_Facility": "Hospital Central de Maputo",
      "Province": "Maputo Cidade",
      "District": "KaMavota",
      "Final_Result": "MTB Not Detected",
      "MTB_Trace": null,
      "Rifampicin_Resistance": null,
      "Sample_Type": "Feces",
      "Collection_Date": "2025-04-15",
      "Registration_Date": "2025-04-17",
      "Analysis_Date": "2025-04-18",
      "Validation_Date": "2025-04-18"
    }
  ]
}

GET/tb/gx/patients/by_result_type/

Search by result type

Search for patient GeneXpert results filtered by the final test result. Returns the same paginated response structure.

Name
result_type
Type
string
Description
Result type to filter by. Accepted values: "detected", "not_detected", "indeterminate", "error", "invalid".

Response fields:

Name
status
Type
string
Description
Request status ("success" or "error").
Name
page
Type
integer
Description
Current page number.
Name
per_page
Type
integer
Description
Number of results per page.
Name
total_count
Type
integer
Description
Total number of matching records.
Name
total_pages
Type
integer
Description
Total number of pages available.
Name
data
Type
array
Description
Array of patient result objects (same structure as search by name).

Request

GET

/tb/gx/patients/by_result_type/

curl -G https://api.openldr.org.mz/tb/gx/patients/by_result_type/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  --data-urlencode 'interval_dates=["2025-01-01","2025-12-31"]' \
  --data-urlencode "result_type=detected" \
  --data-urlencode "genexpert_result_type=Ultra 6 Cores" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=20"

Response

{
  "status": "success",
  "page": 1,
  "per_page": 20,
  "total_count": 4518,
  "total_pages": 226,
  "data": [
    {
      "RequestID": "GX-2025-00098",
      "First_Name": "Antonio",
      "Surname": "Mondlane",
      "Age": 42,
      "Sex": "Male",
      "Requesting_Facility": "CS Machava II",
      "Testing_Facility": "Hospital Central de Maputo",
      "Province": "Maputo Cidade",
      "District": "KaMpfumo",
      "Final_Result": "MTB Detected",
      "MTB_Trace": "High",
      "Rifampicin_Resistance": "Detected",
      "Isoniazid_Resistance": null,
      "Fluoroquinolone_Resistance": null,
      "Sample_Type": "Sputum",
      "Collection_Date": "2025-02-20",
      "Registration_Date": "2025-02-22",
      "Analysis_Date": "2025-02-23",
      "Validation_Date": "2025-02-23"
    }
  ]
}