Encounters

Base URL: https://api.welkinhealth.com/{tenantName}/{instanceName}/patients/{patientId}/encounters

Encounters represent clinical interactions between care team members and patients – such as appointments, chart notes, or structured clinical visits. Each encounter can have assessments, disposition records, and comments attached.

---

Create Encounter

POST /acme/live/patients/{patientId}/encounters

Create a new clinical encounter for a patient.

Request Body

Field	Type	Required	Description
type	string	Yes	Encounter type: IN_PERSON, TELEHEALTH, or PHONE
status	string	Yes	Initial status: SCHEDULED, IN_PROGRESS, COMPLETED, or CANCELLED
scheduledAt	string (ISO 8601)	Yes	When the encounter is scheduled
duration	integer	No	Duration in minutes
notes	string	No	Clinical notes or summary
providerId	string	No	ID of the care provider conducting encounter

Example Request

POST /acme/live/patients/550e8400-e29b-41d4-a716-446655440000/encounters
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "IN_PERSON",
  "status": "SCHEDULED",
  "scheduledAt": "2026-03-25T10:00:00Z",
  "duration": 30,
  "notes": "Follow-up appointment for hypertension management",
  "providerId": "d8f4c8a2-7b1e-4d39-9c7f-8e5a1b2c3d4e"
}

Example Response

{
  "id": "e7f9d5b3-2c8a-4e1f-9a6b-7c1e3d5f8a9b",
  "patientId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "IN_PERSON",
  "status": "SCHEDULED",
  "scheduledAt": "2026-03-25T10:00:00Z",
  "completedAt": null,
  "duration": 30,
  "notes": "Follow-up appointment for hypertension management",
  "providerId": "d8f4c8a2-7b1e-4d39-9c7f-8e5a1b2c3d4e",
  "createdAt": "2026-03-19T14:30:22Z"
}

---

Get All Encounters

GET /acme/live/patients/{patientId}/encounters

List all encounters for a patient with optional filtering.

Query Parameters

Parameter	Type	Required	Description
type	string	No	Filter by encounter type
status	string	No	Filter by status
startDate	string (ISO 8601)	No	Start date for date range filter
endDate	string (ISO 8601)	No	End date for date range filter
page	integer	No	Page number (default: 0)
size	integer	No	Results per page (default: 20)

Example Request

GET /acme/live/patients/550e8400-e29b-41d4-a716-446655440000/encounters?status=COMPLETED&page=0&size=10
Authorization: Bearer {token}

Example Response

{
  "content": [
    {
      "id": "a1b2c3d4-e5f6-4a8b-9c0d-1e2f3a4b5c6d",
      "patientId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "IN_PERSON",
      "status": "COMPLETED",
      "scheduledAt": "2026-03-18T09:00:00Z",
      "completedAt": "2026-03-18T09:30:00Z",
      "duration": 30,
      "notes": "Patient discussed medication adherence",
      "providerId": "d8f4c8a2-7b1e-4d39-9c7f-8e5a1b2c3d4e",
      "createdAt": "2026-03-18T08:45:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-4b9c-0d1e-2f3a4b5c6d7e",
      "patientId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "TELEHEALTH",
      "status": "COMPLETED",
      "scheduledAt": "2026-03-15T14:00:00Z",
      "completedAt": "2026-03-15T14:25:00Z",
      "duration": 25,
      "notes": "Blood pressure review",
      "providerId": "d8f4c8a2-7b1e-4d39-9c7f-8e5a1b2c3d4e",
      "createdAt": "2026-03-15T13:50:00Z"
    }
  ],
  "page": 0,
  "size": 10,
  "totalElements": 2,
  "totalPages": 1
}

---

Get Encounter by ID

GET /acme/live/patients/{patientId}/encounters/{encounterId}

Retrieve details of a specific encounter.

Path Parameters

Parameter	Type	Required	Description
patientId	string	Yes	Patient UUID
encounterId	string	Yes	Encounter UUID

Example Request

GET /acme/live/patients/550e8400-e29b-41d4-a716-446655440000/encounters/e7f9d5b3-2c8a-4e1f-9a6b-7c1e3d5f8a9b
Authorization: Bearer {token}

Example Response

{
  "id": "e7f9d5b3-2c8a-4e1f-9a6b-7c1e3d5f8a9b",
  "patientId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "IN_PERSON",
  "status": "COMPLETED",
  "scheduledAt": "2026-03-25T10:00:00Z",
  "completedAt": "2026-03-25T10:35:00Z",
  "duration": 35,
  "notes": "Patient responding well to medication adjustments",
  "providerId": "d8f4c8a2-7b1e-4d39-9c7f-8e5a1b2c3d4e",
  "createdAt": "2026-03-19T14:30:22Z"
}

---

Update Encounter

PATCH /acme/live/patients/{patientId}/encounters/{encounterId}

Update encounter notes and status.

Request Body

Field	Type	Required	Description
status	string	No	New status (SCHEDULED, IN_PROGRESS, COMPLETED, CANCELLED)
notes	string	No	Updated clinical notes

Example Request

PATCH /acme/live/patients/550e8400-e29b-41d4-a716-446655440000/encounters/e7f9d5b3-2c8a-4e1f-9a6b-7c1e3d5f8a9b
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "COMPLETED",
  "notes": "Patient reviewed lab results. Adjusted insulin dosage."
}

Example Response

{
  "id": "e7f9d5b3-2c8a-4e1f-9a6b-7c1e3d5f8a9b",
  "patientId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "IN_PERSON",
  "status": "COMPLETED",
  "scheduledAt": "2026-03-25T10:00:00Z",
  "completedAt": "2026-03-25T10:35:00Z",
  "duration": 35,
  "notes": "Patient reviewed lab results. Adjusted insulin dosage.",
  "providerId": "d8f4c8a2-7b1e-4d39-9c7f-8e5a1b2c3d4e",
  "updatedAt": "2026-03-25T10:35:00Z"
}

---

Delete Encounter

DELETE /acme/live/patients/{patientId}/encounters/{encounterId}

Delete an encounter.

Path Parameters

Parameter	Type	Required	Description
patientId	string	Yes	Patient UUID
encounterId	string	Yes	Encounter UUID

Example Request

DELETE /acme/live/patients/550e8400-e29b-41d4-a716-446655440000/encounters/e7f9d5b3-2c8a-4e1f-9a6b-7c1e3d5f8a9b
Authorization: Bearer {token}

Example Response

{
  "success": true,
  "message": "Encounter deleted successfully"
}