Standard Objects

​

Commonly-reused generic objects

​

uuid

string (UUID v4 format, with lowercase letters, 32 hexadecimal characters with four hyphens: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX)

If you are generating UUIDs (e.g., for the clinician_appointment_id for a new visit you’re creating), you should generate them with UUID v4.

​

url

string (url, like https://example.com/path)

​

date

string (ISO 8601 date format, i.e., YYYY-MM-DD)

​

datetime

string (ISO 8601 date time format as described below)

When providing inputs to our API, we expect your date times to in ISO 8601 format. We require the timezone to be explicitly included; date times with no timezone information will be rejected.

Our API is guaranteed to output date times in ISO 8601 format with the additional restrictions described in RFC 7493 (“I-JSON”) § 4.3:

• Uppercase letters are used instead of lowercase letters.
• The timezone is always explicitly included, never left implicit.
• Trailing seconds are always included, even when their value is “00.”

​

duration

number (positive integer, we recommend this be in multiples of 15)

​

range

object

• start_datetime : datetime
• end_datetime : datetime

​

phone

string (E.164 format, e.g., +15556668888 i.e., the plus character, followed by country code, followed by phone digits; no spaces, hyphens, or other characters allowed)

​

email

string (valid email format)

​

zipcode

string (numeric, 5 digits)

​

address

object

• line1 : string (non-empty)
• line2 : string (non-empty or empty)
• city : string (non-empty)
• state : string (two characters, valid state abbreviation)
• zip_code : zipcode

​

timezone

string (IANA code, like "America/Los_Angeles")

​

recurrence

object

• rrule : string (RFC-5545 (iCalendar) compatible recurrence object)
• exdate : list[datetime ]

​

Visit-related objects:

​

contact

object

• first_name : string (non-empty)
• last_name : string (non-empty)
• phone : phone | null
• email : email | null

​

encounter_to_create

object

• patient_id : uuid
• clinician_appointment_id ****: uuid
• services : array[object]
  • service_id : uuid
  • optional service_completion_outcome : service_completion_outcome
• optional encounter_outcome : encounter_outcome
• optional encounter_outcome_notes : string (potentially empty)

See Encounter for more details.

​

potential_visit

object

Where:

• service_area_id : uuid

• address : address

• clinic_id : uuid | null ` When:

• duration_minutes : duration | null

Who:

• clinician_appointments : array[object]
  • clinician_appointment_id : uuid
  • is_virtual : boolean
  • start_offset_minutes : duration | null
  • duration_override_minutes : duration | null

What:

• created_from_service_bundle_id : uuid | null
• encounters : array[object]
  • patient_id : uuid
  • clinician_appointment_id : uuid
  • services : array[object]
    • service_id : uuid

See Potential Visit for more details.

​

visit_request

object

​

clinician_appointment_to_create

object

• clinician_appointment_id : uuid
• is_virtual : boolean
• optional clinician_id : uuid | null
• optional start_offset_minutes : duration | null
• optional duration_override_minutes : duration | null
• optional clinician_appointment_status : clinician_appointment_status

​

Visit lifecycle objects:

​

summary_status

string (one of the following)

• "UNSCHEDULED"
• "SCHEDULED"
• "CONFIRMED"
• "EN_ROUTE"
• "AT_LOCATION"
• "IN_REVIEW"
• "COMPLETED"
• "OTHER_OUTCOME"
• "CANCELED"

​

priority

string (one of the following)

• "STANDARD"
• "HIGH"

​

patient_confirmation_outcome

string (one of the following)

• "NONE"
  • No attempt has yet been made to confirm the visit with the patient.
• "DECLINED"
  • Patient has indicated they cannot make it to the visit.
• "ACCEPTED"
  • Patient has indicated that will be present for the visit.
  • When handling patient-led or synchronous scheduling (where a scheduler on the phone with the patient), this is the confirmation status to use when creating the visit.

​

clinician_appointment_status

string (one of the following)

• "NOT_STARTED"
• "EN_ROUTE"
• "AT_LOCATION"
• "ENDED"

​

encounter_outcome

string (one of the following)

• "NONE" (associated clinician appointment has not yet ended)
• "PATIENT_DID_NOT_SHOW" (patient was not present for visit with clinician)
• "SUCCESSFUL" (implies all services were performed successfully)
• "UNSUCCESSFUL"(some services were not performed successfully)

​

service_completion_outcome

string (one of the following)

• "NONE"
  • No outcome reported yet.
• "SUCCESSFUL"
  • The clinician reports the service was completed successfully.
• "UNSUCCESSFUL"
  • The clinician reports there were issues completing the service.

​

Patient-related objects:

​

sex

string (one of the following)

• "M" Male
• "F" Female
• "I" Intersex
• "U" Unknown

​

language

string (one of the following)

• "en" English
• "es" Spanish
• "km" Khmer
• "vi" Vietnamese
• "zh" Chinese
• "fr" French
• "ar" Arabic
• "fa" Persian
• "tl" Tagalog
• "ur" Urdu
• "ko" Korean
• "ru" Russian
• "de" German

These are ISO 639-1 language codes.

If no languages are included, then we by default assume that clinicians speak English and patients prefer English.

​

communication_settings

object (simple key-value pair)

• allows_automated_calls : boolean
• allows_clinician_calls : boolean
• allows_automated_sms : boolean
• allows_clinician_sms : boolean
• allows_automated_emails : boolean

​

Metadata objects:

​

metadata

object (simple key-value pair)

• [string] : string (non-empty)

​

metadata_mutation

object

• [string] : string (non-empty) to add or edit a key-value pair
• [string] : null to delete a key-value pair

​

Pagination objects:

​

pagination_input

object

• offset : int (minimum 0)
• count_limit : int (minimum 1, maximum 100)

​

pagination_output

object

• offset : int
• count_limit : int
• total_records : int

​

Misc other objects:

​

service

object

• service_id : uuid
• name : string
• description : string
• duration_minutes : integer
• is_virtual: boolean

​

clinician_filter

object

• clinician_appointment_id : uuid
• clinicians : clinicians_array

​

territories_array

array[object]

• territory_id : uuid

​

clinicians_array

array[object]

• clinician_id : uuid

​

patients_array

array[object]

• patient_id : uuid

​

clinics_array

array[object]

• clinic_id : uuid

​

clinician

object

• clinician_id : uuid
• first_name : string (non-empty)
• last_name : string (non-empty)
• email : email
• phone : phone | null
• address : address | null
• default_shift_options : object
  • coverage : coverage
• language_codes : array[language]
• qualifications : array[object]
  • qualificiation_id : uuid

​

shift

object

• shift_id : uuid

“Who” fields.

• clinician_id : uuid

“When” fields.

• timezone : timezone
• start_datetime : datetime
• end_datetime : datetime
• optional recurrence : recurrence | null

“Where” fields.

• coverage : coverage

Extra fields.

• notes : string (potentially empty)

​

shift_block

object

• shift_block_id : uuid

“Who” fields.

• clinicians : clinicians_array

“When” fields.

• timezone : timezone
• start_datetime : datetime
• end_datetime : datetime
• recurrence: recurrence | null

“Where” fields.

• start_address : address | null

“Extra” fields.

• notes: string (potentially empty)

​

care_team

object

• care_team_id : uuid
• patients : patients_array
• clinicians : clinicians_array

​

coverage

object

• in_person : object
  • territories : territories_array
  • clinics : clinics_array
• virtual : object
  • territories : territories_array
  • clinics : clinics_array

​

doc_type_code

string (must be one of the following)

• "REQUISITION"
• "PRESCRIPTION"
• "UNKNOWN"
• …