# 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

```bash
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

```json
{
  "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

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

### Example Response

```json
{
  "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

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

### Example Response

```json
{
  "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

```bash
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

```json
{
  "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

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

### Example Response

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/developer-and-integration-guide/api-reference/encounters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.