Encounters

Encounters represent clinical interactions between patients and healthcare providers. Each encounter captures the context of a patient visit including participants, diagnoses, and location.

Endpoints

POST/api/v1/encountersCreate an encounter

GET/api/v1/encounters/:idRetrieve an encounter

GET/api/v1/encountersList encounters

PUT/api/v1/encounters/:idUpdate an encounter

GET/api/v1/encounters/:id/participantsList participants

GET/api/v1/encounters/:id/diagnosesList diagnoses

The Encounter Object

Attributes

idstring

Unique identifier for the encounter.

objectstring

String representing the object type. Always "encounter".

encounter_numberstring

Human-readable encounter reference number.

patient_uhidstring

UHID of the patient.

statusstring

Encounter status: planned, arrived, triaged, in-progress, onleave, finished, cancelled.

classstring

Classification: ambulatory, emergency, inpatient, observation, etc.

typestringnullable

Specific type of encounter.

facility_idstringnullable

ID of the facility where encounter occurred.

facility_namestringnullable

Name of the facility.

provider_idstringnullable

ID of the primary provider.

provider_namestringnullable

Name of the primary provider.

period_startstring

Start time of the encounter.

period_endstringnullable

End time of the encounter.

reason_codestringnullable

Coded reason for the encounter.

reason_textstringnullable

Text description of the reason.

fhir_encounter_idstring

Reference to the FHIR Encounter resource.

created_atstring

Timestamp when the encounter was created.

RESPONSE200

{
  "id": "enc_1234567890",
  "object": "encounter",
  "encounter_number": "ENC-2024-001234",
  "patient_uhid": "UG123456789A",
  "status": "in-progress",
  "class": "ambulatory",
  "type": "consultation",
  "facility_id": "fac_abc123",
  "facility_name": "Mulago Hospital",
  "provider_id": "prov_xyz789",
  "provider_name": "Dr. Sarah Nakamya",
  "period_start": "2024-01-15T10:00:00Z",
  "period_end": null,
  "reason_code": "185349003",
  "reason_text": "General examination",
  "fhir_encounter_id": "Encounter/fhir-enc-123",
  "created_at": "2024-01-15T10:00:00Z"
}

Create an Encounter

Creates a new clinical encounter for a patient.

POST/api/v1/encounters

Request Body

patient_uhidstringrequired

UHID of the patient

classstringrequired

Encounter class (ambulatory, emergency, inpatient, etc.)

typestringoptional

Specific encounter type

facility_idstringoptional

Facility ID

provider_idstringoptional

Primary provider ID

reason_codestringoptional

SNOMED CT code for reason

reason_textstringoptional

Text description of reason

Request

bash

curl https://api.mediloop.co/api/v1/encounters \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "patient_uhid": "UG123456789A",
    "class": "ambulatory",
    "type": "consultation",
    "facility_id": "fac_abc123",
    "provider_id": "prov_xyz789",
    "reason_text": "General examination"
  }'

RESPONSE201

{
  "id": "enc_1234567890",
  "object": "encounter",
  "encounter_number": "ENC-2024-001234",
  "patient_uhid": "UG123456789A",
  "status": "in-progress",
  "class": "ambulatory",
  "created_at": "2024-01-15T10:00:00Z"
}

List Encounters

Returns a list of encounters with optional filtering.

GET/api/v1/encounters

Query Parameters

limitintegeroptional

Number of results (1-100)

Default: 10

patient_uhidstringoptional

Filter by patient UHID

facility_idstringoptional

Filter by facility

statusstringoptional

Filter by status

start_datestringoptional

Filter from date (ISO 8601)

end_datestringoptional

Filter to date (ISO 8601)

Request

bash

curl "https://api.mediloop.co/api/v1/encounters?patient_uhid=UG123456789A&status=finished" \
  -H "Authorization: Bearer sk_test_..."

RESPONSE200

{
  "object": "list",
  "url": "/api/v1/encounters",
  "has_more": false,
  "data": [
    {
      "id": "enc_1234567890",
      "object": "encounter",
      "patient_uhid": "UG123456789A",
      "status": "finished",
      "class": "ambulatory",
      "period_start": "2024-01-15T10:00:00Z",
      "period_end": "2024-01-15T10:45:00Z"
    }
  ]
}

Encounter Participants

List all participants involved in an encounter.

GET/api/v1/encounters/:id/participants

Request

bash

curl https://api.mediloop.co/api/v1/encounters/enc_123/participants \
  -H "Authorization: Bearer sk_test_..."

RESPONSE200

{
  "object": "list",
  "data": [
    {
      "id": "part_001",
      "type": "primary-performer",
      "provider_id": "prov_xyz789",
      "provider_name": "Dr. Sarah Nakamya",
      "specialty": "General Practice"
    },
    {
      "id": "part_002",
      "type": "participant",
      "provider_id": "prov_abc456",
      "provider_name": "Nurse Jane Apio",
      "specialty": "Nursing"
    }
  ]
}

Encounter Classes

Valid encounter class values:

Class	Description
`ambulatory`	Outpatient visit
`emergency`	Emergency department visit
`inpatient`	Hospital admission
`observation`	Observation stay
`home`	Home visit
`virtual`	Telemedicine consultation