Appointment

An appointment is a booked chunk of time between a provider and a patient. Each appointment has a unique Zoom url link attached to it.

The appointment model

Properties

Name
id
Type
string
Description
Unique identifier for the appointment.
Name
object
Type
string
Description
Always 'appointment'.
Name
generated_from_type
Type
string
Description
Only applies if the patient self-booked the appointment. Whether this appointment was created from a rule or override.
Possible values:
rule
override
Name
generated_from
Type
string
Description
Only applies if the patient self-booked the appointment. Which rule or override this appointment was created from.
Name
appointment_type
Type
string
Description
Only applies to external appointments. Type of appointment this is.
Name
name
Type
string
Description
Name of the appointment.
Name
description
Type
string
Description
Description of the appointment.
Name
group
Type
boolean
Description
Whether is appointment is a group appointment.
Name
internal
Type
boolean
Description
Whether is appointment is an internal appointment.
Name
timezone
Type
string
Description
Timezone of the appointment.
Name
recurrence_rules
Type
array of objects
Description
Recurrence rules describing how this appointment repeats.
Name
recurrence_id
Type
string
Description
Identifier grouping appointments that belong to the same recurrence.
Name
recurring
Type
object
Description
Recurrence for the appointment.
Name
start_time
Type
date-time
Description
Planned start time (in ISO-8601 format) of the appointment.
Name
end_time
Type
date-time
Description
Planned end time (in ISO-8601 format) of the appointment.
Name
actual_start_time
Type
date-time
Description
Only applies to non-recurring appointments. Actual start time (in ISO-8601 format) of the appointment.
Name
actual_end_time
Type
date-time
Description
Only applies to non-recurring appointments. Actual end time (in ISO-8601 format) of the appointment.
Name
host
Type
string
Description
Host of the appointment.
Name
attendees
Type
array of objects
Description
List of attendees for the attendees.
Name
observers
Type
array of objects
Description
Observers of the appointment.
Name
reference_patients
Type
array of strings
Description
Only applies to internal appointments. Patients that this appointment is about.
Name
charged_while_booking
Type
object
Description
Amount that was charged to the patient to book the appointment.
Name
charge_after_appointment
Type
object
Description
Amount to charge the patient once the appointment is successfully completed
Name
charged_externally
Type
number
Description
Amount that was charged externally (off-platform) in $ to the patient. For example, if the patient paid $100 in cash, this would be 100.
Name
interaction_type
Type
string
Description
Interaction type.
Possible values:
video_call
in_person

Name
service_facility
Type
string
Description
Service facility where the appointment takes place.
Name
location
Type
object
Description
Only applies if 'interaction_type' is 'in_person.'
Address of the appointment.
Name
status_history
Type
array of objects
Description
Status history of the appointment.
Name
visit_note
Type
string
Description
Visit note created for this appointment.
Name
insurance_claim
Type
string
Description
Insurance claim associated with this appointment.
Name
external_accounts
Type
object
Description
External account identifiers (e.g. Outlook) linked to this appointment.
Name
external_id
Type
string
Description
A client-specified unique ID to associate with this appointment.
Name
created_by
Type
string
Description
Creator of the appointment.
Name
created_at
Type
date-time
Description
Timestamp (in ISO 8601 format) of when the appointment was created.
Name
last_updated_at
Type
date-time
Description
Timestamp (in ISO 8601 format) of when the appointment was last updated.

Response

{
    "id": "appt_2UxtAULYUrX7GVsTKePy",
    "object": "appointment",

    "generated_from": "rule_2UxtAULYUrX7GVsTKePy",
    "generated_from_type": "rule",
    "appointment_type": "aptp_3XxtAULYUrX7GVsTKePy",
    "name": "Annual Check-in",
    "description": "Annual check-in appointment for all patients",
    "group": false,
    "internal": false,

    "recurring": {
        "is_recurring": false
    },
    "charged_while_booking": {
      "enabled": true,
      "auto_charge_if_possible": true,
      "product": "prod_3XxtAULYUrX7GVsTKePy",
    },
    "charge_after_appointment": {
      "enabled": false
    },
    "charged_externally": 0,

    "start_time": "2024-04-10T13:30:21.724Z",
    "end_time": "2024-04-10T14:30:21.724Z",
    "actual_start_time": "2024-04-10T13:30:21.724Z",
    "actual_end_time": "2024-04-10T14:30:21.724Z",
    "host": "user_Z1zXZKvqrpwxbznuW6lJ",
    "attendees": [{
        "id": 1,
        "attendee":"user_IsW3SoxZQxW0agHKyP2V",
        "attendance_status": "going",
        "no_show": false,
        "payment_status": "not_applicable",
        "last_updated_at": "2024-04-10T13:20:21.724Z"
    }],
    "reference_patients": [],

    "interaction_type": "video_call",
    "video_call": {
        "join_url" : "https://us06web.zoom.us/j/85129814133",
        "meeting_id": "85129814133"
    },
    "location": {},
    "status_history": [
        {
            "status": "scheduled",
            "changed_by": "user_xeDpGyt67wTor93qKtS7",
            "changed_at": "2024-04-10T13:20:21.724Z"
        }
    ],
    "visit_note": "note_wTor93qKtS7xeDpGyt67",

    "external_id": "tS7xeDpGytFHKJK01ksjnfwwro",

    "created_by": "user_xeDpGyt67wTor93qKtS7",
    "created_at": "2024-04-10T13:20:21.724Z",
    "last_updated_at": "2024-04-10T13:20:21.724Z"
}

POST/v2/appointments

Create an appointment

Creates a new appointment.

Required attributes

Name
generated_from_type
Type
string
Description
Only applies if the patient self-booked the appointment. Whether this appointment was created from a rule or override.
Possible values:
rule
override
Name
generated_from
Type
string
Description
Only applies if the patient self-booked the appointment. Which rule or override this appointment was created from.
Name
appointment_type
Type
string
Description
Only applies to external appointments. Type of appointment this is.
Name
name
Type
string
Description
Name of the appointment.
Name
description
Type
string
Description
Description of the appointment.
Name
group
Type
boolean
Description
Whether is appointment is a group appointment.
Name
internal
Type
boolean
Description
Whether is appointment is an internal appointment.
Name
start_time
Type
date-time
Description
Planned start time (in ISO-8601 format) of the appointment.
Name
end_time
Type
date-time
Description
Planned end time (in ISO-8601 format) of the appointment.
Name
host
Type
string
Description
Host of the appointment.
Name
attendees
Type
array of strings
Description
Attendees of the appointment.

Optional attributes

Name
status
Type
string
Description
Status of the appointment. Defaults to 'scheduled'.
Possible values:
scheduled
started
completed
cancelled
rescheduled
Name
reference_patients
Type
array of strings
Description
Only applies to internal appointments. Patients that this appointment is about. about.
Name
external_id
Type
string
Description
A client-specified unique ID to associate with this appointment.

Request

POST

/v2/appointments

curl -X POST "https://{{base_subdomain}}.avonhealth.com/v2/appointments" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}" \
  -H "Content-Type: application/json" \
  --data '{
    "generated_from_type": "rule",
    "generated_from": "Example",
    "appointment_type": "Example",
    "name": "Example",
    "description": "Example",
    "group": true,
    "internal": true,
    "start_time": "2025-01-15T14:30:00.000Z"
  }'

Response

    {
        "id": "appt_2UxtAULYUrX7GVsTKePy",
        "object": "appointment",

        "generated_from": "rule_2UxtAULYUrX7GVsTKePy",
        "generated_from_type": "rule",
        "appointment_type": "aptp_3XxtAULYUrX7GVsTKePy",
        "name": "Annual Check-in",
        "description": "Annual check-in appointment for all patients",
        "group": false,
        "internal": false,

        "recurring": {
            "is_recurring": false
        },

        "start_time": "2024-04-10T13:30:21.724Z",
        "end_time": "2024-04-10T14:30:21.724Z",
        "actual_start_time": "2024-04-10T13:30:21.724Z",
        "actual_end_time": "2024-04-10T14:30:21.724Z",
        "host": "user_Z1zXZKvqrpwxbznuW6lJ",
        "attendees": [{
            "id": 1,
            "attendee":"user_IsW3SoxZQxW0agHKyP2V",
            "attendance_status": "going",
            "no_show": false,
            "payment_status": "not_applicable",
            "last_updated_at": "2024-04-10T13:20:21.724Z"
        }],
        "reference_patients": [],

        "charged_while_booking": {
          "enabled": true,
          "auto_charge_if_possible": true,
          "product": "prod_3XxtAULYUrX7GVsTKePy",
        },
        "charge_after_appointment": {
          "enabled": false
        },
        "charged_externally": 0,

        "interaction_type": "video_call",
        "video_call": {
            "join_url" : "https://us06web.zoom.us/j/85129814133",
            "meeting_id": "85129814133"
        },
        "location": {},
        "status_history": [
            {
                "status": "scheduled",
                "changed_by": "user_xeDpGyt67wTor93qKtS7",
                "changed_at": "2024-04-10T13:20:21.724Z"
            }
        ],
        "visit_note": "note_wTor93qKtS7xeDpGyt67",

        "external_id": "tS7xeDpGytFHKJK01ksjnfwwro",

        "created_by": "user_xeDpGyt67wTor93qKtS7",
        "created_at": "2024-04-10T13:20:21.724Z",
        "last_updated_at": "2024-04-10T13:20:21.724Z"
    }

GET/v2/appointments/:id

Retrieve an appointment

Retrieves the specified appointment object.

Request

GET

/v2/appointments/:id

curl "https://{{base_subdomain}}.avonhealth.com/v2/appointments/:id" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}"

Response

    {
       "id": "appt_2UxtAULYUrX7GVsTKePy",
        "object": "appointment",

        "generated_from": "rule_2UxtAULYUrX7GVsTKePy",
        "generated_from_type": "rule",
        "appointment_type": "aptp_3XxtAULYUrX7GVsTKePy",
        "name": "Annual Check-in",
        "description": "Annual check-in appointment for all patients",
        "group": false,
        "internal": false,

        "recurring": {
            "is_recurring": false
        },

        "start_time": "2024-04-10T13:30:21.724Z",
        "end_time": "2024-04-10T14:30:21.724Z",
        "actual_start_time": "2024-04-10T13:30:21.724Z",
        "actual_end_time": "2024-04-10T14:30:21.724Z",
        "host": "user_Z1zXZKvqrpwxbznuW6lJ",
        "attendees": [{
            "id": 1,
            "attendee":"user_IsW3SoxZQxW0agHKyP2V",
            "attendance_status": "going",
            "no_show": false,
            "payment_status": "not_applicable",
            "last_updated_at": "2024-04-10T13:20:21.724Z"
        }],
        "reference_patients": [],

        "charged_while_booking": {
          "enabled": true,
          "auto_charge_if_possible": true,
          "product": "prod_3XxtAULYUrX7GVsTKePy",
        },
        "charge_after_appointment": {
          "enabled": false
        },
        "charged_externally": 0,

        "interaction_type": "video_call",
        "video_call": {
            "join_url" : "https://us06web.zoom.us/j/85129814133",
            "meeting_id": "85129814133"
        },
        "location": {},
        "status_history": [
            {
                "status": "scheduled",
                "changed_by": "user_xeDpGyt67wTor93qKtS7",
                "changed_at": "2024-04-10T13:20:21.724Z"
            }
        ],
        "visit_note": "note_wTor93qKtS7xeDpGyt67",

        "external_id": "tS7xeDpGytFHKJK01ksjnfwwro",

        "created_by": "user_xeDpGyt67wTor93qKtS7",
        "created_at": "2024-04-10T13:20:21.724Z",
        "last_updated_at": "2024-04-10T13:20:21.724Z"
    }

POST/v2/appointments/:id

Update an appointment

Update the specified appointment object by setting the values of the parameters passed. Any other parameters not provided will not be modified.

Required attributes

Optional attributes

Name
name
Type
string
Description
Name of the appointment.
Name
description
Type
string
Description
Description of the appointment.
Name
status
Type
string
Description
Status to update the appointment to.
Possible values:
scheduled
started
completed
cancelled
rescheduled
Name
actual_start_time
Type
date-time
Description
Actual start time (in ISO-8601 format) of the appointment.
Name
actual_end_time
Type
date-time
Description
Actual end time (in ISO-8601 format) of the appointment.
Name
new_attendees
Type
array of strings
Description
List of attendees to add to the appointment.
Name
removed_attendees
Type
array of strings
Description
List of attendees to remove from the appointment.
Name
reference_patients
Type
array of strings
Description
Only applies to internal appointments. Patients that this appointment is about.
Name
external_id
Type
string
Description
A client-specified unique ID to associate with this appointment.

Request

POST

/v2/appointments/:id

curl -X POST "https://{{base_subdomain}}.avonhealth.com/v2/appointments/:id" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}" \
  -H "Content-Type: application/json" \
  --data '{}'

Response

    {
       "id": "appt_2UxtAULYUrX7GVsTKePy",
        "object": "appointment",

        "generated_from": "rule_2UxtAULYUrX7GVsTKePy",
        "generated_from_type": "rule",
        "appointment_type": "aptp_3XxtAULYUrX7GVsTKePy",
        "name": "Annual Check-in",
        "description": "Annual check-in appointment for all patients",
        "group": false,
        "internal": false,

        "recurring": {
            "is_recurring": false
        },

        "start_time": "2024-04-10T13:30:21.724Z",
        "end_time": "2024-04-10T14:30:21.724Z",
        "actual_start_time": "2024-04-10T13:30:21.724Z",
        "actual_end_time": "2024-04-10T14:30:21.724Z",
        "host": "user_Z1zXZKvqrpwxbznuW6lJ",
        "attendees": [{
            "id": 1,
            "attendee":"user_IsW3SoxZQxW0agHKyP2V",
            "attendance_status": "going",
            "no_show": false,
            "payment_status": "not_applicable",
            "last_updated_at": "2024-04-10T13:20:21.724Z"
        }],
        "reference_patients": [],

        "charged_while_booking": {
          "enabled": true,
          "auto_charge_if_possible": true,
          "product": "prod_3XxtAULYUrX7GVsTKePy",
        },
        "charge_after_appointment": {
          "enabled": false
        },
        "charged_externally": 0,

        "interaction_type": "video_call",
        "video_call": {
            "join_url" : "https://us06web.zoom.us/j/85129814133",
            "meeting_id": "85129814133"
        },
        "location": {},
        "status_history": [
            {
                "status": "scheduled",
                "changed_by": "user_xeDpGyt67wTor93qKtS7",
                "changed_at": "2024-04-10T13:20:21.724Z"
            }
        ],
        "visit_note": "note_wTor93qKtS7xeDpGyt67",

        "external_id": "tS7xeDpGytFHKJK01ksjnfwwro",

        "created_by": "user_xeDpGyt67wTor93qKtS7",
        "created_at": "2024-04-10T13:20:21.724Z",
        "last_updated_at": "2024-04-10T13:20:21.724Z"
    }

GET/v2/appointments

List all appointments

Returns a list of all appointments. Pass attributes as query params to filter the list of appointments based on that criteria.

Optional query parameters

Name
host
Type
string
Description
Host ID to filter by.
Name
attendees
Type
array of strings
Description
List of attendees to filter by.
Name
search_from
Type
date-time
Description
Timestamp in ISO 8601 format. Only return appointments that start after this time.
Name
search_until
Type
date-time
Description
Timestamp in ISO 8601 format. Only return appointments that start before this time.
Name
status
Type
string
Description
Status to filter by.

Request

GET

/v2/appointments

curl "https://{{base_subdomain}}.avonhealth.com/v2/appointments?host=Example&attendees=" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}"

Response

    {
      "object": "list",
      "data": [
        {
          "id": "appt_2UxtAULYUrX7GVsTKePy",
          "object": "appointment",

          "generated_from": "rule_2UxtAULYUrX7GVsTKePy",
          "generated_from_type": "rule",
          "appointment_type": "aptp_3XxtAULYUrX7GVsTKePy",
          "name": "Annual Check-in",
          "description": "Annual check-in appointment for all patients",
          "group": false,
          "internal": false,

          "recurring": {
              "is_recurring": false
          },

          "start_time": "2024-04-10T13:30:21.724Z",
          "end_time": "2024-04-10T14:30:21.724Z",
          "actual_start_time": "2024-04-10T13:30:21.724Z",
          "actual_end_time": "2024-04-10T14:30:21.724Z",
          "host": "user_Z1zXZKvqrpwxbznuW6lJ",
          "attendees": [{
              "id": 1,
              "attendee": "user_IsW3SoxZQxW0agHKyP2V",
              "attendance_status": "going",
              "no_show": false,
              "payment_status": "not_applicable",
              "last_updated_at": "2024-04-10T13:20:21.724Z"
          }],
          "reference_patients": [],

          "charged_while_booking": {
            "enabled": true,
            "auto_charge_if_possible": true,
            "product": "prod_3XxtAULYUrX7GVsTKePy",
          },
          "charge_after_appointment": {
            "enabled": false
          },
          "charged_externally": 0,

          "interaction_type": "video_call",
          "video_call": {
              "join_url" : "https://us06web.zoom.us/j/85129814133",
              "meeting_id": "85129814133"
          },
          "location": {},
          "status_history": [
              {
                  "status": "scheduled",
                  "changed_by": "user_xeDpGyt67wTor93qKtS7",
                  "changed_at": "2024-04-10T13:20:21.724Z"
              }
          ],
          "visit_note": "note_wTor93qKtS7xeDpGyt67",

          "external_id": "tS7xeDpGytFHKJK01ksjnfwwro",

          "created_by": "user_xeDpGyt67wTor93qKtS7",
          "created_at": "2024-04-10T13:20:21.724Z",
          "last_updated_at": "2024-04-10T13:20:21.724Z"
        },
      ]
    }