Create Encounter - Documentation

curl -X 'POST' \
  'http://localhost:5001/encounters' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "clinicId": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
  "reviewType": "synchronous",
  "serviceQueue": "provider_network",
  "patientId": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
  "treatmentIds": [
    "45ab34be-8d6e-4037-a0e3-a60b45169f09"
  ],
  "additionalNotes": "Patient reported feeling better after treatment",
  "documentIds": [],
  "scheduledDay": "2025-12-13",
  "scheduledTime": "13:30:00",
  "scheduledTimeZone": "America/Los_Angeles",
  "slotDurationMinutes": 30
}'

{
  "id": 1,
  "gfeId": "ES00000001",
  "clinicId": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
  "providerId": null,
  "patientId": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
  "reviewType": "synchronous",
  "serviceQueue": "provider_network",
  "additionalNotes": "Patient reported feeling better after treatment",
  "reviewerId": null,
  "status": "awaiting",
  "isActive": true,
  "createdAt": "2025-12-04T19:28:43.743Z",
  "updatedAt": "2025-12-04T19:28:43.810Z",
  "createdBy": "34b2cdf8-5599-49c5-9438-eec551d4d196",
  "updatedBy": null,
  "clinic": {
    "id": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
    "legalName": "Demo Clinic Legal Name",
    "displayName": "Demo Clinic",
    "email": "clinic@demo-clinic.com",
    "metadata": null,
    "tenantId": "ec09ad81-8c51-4132-a78d-3bb173413ccb",
    "isActive": true,
    "createdAt": "2025-12-04T18:22:35.954Z",
    "updatedAt": "2025-12-04T18:22:35.954Z",
    "locations": []
  },
  "provider": null,
  "patient": {
    "user_id": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
    "firstName": "Jaime",
    "lastName": "Reyes",
    "dateOfBirth": "1992-01-01T00:00:00.000Z",
    "sex": "male",
    "phone": "5556667777",
    "email": "1blue.beetle@reachtech.org",
    "address1": null,
    "address2": null,
    "cityId": null,
    "stateId": null,
    "countryId": null,
    "postal": null,
    "timezone": null,
    "locale": null,
    "metadata": null,
    "createdAt": "2025-12-04T19:22:47.886Z",
    "updatedAt": "2025-12-04T19:22:47.886Z",
    "notes": null,
    "emergencyContact": null,
    "emergencyContactCode": null,
    "emergencyContactName": null,
    "employer": null,
    "workMobile": null,
    "gfeStateId": null,
    "profileImageBlobPath": null,
    "maritalStatus": null,
    "isHomeAddressSameAsShipping": true,
    "vouchedJobId": null,
    "isVerified": "NOTVERIFIED",
    "vouchedInviteSentDate": null,
    "vouchedReminderCount": 0,
    "vouchedResultMessage": null,
    "vouchedResponsePayload": null,
    "acsUserId": null,
    "city": null,
    "state": null,
    "country": null
  },
  "reviewer": null,
  "encounterZoomMeetings": [],
  "latestReview": {
    "id": "376606df-33ab-4b8f-a218-e3410458dd48",
    "encounterId": 1,
    "note": "",
    "medical_decision_type": null,
    "medical_decision_note": null,
    "signatureBase64": null,
    "createdAt": "2025-12-04T19:28:44.076Z",
    "updatedAt": "2025-12-04T19:28:44.076Z",
    "createdBy": "34b2cdf8-5599-49c5-9438-eec551d4d196"
  },
  "latestTreatments": [],
  "documents": [],
  "order": null,
  "clientNotes": []
}

POST

encounters

curl -X 'POST' \
  'http://localhost:5001/encounters' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "clinicId": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
  "reviewType": "synchronous",
  "serviceQueue": "provider_network",
  "patientId": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
  "treatmentIds": [
    "45ab34be-8d6e-4037-a0e3-a60b45169f09"
  ],
  "additionalNotes": "Patient reported feeling better after treatment",
  "documentIds": [],
  "scheduledDay": "2025-12-13",
  "scheduledTime": "13:30:00",
  "scheduledTimeZone": "America/Los_Angeles",
  "slotDurationMinutes": 30
}'

{
  "id": 1,
  "gfeId": "ES00000001",
  "clinicId": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
  "providerId": null,
  "patientId": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
  "reviewType": "synchronous",
  "serviceQueue": "provider_network",
  "additionalNotes": "Patient reported feeling better after treatment",
  "reviewerId": null,
  "status": "awaiting",
  "isActive": true,
  "createdAt": "2025-12-04T19:28:43.743Z",
  "updatedAt": "2025-12-04T19:28:43.810Z",
  "createdBy": "34b2cdf8-5599-49c5-9438-eec551d4d196",
  "updatedBy": null,
  "clinic": {
    "id": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
    "legalName": "Demo Clinic Legal Name",
    "displayName": "Demo Clinic",
    "email": "clinic@demo-clinic.com",
    "metadata": null,
    "tenantId": "ec09ad81-8c51-4132-a78d-3bb173413ccb",
    "isActive": true,
    "createdAt": "2025-12-04T18:22:35.954Z",
    "updatedAt": "2025-12-04T18:22:35.954Z",
    "locations": []
  },
  "provider": null,
  "patient": {
    "user_id": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
    "firstName": "Jaime",
    "lastName": "Reyes",
    "dateOfBirth": "1992-01-01T00:00:00.000Z",
    "sex": "male",
    "phone": "5556667777",
    "email": "1blue.beetle@reachtech.org",
    "address1": null,
    "address2": null,
    "cityId": null,
    "stateId": null,
    "countryId": null,
    "postal": null,
    "timezone": null,
    "locale": null,
    "metadata": null,
    "createdAt": "2025-12-04T19:22:47.886Z",
    "updatedAt": "2025-12-04T19:22:47.886Z",
    "notes": null,
    "emergencyContact": null,
    "emergencyContactCode": null,
    "emergencyContactName": null,
    "employer": null,
    "workMobile": null,
    "gfeStateId": null,
    "profileImageBlobPath": null,
    "maritalStatus": null,
    "isHomeAddressSameAsShipping": true,
    "vouchedJobId": null,
    "isVerified": "NOTVERIFIED",
    "vouchedInviteSentDate": null,
    "vouchedReminderCount": 0,
    "vouchedResultMessage": null,
    "vouchedResponsePayload": null,
    "acsUserId": null,
    "city": null,
    "state": null,
    "country": null
  },
  "reviewer": null,
  "encounterZoomMeetings": [],
  "latestReview": {
    "id": "376606df-33ab-4b8f-a218-e3410458dd48",
    "encounterId": 1,
    "note": "",
    "medical_decision_type": null,
    "medical_decision_note": null,
    "signatureBase64": null,
    "createdAt": "2025-12-04T19:28:44.076Z",
    "updatedAt": "2025-12-04T19:28:44.076Z",
    "createdBy": "34b2cdf8-5599-49c5-9438-eec551d4d196"
  },
  "latestTreatments": [],
  "documents": [],
  "order": null,
  "clientNotes": []
}

Overview

Creates a new encounter record. This process involves strict validation:

Provider Validation: If provided, the provider must belong to the specified clinic and be clinical staff.
Reviewer Validation: If provided, the reviewer must belong to the clinic, be clinical staff, and hold an active license in the patient’s state.
Tenant Scope: The clinic must belong to the authenticated user’s tenant.
Treatments: At least one treatment ID is required to create initial treatment records (status: pending_review).

The serviceQueue parameter should be hardcoded to "provider_network" for all requests.

Headers

This endpoint uses Machine-to-Machine (M2M) authentication.

Authorization

string

required

Standard Bearer token (e.g., Bearer <your_access_token>). See the M2M Authentication guide for details.

Content-Type

string

required

Must be set to application/json.

Body Parameters

clinicId

string

required

The unique UUID of the clinic.

patientId

string

required

The unique UUID of the patient.

reviewType

string

required

The type of review (e.g., synchronous, asynchronous).

serviceQueue

string

required

The queue to assign the encounter to. Note: This value should be hardcoded to "provider_network".

treatmentIds

array

required

List of treatment UUIDs to associate with this encounter. At least one is required.

reviewerId

string

The unique UUID of the reviewer (optional). If provided, must be valid and licensed in the patient’s state.

providerId

string

The unique UUID of the provider (optional).

additionalNotes

string

Any additional notes regarding the encounter.

documentIds

array

List of document UUIDs to link to the encounter.

Scheduling Parameters (Optional)

scheduledDay

string

Date of the appointment in YYYY-MM-DD format.

scheduledTime

string

Time of the appointment in HH:MM:SS format.

scheduledTimeZone

string

Timezone for the schedule (e.g., America/Los_Angeles).

slotDurationMinutes

integer

Duration of the appointment slot in minutes.

Response Parameters

The response returns the fully created Encounter object with all associated records.

integer

The unique numeric ID of the encounter.

gfeId

string

The Good Faith Exam (GFE) identifier.

status

string

Current status of the encounter (e.g., awaiting).

isActive

boolean

Indicates if the encounter is active.

clinicId

string

UUID of the clinic.

patientId

string

UUID of the patient.

reviewerId

string

UUID of the assigned reviewer.

providerId

string

UUID of the provider.

reviewType

string

Type of review.

serviceQueue

string

Service queue name.

additionalNotes

string

Notes added during creation.

createdAt

string

Creation timestamp.

latestReview

object

Details of the latest review.

Show Properties

string

Review ID.

note

string

Reviewer notes.

medical_decision_type

string

Decision type (e.g., “injectables”).

medical_decision_note

string

Decision notes.

latestTreatments

array

List of treatments associated with the encounter.

Show Item Properties

string

Treatment Record ID.

treatmentId

string

Product/Treatment ID.

status

string

Status (e.g., “indicated”).

status_note

string

Status note.

icd

string

ICD-10 code.

documents

array

Documents linked to the encounter.

Show Item Properties

string

Encounter Document ID.

document

object

Show Document Details

fileUrl

string

URL to access the file.

fileName

string

Name of the file.

docType

string

Type (e.g., “uploaded-form”).

zoomMeeting

object

Zoom meeting details (if scheduled).

Show Properties

meetingId

string

Zoom Meeting ID.

joinUrl

string

URL for participant to join.

startUrl

string

URL for host to start.

startTime

string

Scheduled start time.

status

string

Meeting status.

encounterAppointment

object

Linked appointment details.

Show Properties

appointmentId

string

Appointment UUID.

appointment

object

Show Appointment Details

startAt

string

Start timestamp.

endAt

string

End timestamp.

status

string

Appointment status.

latestVitals

object

Patient vitals snapshot.

Show Properties

weight

string

Patient weight.

height

string

Patient height.

bmi

string

Calculated BMI.

bpSystolic

string

Systolic Blood Pressure.

bpDiastolic

string

Diastolic Blood Pressure.

Status Codes

Status	Description
`201`	Created. Encounter created successfully.
`400`	Bad Request. Validation failed (e.g., invalid reviewer license, provider not in clinic).
`401`	Unauthorized. Invalid or missing authentication token.
`403`	Forbidden. Insufficient permissions or clinic does not belong to tenant.

curl -X 'POST' \
  'http://localhost:5001/encounters' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "clinicId": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
  "reviewType": "synchronous",
  "serviceQueue": "provider_network",
  "patientId": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
  "treatmentIds": [
    "45ab34be-8d6e-4037-a0e3-a60b45169f09"
  ],
  "additionalNotes": "Patient reported feeling better after treatment",
  "documentIds": [],
  "scheduledDay": "2025-12-13",
  "scheduledTime": "13:30:00",
  "scheduledTimeZone": "America/Los_Angeles",
  "slotDurationMinutes": 30
}'

{
  "id": 1,
  "gfeId": "ES00000001",
  "clinicId": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
  "providerId": null,
  "patientId": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
  "reviewType": "synchronous",
  "serviceQueue": "provider_network",
  "additionalNotes": "Patient reported feeling better after treatment",
  "reviewerId": null,
  "status": "awaiting",
  "isActive": true,
  "createdAt": "2025-12-04T19:28:43.743Z",
  "updatedAt": "2025-12-04T19:28:43.810Z",
  "createdBy": "34b2cdf8-5599-49c5-9438-eec551d4d196",
  "updatedBy": null,
  "clinic": {
    "id": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
    "legalName": "Demo Clinic Legal Name",
    "displayName": "Demo Clinic",
    "email": "clinic@demo-clinic.com",
    "metadata": null,
    "tenantId": "ec09ad81-8c51-4132-a78d-3bb173413ccb",
    "isActive": true,
    "createdAt": "2025-12-04T18:22:35.954Z",
    "updatedAt": "2025-12-04T18:22:35.954Z",
    "locations": []
  },
  "provider": null,
  "patient": {
    "user_id": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
    "firstName": "Jaime",
    "lastName": "Reyes",
    "dateOfBirth": "1992-01-01T00:00:00.000Z",
    "sex": "male",
    "phone": "5556667777",
    "email": "1blue.beetle@reachtech.org",
    "address1": null,
    "address2": null,
    "cityId": null,
    "stateId": null,
    "countryId": null,
    "postal": null,
    "timezone": null,
    "locale": null,
    "metadata": null,
    "createdAt": "2025-12-04T19:22:47.886Z",
    "updatedAt": "2025-12-04T19:22:47.886Z",
    "notes": null,
    "emergencyContact": null,
    "emergencyContactCode": null,
    "emergencyContactName": null,
    "employer": null,
    "workMobile": null,
    "gfeStateId": null,
    "profileImageBlobPath": null,
    "maritalStatus": null,
    "isHomeAddressSameAsShipping": true,
    "vouchedJobId": null,
    "isVerified": "NOTVERIFIED",
    "vouchedInviteSentDate": null,
    "vouchedReminderCount": 0,
    "vouchedResultMessage": null,
    "vouchedResponsePayload": null,
    "acsUserId": null,
    "city": null,
    "state": null,
    "country": null
  },
  "reviewer": null,
  "encounterZoomMeetings": [],
  "latestReview": {
    "id": "376606df-33ab-4b8f-a218-e3410458dd48",
    "encounterId": 1,
    "note": "",
    "medical_decision_type": null,
    "medical_decision_note": null,
    "signatureBase64": null,
    "createdAt": "2025-12-04T19:28:44.076Z",
    "updatedAt": "2025-12-04T19:28:44.076Z",
    "createdBy": "34b2cdf8-5599-49c5-9438-eec551d4d196"
  },
  "latestTreatments": [],
  "documents": [],
  "order": null,
  "clientNotes": []
}

Get Patient by ID Get Encounter Status

⌘I

APIs

Authentication

​Overview

​Headers

​Body Parameters

​Scheduling Parameters (Optional)

​Response Parameters

​Status Codes

Overview

Headers

Body Parameters

Scheduling Parameters (Optional)

Response Parameters

Status Codes