Appointment

A booking of a healthcare event among patient(s), practitioner(s), related person(s) and/or device(s) for a specific date/time. This may result in one or more Encounter(s).

https://hl7.org/fhir/R4/appointment.html

This may result in one or more Encounters.

The appointment resource maps to both patient appointments as well as other events in Canvas. Instructions for configuring appointment and note types can be found here.

Related guides:
post
/Appointment

Appointment create

Create an Appointment

It is recommended to utilize the FHIR Slot Search to find appointment times for a specific practitioner.

Prevent Double Booking By default, Canvas does not prevent appointments from being created if there is already an existing appointment for that provider. However, Canvas has a config setting to disable double booking. If double booking is not allowed and the Appointment Create or Appointment Update request is trying to book an appointment for a given Provider that already has a scheduled appointment at that time, you will see a 422 error status with the following error message returned This appointment time is no longer available.

Attributes

resourceType
string

The FHIR Resource name.

contained
array[json]

Contained, inline Resources. Used to store links for telehealth appointments.

This endpoint allows one custom video meeting link to be passed in that will be utilized on the UI over the default provider’s meeting link if the appointment is a telemedicine. You can specify a telehealth meeting link by adding an element in the SupportingInformation attribute where the SupportingInformation.reference is #appointment-meeting-endpoint-0 and matches the contained[0].id attribute of appointment-meeting-endpoint-0. See examples for help.

Click to view child attributes
resourceType
enum [ Endpoint ] required
id
string required

The id of the contained entry. This needs to be appointment-meeting-endpoint-0 and the SupportingInformation.reference will be #appointment-meeting-endpoint-0.

address
string required

The technical base address for connecting to this endpoint.

identifier
array[json]

External Ids for this item.

The identifier list defines additional identifiers that are able to be stored for an appointment.

These identifiers will not be surfaced on the Patient’s chart, but they may help you identify the patient in your system by associating your identifier with the resource’s id.

Click to view child attributes
use
enum [ usual | official | temp | secondary | old ]

The purpose of this identifier. If this is omitted, it will default to usual.

system
string

The namespace for the identifier value.

value
string

The value that is unique

assigner
json

Text representing Organization that issued id. If ommitted it will default to the system of the identifier.

Click to view child attributes
display
string
period
json

Time period when id is/was valid for use.

Click to view child attributes
start
datetime

Starting time with inclusive boundary. If omitted this will default to 1970-01-01.

end
datetime

End time with inclusive boundary, if not ongoing. If ommitted this will default to 2100-12-31.

status
enum [ arrived | booked | cancelled | checked-in | fulfilled | noshow | pending | proposed | entered-in-error ] required

The status of the appointment.

This table shows the mappings of statuses/states an appointment is in within Canvas to the FHIR status attribute.

FHIR StatusCanvas Status
proposedunconfirmed
pendingattempted
bookedconfirmed
arrivedarrived
checked-inroomed
fulfilledexited
noshowno-showed
cancelledcancelled
entered-in-errordeleted

If any of the first 7 FHIR statuses are used, the appointment will appear on the schedule from the dropdown on the Appointment Card in the Schedule view with one of those statuses.

An appointment can be created as cancelled for historical purposes, but it will not appear on the schedule view and will be a restorable note on the patient’s timeline.

The Create endpoint does NOT accept a status of entered-in-error.

appointmentType
json

The style of appointment or patient that has been booked in the slot (not service type). Canvas supports configurable apppointment and note types.

There are a few things to note with this attribute:

1.If the appointmentType attribute is omitted from the body completely, the note type that has Is default appointment type will be used (usually Office Visit if unchanged)

2.If the code / system pair does not exist, you will see a 422 error status with error message Appointment Type does not exist with code: {code} and system: {system}

3.If the code / system pair passed is not marked as Is Scheduleable in Canvas, you will get a 422 error status with error message Note type: {name} is not scheduleable.

Click to view child attributes
coding
array[json]

The type of appointment

Click to view child attributes
system
string

The system of the appointment

code
string

The code of the appointment.

This needs to match a coding in the Appointment and Note Types Canvas Settings and be deemed as Is Scheduleable.

reasonCode
array[json]

Coded reason this appointment is scheduled.

Canvas supports two ways to specify the reason for vist (RFV): structured and unstructured. Both the coding and text attributes are used for Structured RFVs, whereas unstructured RFVs only leverage the text attribute.

Canvas only accepts the first item in the reasonCode list.

If you are taking advantage of our structured reason for visit feature, you can provide a coding that Canvas can use to look up the code value in configured in settings and display the structured RFV matching that code. If Appointment.reasonCode[0].coding[0].code is not a valid ReasonForVisitSettingCoding you will get the error “structured reason for visit with code {code} does not exist”. You will also receive an error if the RFV code in Canvas’ setting’s page is not unique.

The text attribute maps to the free text Reason For Visit command. If you are using the structured reason for visit feature, this text will display as the comment in the command. If you are not using the structured reason for visit feature, then only Appointment.reasonCode[0].text needs to be populated in your message and coding should be omitted.

If this field is omitted (along with the deprecated description field), the RFV command in the appointment note will be defaulted to No description given.

Click to view child attributes
coding
array[json]

Identifies where the definition of the code comes from.

Click to view child attributes
code
string

The code of the reason for visit.

text
string
description [deprecated]
string

Shown on a subject line in a meeting request, or appointment list.

Note: This field is being deprecated in favor of reasonCode. The text in reasonCode and this description attribute will always match.

supportingInformation
array[json] required

Additional information to support the appointment. Currently, Canvas supports the ability to write 2 different types of references:

  1. Location: A reference to a Location captures what Practice Location in Canvas the appointment will take place at.
  2. Meeting Link: For appointments that are telehealth in Canvas, there can be a reference to an endpoint in this list. The reference attribute will need to match an id in the Appointment.contained attribute list, but will need to have a # in front of the reference string. See examples for help. For telehealth appointments where no meeting link reference is supplied, it will default to the practitioner’s personal meeting room link as defined in Canvas Settings.
Click to view child attributes
reference
string required

The reference string of the supporting information.

If the entry is for a Location the format will be "Location/9d3a079f-22c0-4918-96d7-72eb567563ec". You can retrieve this information for a Location Search.

If the entry is for a virtual meeting link, the reference should be #appointment-meeting-endpoint-0.

type
string

Type the reference refers to (e.g. “Location”, “Endpoint”, “Encounter”, “Appointment”).

start
datetime required

When appointment is to take place.

The start attribute determines the start timestamp of the appointment. It is written in instant format for FHIR. Seconds and milliseconds can be omitted, but YYYY-MM-DDTHH:MM are required.

end
datetime required

When appointment is to conclude.

The end attribute is used with the start timestamp to determine the duration in minutes of the appointment. The duration of the appointment must be greater than 0 minutes. It is written in instant format for FHIR. Seconds and milliseconds can be omitted, but YYYY-MM-DDTHH:MM are required.

participant
array[json] required

Participants involved in appointment. At least one object needs to be supplied that corresponds to the practitioner, there will always be a practitioner involved in every appointment type. An optional 2nd object corresponding to the patient reference will be accepted if the appointmentType allows/requires a patient participant.

Click to view child attributes
actor
json required

Reference to person involved in appointment.

Click to view child attributes
reference
string required

The reference string of the practitioner or patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

Value Options Supported:
  • Practitioner/id
  • Patient/id
type
string

Type the reference refers to (e.g. “Patient”, “Practitioner”).

Value Options Supported:
  • Practitioner
  • Patient
status
enum [ accepted ] required

Responses

201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.

Canvas returns the created resource's id as a UUID within the location header and a null response body.

Errors

400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Appointment/{id}

Appointment read

Read an Appointment

Path Parameters

id required
string
The unique identifier for the Appointment

Response Payload Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the appointment.

contained
array[json]

Contained, inline Resources. Used to store links for telehealth appointments.

There will be a reference in the supportingInformation attribute with a type of Endpoint and a reference of #appointment-meeting-endpoint-0 that will match the contained[0].id`.

Click to view child attributes
resourceType
enum [ Endpoint ]
id
string

The id of the contained entry. This needs to be appointment-meeting-endpoint-0 and the SupportingInformation.reference will be #appointment-meeting-endpoint-0.

status
enum [ active ]
connectionType
json
Click to view child attributes
code
string

Protocol/Profile/Standard to be used with this endpoint connection

payloadType
array[json]
Click to view child attributes
coding
array[json]
Click to view child attributes
code
enum [ video-call ]
address
string

The technical base address for connecting to this endpoint.

extension
array[json]

Canvas supports a note identifier extension on this resource for read and search interactions. The note identifier can be used with the Canvas Note API.

Click to view child attributes
url
string

Reference that defines the content of this object.

Value Options Supported:
  • http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string

The valueId field is used for the Note extension and will be the note’s unique identifier.

identifier
array[json]

External Ids for this item.

The identifier list defines additional identifiers that are able to be stored for an appointment.

These identifiers will not be surfaced on the Patient’s chart, but they may help you identify the patient in your system by associating your identifier with the resource’s id.

Click to view child attributes
id
string

Unique id for inter-element referencing

use
enum [ usual | official | temp | secondary | old ]

The purpose of this identifier. If this is omitted, it will default to usual.

system
string

The namespace for the identifier value.

value
string

The value that is unique

period
json

Time period when id is/was valid for use.

Click to view child attributes
start
datetime

Starting time with inclusive boundary. If omitted this will default to 1970-01-01.

end
datetime

End time with inclusive boundary, if not ongoing. If ommitted this will default to 2100-12-31.

status
enum [ arrived | booked | cancelled | checked-in | fulfilled | noshow | pending | proposed | entered-in-error ]

The status of the appointment.

This table shows the mappings of statuses/states an appointment is in within Canvas to the FHIR status attribute.

FHIR StatusCanvas Status
proposedunconfirmed
pendingattempted
bookedconfirmed
arrivedarrived
checked-inroomed
fulfilledexited
noshowno-showed
cancelledcancelled
entered-in-errordeleted

The first 7 statuses come from the dropdown on the Appointment Card in the Schedule view. A cancelled status comes from a patient appointment or an other event being cancelled. The deleted/entered-in-error status is when a checked-in appointment note has been deleted in Canvas.

appointmentType
json

The style of appointment or patient that has been booked in the slot (not service type). Canvas supports configurable apppointment and note types.

Click to view child attributes
coding
array[json]

The type of appointment

Click to view child attributes
system
string

The system of the appointment

code
string

The code of the appointment.

This needs to match a coding in the Appointment and Note Types Canvas Settings and be deemed as Is Scheduleable.

display
string

The display of the appointment

reasonCode
array[json]

Coded reason this appointment is scheduled.

Canvas supports two ways to specify the reason for vist (RFV): structured and unstructured. Both the coding and text attributes are used for Structured RFVs, whereas unstructured RFVs only leverage the text attribute.

Click to view child attributes
coding
array[json]

Identifies where the definition of the code comes from.

Click to view child attributes
system
string

The system of the coding.

code
string

The code of the reason for visit.

display
string

The display name of the coding.

userSelected
boolean

If this coding was chosen directly by the user. In Canvas this indicates if the coding is currently active or not.

text
string
description [deprecated]
string

Shown on a subject line in a meeting request, or appointment list.

Note: This field is being deprecated in favor of reasonCode. The text in reasonCode and this description attribute will always match.

supportingInformation
array[json]

Additional information to support the appointment. Currently, Canvas supports different types of references in this list:

  1. Location: A reference to a Location captures what Practice Location in Canvas the appointment will take place at.
  2. Meeting Link: For appointments that are telehealth in Canvas, there will be a reference to an endpoint in this list. The reference attribute will match an id in the Appointment.contained attribute list. That element will display the url address of the virtual meeting link.
  3. Appointment: If an appointment has been rescheduled, this list could display an associated Appointment reference. If you see a display of Previously Rescheduled Appointment, it means that the appointment you are currently looking at was created after rescheduling the appointment in that Reference. If you see a display of Rescheduled Replacement Appointment, it means that the appointment you are currently looking at is now outdated by a new appointment.
  4. Encounter: If there is any encounter associated with the appointment made in Canvas, the refence will appear in this list.
Click to view child attributes
reference
string

The reference string of the supporting information.

type
string

Type the reference refers to (e.g. “Location”, “Endpoint”, “Encounter”, “Appointment”).

display
string

Display name of the reference

Value Options Supported:
  • Previously Rescheduled Appointment
  • Rescheduled Replacement Appointment
start
datetime

When appointment is to take place.

end
datetime

When appointment is to conclude.

participant
array[json]

Participants involved in appointment. There will be at least one entry for a practitioner. An optional 2nd entry will display if the appointment involves a specific patient. This will be dictated by the appointmentType and if it relates to a generic event or a patient’s appointment.

Click to view child attributes
actor
json

Reference to person involved in appointment.

Click to view child attributes
reference
string

The reference string of the practitioner or patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

Value Options Supported:
  • Practitioner/id
  • Patient/id
type
string

Type the reference refers to (e.g. “Patient”, “Practitioner”).

Value Options Supported:
  • Practitioner
  • Patient
status
enum [ accepted ]

Responses

200 OK
Request was successful.

Errors

401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
put
/Appointment/{id}

Appointment update

Update an Appointment This is almost identical to the Appointment Create. The update will only affect fields that are passed in to the body, if any fields are omitted they will be ignored and kept as co are currently set in the Canvas database.

Attributes

resourceType
string

The FHIR Resource name.

id
string required

The identifier of the appointment.

contained
array[json]

Contained, inline Resources. Used to store links for telehealth appointments.

This endpoint allows one custom video meeting link to be passed in that will be utilized on the UI over the default provider’s meeting link if the appointment is a telemedicine. You can specify a telehealth meeting link by adding an element in the SupportingInformation attribute where the SupportingInformation.reference is #appointment-meeting-endpoint-0 and matches the contained[0].id attribute of appointment-meeting-endpoint-0. See examples for help.

Click to view child attributes
resourceType
enum [ Endpoint ] required
id
string required

The id of the contained entry. This needs to be appointment-meeting-endpoint-0 and the SupportingInformation.reference will be #appointment-meeting-endpoint-0.

address
string required

The technical base address for connecting to this endpoint.

identifier
array[json]

External Ids for this item.

The identifier list defines additional identifiers that are able to be stored for an appointment.

These identifiers will not be surfaced on the Patient’s chart, but they may help you identify the patient in your system by associating your identifier with the resource’s id.

To update an existing identifier, include the id in the identifier[x].id field returned from Read/Search.

The identifier section sent in an update will entirely replace existing identifiers currently within the period.start and period.end dates.

If an identifier already exists in the Canvas database and is not included in the Update message, it will be deleted if and only if the period.end date is in the future.

Click to view child attributes
id
string

Unique id for inter-element referencing

use
enum [ usual | official | temp | secondary | old ]

The purpose of this identifier. If this is omitted, it will default to usual.

system
string

The namespace for the identifier value.

value
string

The value that is unique

assigner
json

Text representing Organization that issued id. If ommitted it will default to the system of the identifier.

Click to view child attributes
display
string
period
json

Time period when id is/was valid for use.

Click to view child attributes
start
datetime

Starting time with inclusive boundary. If omitted this will default to 1970-01-01.

end
datetime

End time with inclusive boundary, if not ongoing. If ommitted this will default to 2100-12-31.

status
enum [ arrived | booked | cancelled | checked-in | fulfilled | noshow | pending | proposed | entered-in-error ] required

The status of the appointment.

This table shows the mappings of statuses/states an appointment is in within Canvas to the FHIR status attribute.

FHIR StatusCanvas Status
proposedunconfirmed
pendingattempted
bookedconfirmed
arrivedarrived
checked-inroomed
fulfilledexited
noshowno-showed
cancelledcancelled
entered-in-errordeleted

If any of the first 7 FHIR statuses are used, the appointment will appear on the schedule from the dropdown on the Appointment Card in the Schedule view with one of those statuses.

An appointment can be updated to cancelled and as a result it will disappear from the schedule view and/or will be a restorable note on the patient’s timeline. Once an appointment is in a cancelled state, it should not be updated to a different status via FHIR, instead the note should be reverted directly in the Patient’s chart before it can be updated via FHIR again.

The Update endpoint does NOT accept a status of entered-in-error.

appointmentType
json

The style of appointment or patient that has been booked in the slot (not service type). Canvas supports configurable apppointment and note types.

There are a few things to note with this attribute:

1.If the appointmentType attribute is omitted from the body completely on an update, the note type will stay as it already is in the Canvas.

2.If the code / system pair does not exist, you will see a 422 error status with error message Appointment Type does not exist with code: {code} and system: {system}

3.If the code / system pair passed is not marked as Is Scheduleable in Canvas, you will get a 422 error status with error message Note type: {name} is not scheduleable.

Click to view child attributes
coding
array[json]

The type of appointment

Click to view child attributes
system
string

The system of the appointment

code
string

The code of the appointment.

This needs to match a coding in the Appointment and Note Types Canvas Settings and be deemed as Is Scheduleable.

reasonCode
array[json]

Coded reason this appointment is scheduled.

Canvas supports two ways to specify the reason for vist (RFV): structured and unstructured. Both the coding and text attributes are used for Structured RFVs, whereas unstructured RFVs only leverage the text attribute.

On an update, if the reasonCode has changed from what is already saved in Canvas, it will create a new RFV command on that appointment. The old reason for visit will be marked as entered-in-error, and the text will no longer display. Below is an example of what an appointment’s note will look like after changing the description multiple times. The originator and entered-in-error will be set to Canvas Bot, which can be seen if you click on the crossed off “Reason for Visit”.

api-update-rfv

If this field is omitted (along with the deprecated description field), the RFV command in the appointment note will stay as it currently is.

Click to view child attributes
coding
array[json]

Identifies where the definition of the code comes from.

Click to view child attributes
code
string

The code of the reason for visit.

text
string
description [deprecated]
string

Shown on a subject line in a meeting request, or appointment list.

Note: This field is being deprecated in favor of reasonCode. The text in reasonCode and this description attribute will always match.

supportingInformation
array[json] required

Additional information to support the appointment. Currently, Canvas supports the ability to write 2 different types of references:

  1. Location: A reference to a Location captures what Practice Location in Canvas the appointment will take place at.
  2. Meeting Link: For appointments that are telehealth in Canvas, there can be a reference to an endpoint in this list. The reference attribute will need to match an id in the Appointment.contained attribute list, but will need to have a # in front of the reference string. See examples for help. For telehealth appointments where no meeting link reference is supplied, it will default to the practitioner’s personal meeting room link as defined in Canvas Settings.
Click to view child attributes
reference
string required

The reference string of the supporting information.

If the entry is for a Location the format will be "Location/9d3a079f-22c0-4918-96d7-72eb567563ec". You can retrieve this information for a Location Search.

If the entry is for a virtual meeting link, the reference should be #appointment-meeting-endpoint-0.

type
string

Type the reference refers to (e.g. “Location”, “Endpoint”, “Encounter”, “Appointment”).

start
datetime required

When appointment is to take place.

The start attribute determines the start timestamp of the appointment. It is written in instant format for FHIR. Seconds and milliseconds can be omitted, but YYYY-MM-DDTHH:MM are required.

end
datetime required

When appointment is to conclude.

participant
array[json] required

Participants involved in appointment. At least one object needs to be supplied that corresponds to the practitioner, there will always be a practitioner involved in every appointment type. An optional 2nd object corresponding to the patient reference will be accepted if the appointmentType allows/requires a patient participant.

Click to view child attributes
actor
json required

Reference to person involved in appointment.

Click to view child attributes
reference
string required

The reference string of the practitioner or patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

Value Options Supported:
  • Practitioner/id
  • Patient/id
type
string

Type the reference refers to (e.g. “Patient”, “Practitioner”).

Value Options Supported:
  • Practitioner
  • Patient
status
enum [ accepted ] required

Responses

200 OK
The server has successfully processed the request.

Canvas returns a null response body.

Errors

400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
412 Precondition Failed
The request depends on a precondition that has not been met.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.

Query Parameters

_id
string

A Canvas-issued unique identifier for the Appointment.

appointment-type
string

Filters by the code and/or system under appointmentType.coding attribute. You can search by just the code value or you can search by the system and code in the format system|code (e.g http://snomed.info/sct|308335008).

location
string

The location of the appointment in the format Location/9d3a079f-22c0-4918-96d7-72eb567563ec.

patient
string

The patient the appointment is for in the format Patient/a39cafb9d1b445be95a2e2548e12a787.

practitioner
string

The practitioner involoved in the appointment in the format Practitioner/3a9cafb9d1b445be95a2e2548e12a787.

date
string

Filter by start time. See Date Filtering for more information.

status
string

The status of the appointment.

Search Values Supported:
  • proposed
  • pending
  • booked
  • arrived
  • checked-in
  • fulfilled
  • noshow
  • cancelled
_sort
string

Triggers sorting of the results by a specific criteria. Adding a - will sort in descending order while the default sorts in ascending order.

Search Values Supported:
  • date
  • patient
  • practitioner
  • -date
  • -patient
  • -practitioner

Response Payload Attributes

resourceType
string

The FHIR Resource name.

type
string

This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .

total
integer

The number of resources that match the search parameter.

link
array[json]

Attributes relevant to pagination, see our Pagination page for more detail.

Click to view child attributes
relation
enum [self|first|next|last]

The relation of the page search

url

The search url for the specific relation

entry
array[json]

The results bundle that lists out each object returned in the search

Click to view child attributes
resource
json

The attributes specific to the resource type, see the Attributes section below

Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the appointment.

contained
array[json]

Contained, inline Resources. Used to store links for telehealth appointments.

There will be a reference in the supportingInformation attribute with a type of Endpoint and a reference of #appointment-meeting-endpoint-0 that will match the contained[0].id`.

Click to view child attributes
resourceType
enum [ Endpoint ]
id
string

The id of the contained entry. This needs to be appointment-meeting-endpoint-0 and the SupportingInformation.reference will be #appointment-meeting-endpoint-0.

status
enum [ active ]
connectionType
json
Click to view child attributes
code
string

Protocol/Profile/Standard to be used with this endpoint connection

payloadType
array[json]
Click to view child attributes
coding
array[json]
Click to view child attributes
code
enum [ video-call ]
address
string

The technical base address for connecting to this endpoint.

extension
array[json]

Canvas supports a note identifier extension on this resource for read and search interactions. The note identifier can be used with the Canvas Note API.

Click to view child attributes
url
string

Reference that defines the content of this object.

Value Options Supported:
  • http://schemas.canvasmedical.com/fhir/extensions/note-id
valueId
string

The valueId field is used for the Note extension and will be the note’s unique identifier.

identifier
array[json]

External Ids for this item.

The identifier list defines additional identifiers that are able to be stored for an appointment.

These identifiers will not be surfaced on the Patient’s chart, but they may help you identify the patient in your system by associating your identifier with the resource’s id.

Click to view child attributes
id
string

Unique id for inter-element referencing

use
enum [ usual | official | temp | secondary | old ]

The purpose of this identifier. If this is omitted, it will default to usual.

system
string

The namespace for the identifier value.

value
string

The value that is unique

period
json

Time period when id is/was valid for use.

Click to view child attributes
start
datetime

Starting time with inclusive boundary. If omitted this will default to 1970-01-01.

end
datetime

End time with inclusive boundary, if not ongoing. If ommitted this will default to 2100-12-31.

status
enum [ arrived | booked | cancelled | checked-in | fulfilled | noshow | pending | proposed | entered-in-error ]

The status of the appointment.

This table shows the mappings of statuses/states an appointment is in within Canvas to the FHIR status attribute.

FHIR StatusCanvas Status
proposedunconfirmed
pendingattempted
bookedconfirmed
arrivedarrived
checked-inroomed
fulfilledexited
noshowno-showed
cancelledcancelled
entered-in-errordeleted

The first 7 statuses come from the dropdown on the Appointment Card in the Schedule view. A cancelled status comes from a patient appointment or an other event being cancelled. The deleted/entered-in-error status is when a checked-in appointment note has been deleted in Canvas.

appointmentType
json

The style of appointment or patient that has been booked in the slot (not service type). Canvas supports configurable apppointment and note types.

Click to view child attributes
coding
array[json]

The type of appointment

Click to view child attributes
system
string

The system of the appointment

code
string

The code of the appointment.

This needs to match a coding in the Appointment and Note Types Canvas Settings and be deemed as Is Scheduleable.

display
string

The display of the appointment

reasonCode
array[json]

Coded reason this appointment is scheduled.

Canvas supports two ways to specify the reason for vist (RFV): structured and unstructured. Both the coding and text attributes are used for Structured RFVs, whereas unstructured RFVs only leverage the text attribute.

Click to view child attributes
coding
array[json]

Identifies where the definition of the code comes from.

Click to view child attributes
system
string

The system of the coding.

code
string

The code of the reason for visit.

display
string

The display name of the coding.

userSelected
boolean

If this coding was chosen directly by the user. In Canvas this indicates if the coding is currently active or not.

text
string
description [deprecated]
string

Shown on a subject line in a meeting request, or appointment list.

Note: This field is being deprecated in favor of reasonCode. The text in reasonCode and this description attribute will always match.

supportingInformation
array[json]

Additional information to support the appointment. Currently, Canvas supports different types of references in this list:

  1. Location: A reference to a Location captures what Practice Location in Canvas the appointment will take place at.
  2. Meeting Link: For appointments that are telehealth in Canvas, there will be a reference to an endpoint in this list. The reference attribute will match an id in the Appointment.contained attribute list. That element will display the url address of the virtual meeting link.
  3. Appointment: If an appointment has been rescheduled, this list could display an associated Appointment reference. If you see a display of Previously Rescheduled Appointment, it means that the appointment you are currently looking at was created after rescheduling the appointment in that Reference. If you see a display of Rescheduled Replacement Appointment, it means that the appointment you are currently looking at is now outdated by a new appointment.
  4. Encounter: If there is any encounter associated with the appointment made in Canvas, the refence will appear in this list.
Click to view child attributes
reference
string

The reference string of the supporting information.

type
string

Type the reference refers to (e.g. “Location”, “Endpoint”, “Encounter”, “Appointment”).

display
string

Display name of the reference

Value Options Supported:
  • Previously Rescheduled Appointment
  • Rescheduled Replacement Appointment
start
datetime

When appointment is to take place.

end
datetime

When appointment is to conclude.

participant
array[json]

Participants involved in appointment. There will be at least one entry for a practitioner. An optional 2nd entry will display if the appointment involves a specific patient. This will be dictated by the appointmentType and if it relates to a generic event or a patient’s appointment.

Click to view child attributes
actor
json

Reference to person involved in appointment.

Click to view child attributes
reference
string

The reference string of the practitioner or patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

Value Options Supported:
  • Practitioner/id
  • Patient/id
type
string

Type the reference refers to (e.g. “Patient”, “Practitioner”).

Value Options Supported:
  • Practitioner
  • Patient
status
enum [ accepted ]

Responses

200 OK
Request was successful.

Errors

400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  • curl --request GET \
         --url 'https://fumage-example.canvasmedical.com/Appointment/<id>' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json'
    
  • import requests
    
    url = "https://fumage-example.canvasmedical.com/Appointment/<id>"
    
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>"
    }
    
    response = requests.get(url, headers=headers)
    
    print(response.text)
    
  • {
        "resourceType": "Appointment",
        "id": "621a66fc-9d5c-4de0-97fb-935d611ac176",
        "contained":
        [
            {
                "resourceType": "Endpoint",
                "id": "appointment-meeting-endpoint-0",
                "status": "active",
                "connectionType":
                {
                    "code": "https"
                },
                "payloadType":
                [
                    {
                        "coding":
                        [
                            {
                                "code": "video-call"
                            }
                        ]
                    }
                ],
                "address": "https://url-for-video-chat.example.com?meeting=abc123"
            }
        ],
        "extension": [
            {
                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5",
            }
        ],
        "identifier": [
            {
                "id": "97b28298-f618-4972-9a6b-d095785587d6",
                "use": "usual",
                "system": "AssigningSystem",
                "value": "test123",
                "period": {
                    "start": "2024-01-01",
                    "end": "2024-12-31"
                }
            }
        ],
        "status": "proposed",
        "appointmentType":
        {
            "coding":
            [
                {
                    "system": "http://snomed.info/sct",
                    "code": "448337001",
                    "display": "Telemedicine"
                }
            ]
        },
        "reasonCode":
        [
            {
                "coding":
                [
                    {
                        "system": "INTERNAL",
                        "code": "INIV",
                        "display": "Initial Visit",
                        "userSelected": false
                    }
                ],
                "text": "Initial 30 Minute Visit"
            }
        ],
        "description": "Initial 30 Minute Visit",
        "supportingInformation":
        [
            {
                "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060",
                "type": "Location"
            },
            {
                "reference": "#appointment-meeting-endpoint-0",
                "type": "Endpoint"
            },
            {
                "reference": "Encounter/23668e1a-e914-4eac-885c-1a2a27244ab7",
                "type": "Encounter"
            }
        ],
        "start": "2023-10-24T13:30:00+00:00",
        "end": "2023-10-24T14:00:00+00:00",
        "participant":
        [
            {
                "actor":
                {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                    "type": "Practitioner"
                },
                "status": "accepted"
            },
            {
                "actor":
                {
                    "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d",
                    "type": "Patient"
                },
                "status": "accepted"
            }
        ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "unknown",
          "details": {
            "text": "Authentication failed"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "forbidden",
          "details": {
            "text": "Authorization failed"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "not-found",
          "details": {
            "text": "Unknown Appointment resource 'a47c7b0ebbb442cdbc4adf259d148ea1'"
          }
        }
      ]
    }
    
  • curl --request GET \
         --url 'https://fumage-example.canvasmedical.com/Appointment?patient=Patient/a031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner/4150cd20de8a470aa570a852859ac87e' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json'
    
  • import requests
    
    url = "https://fumage-example.canvasmedical.com/Appointment?patient=Patient/a031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner/4150cd20de8a470aa570a852859ac87e"
    
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>"
    }
    
    response = requests.get(url, headers=headers)
    
    print(response.text)
    
  • {
        "resourceType": "Bundle",
        "type": "searchset",
        "total": 1,
        "link":
        [
            {
                "relation": "self",
                "url": "/Appointment?patient=Patient%2Fa031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner%2F4150cd20de8a470aa570a852859ac87e&_count=10&_offset=0"
            },
            {
                "relation": "first",
                "url": "/Appointment?patient=Patient%2Fa031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner%2F4150cd20de8a470aa570a852859ac87e&_count=10&_offset=0"
            },
            {
                "relation": "last",
                "url": "/Appointment?patient=Patient%2Fa031d1ba40d74aebb8ed716716da05c2&practitioner=Practitioner%2F4150cd20de8a470aa570a852859ac87e&_count=10&_offset=0"
            }
        ],
        "entry":
        [
            {
                "resource":
                {
                    "resourceType": "Appointment",
                    "id": "f7bb6d7e-1cab-42cd-b3d2-40229e1bede7",
                    "contained":
                    [
                        {
                            "resourceType": "Endpoint",
                            "id": "appointment-meeting-endpoint-0",
                            "status": "active",
                            "connectionType":
                            {
                                "code": "https"
                            },
                            "payloadType":
                            [
                                {
                                    "coding":
                                    [
                                        {
                                            "code": "video-call"
                                        }
                                    ]
                                }
                            ],
                            "address": "https://url-for-video-chat.example.com?meeting=abc123"
                        }
                    ],
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                            "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5",
                        }
                    ],
                    "identifier": [
                      {
                          "id": "97b28298-f618-4972-9a6b-d095785587d6",
                          "use": "usual",
                          "system": "AssigningSystem",
                          "value": "test123",
                          "period": {
                              "start": "2024-01-01",
                              "end": "2024-12-31"
                          }
                      }
                    ],
                    "status": "proposed",
                    "appointmentType":
                    {
                        "coding":
                        [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "448337001",
                                "display": "Telemedicine"
                            }
                        ]
                    },
                    "reasonCode":
                    [
                        {
                            "coding":
                            [
                                {
                                    "system": "INTERNAL",
                                    "code": "INIV",
                                    "display": "Initial Visit",
                                    "userSelected": false
                                }
                            ],
                            "text": "Initial 30 Minute Visit"
                        }
                    ],
                    "description": "Initial 30 Minute Visit",
                    "supportingInformation":
                    [
                        {
                            "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060",
                            "type": "Location"
                        },
                        {
                            "reference": "#appointment-meeting-endpoint-0",
                            "type": "Endpoint"
                        },
                        {
                            "reference": "Encounter/797ccaae-2939-4e8a-9d91-5e9574a11a4e",
                            "type": "Encounter"
                        }
                    ],
                    "start": "2023-10-24T13:30:00+00:00",
                    "end": "2023-10-24T14:00:00+00:00",
                    "participant":
                    [
                        {
                            "actor":
                            {
                                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                "type": "Practitioner"
                            },
                            "status": "accepted"
                        },
                        {
                            "actor":
                            {
                                "reference": "Patient/a031d1ba40d74aebb8ed716716da05c2",
                                "type": "Patient"
                            },
                            "status": "accepted"
                        }
                    ]
                }
            }
        ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "invalid",
          "details": {
            "text": "Bad request"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "unknown",
          "details": {
            "text": "Authentication failed"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "forbidden",
          "details": {
            "text": "Authorization failed"
          }
        }
      ]
    }
    
  • curl --request POST \
         --url 'https://fumage-example.canvasmedical.com/Appointment' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
        "resourceType": "Appointment",
        "contained":
        [
            {
                "resourceType": "Endpoint",
                "id": "appointment-meeting-endpoint",
                "status": "active",
                "connectionType":
                {
                    "code": "https"
                },
                "payloadType":
                [
                    {
                        "coding":
                        [
                            {
                                "code": "video-call"
                            }
                        ]
                    }
                ],
                "address": "https://url-for-video-chat.example.com?meeting=abc123"
            }
        ],
        "identifier": [
            {
                "use": "usual",
                "system": "AssigningSystem",
                "value": "test123",
                "period": {
                    "start": "2024-01-01",
                    "end": "2024-12-31"
                }
            }
        ],
        "status": "proposed",
        "appointmentType":
        {
            "coding":
            [
                {
                    "system": "http://snomed.info/sct",
                    "code": "448337001",
                    "display": "Telemedicine consultation with patient (procedure)"
                }
            ]
        },
        "reasonCode":
        [
            {
                "coding":
                [
                    {
                        "system": "INTERNAL",
                        "code": "INIV",
                        "display": "Initial Visit",
                        "userSelected": false
                    }
                ],
                "text": "Initial 30 Minute Visit"
            }
        ],
        "supportingInformation":
        [
            {
                "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060"
            },
            {
                "reference": "#appointment-meeting-endpoint",
                "type": "Endpoint"
            }
        ],
        "start": "2023-10-24T13:30:00.000Z",
        "end": "2023-10-24T14:00:00.000Z",
        "participant":
        [
            {
                "actor":
                {
                    "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d"
                },
                "status": "accepted"
            },
            {
                "actor":
                {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e"
                },
                "status": "accepted"
            }
        ]
    }
    '
    
  • import requests
    
    url = "https://fumage-example.canvasmedical.com/Appointment"
    
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>",
        "content-type": "application/json"
    }
    
    payload = {
        "resourceType": "Appointment",
        "contained":
        [
            {
                "resourceType": "Endpoint",
                "id": "appointment-meeting-endpoint",
                "status": "active",
                "connectionType":
                {
                    "code": "https"
                },
                "payloadType":
                [
                    {
                        "coding":
                        [
                            {
                                "code": "video-call"
                            }
                        ]
                    }
                ],
                "address": "https://url-for-video-chat.example.com?meeting=abc123"
            }
        ],
        "identifier": [
          {
              "use": "usual",
              "system": "AssigningSystem",
              "value": "test123",
              "period": {
                  "start": "2024-01-01",
                  "end": "2024-12-31"
              }
          }
        ],
        "status": "proposed",
        "appointmentType":
        {
            "coding":
            [
                {
                    "system": "http://snomed.info/sct",
                    "code": "448337001",
                    "display": "Telemedicine consultation with patient (procedure)"
                }
            ]
        },
        "reasonCode":
        [
            {
                "coding":
                [
                    {
                        "system": "INTERNAL",
                        "code": "INIV",
                        "display": "Initial Visit",
                        "userSelected": False
                    }
                ],
                "text": "Initial 30 Minute Visit"
            }
        ],
        "supportingInformation":
        [
            {
                "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060"
            },
            {
                "reference": "#appointment-meeting-endpoint",
                "type": "Endpoint"
            }
        ],
        "start": "2023-10-24T13:30:00.000Z",
        "end": "2023-10-24T14:00:00.000Z",
        "participant":
        [
            {
                "actor":
                {
                    "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d"
                },
                "status": "accepted"
            },
            {
                "actor":
                {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e"
                },
                "status": "accepted"
            }
        ]
    }
    
    response = requests.post(url, json=payload, headers=headers)
    
    print(response.text)
    
  • null
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "invalid",
          "details": {
            "text": "Bad request"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "unknown",
          "details": {
            "text": "Authentication failed"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "forbidden",
          "details": {
            "text": "Authorization failed"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "not-supported",
          "details": {
            "text": "Operation is not supported"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "business-rule",
          "details": {
            "text": "Unprocessable entity"
          }
        }
      ]
    }
    
  • curl --request PUT \
         --url 'https://fumage-example.canvasmedical.com/Appointment/<id>' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
        "resourceType": "Appointment",
        "contained":
        [
            {
                "resourceType": "Endpoint",
                "id": "appointment-meeting-endpoint",
                "status": "active",
                "connectionType":
                {
                    "code": "https"
                },
                "payloadType":
                [
                    {
                        "coding":
                        [
                            {
                                "code": "video-call"
                            }
                        ]
                    }
                ],
                "address": "https://url-for-video-chat.example.com?meeting=abc123"
            }
        ],
        "identifier": [
          {
              "id": "97b28298-f618-4972-9a6b-d095785587d6",
              "use": "usual",
              "system": "AssigningSystem",
              "value": "test123",
              "period": {
                  "start": "2024-01-01",
                  "end": "2024-12-31"
              }
          }
        ],
        "status": "cancelled",
        "appointmentType":
        {
            "coding":
            [
                {
                    "system": "http://snomed.info/sct",
                    "code": "448337001",
                    "display": "Telemedicine consultation with patient (procedure)"
                }
            ]
        },
        "reasonCode":
        [
            {
                "coding":
                [
                    {
                        "system": "INTERNAL",
                        "code": "INIV",
                        "display": "Initial Visit",
                        "userSelected": false
                    }
                ],
                "text": "Initial 30 Minute Visit"
            }
        ],
        "supportingInformation":
        [
            {
                "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060"
            },
            {
                "reference": "#appointment-meeting-endpoint",
                "type": "Endpoint"
            }
        ],
        "start": "2023-10-24T13:30:00.000Z",
        "end": "2023-10-24T14:00:00.000Z",
        "participant":
        [
            {
                "actor":
                {
                    "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d"
                },
                "status": "accepted"
            },
            {
                "actor":
                {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e"
                },
                "status": "accepted"
            }
        ]
    }
    '
    
  • import requests
    
    url = "https://fumage-example.canvasmedical.com/Appointment/<id>"
    
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>",
        "content-type": "application/json"
    }
    
    payload = {
        "resourceType": "Appointment",
        "contained":
        [
            {
                "resourceType": "Endpoint",
                "id": "appointment-meeting-endpoint",
                "status": "active",
                "connectionType":
                {
                    "code": "https"
                },
                "payloadType":
                [
                    {
                        "coding":
                        [
                            {
                                "code": "video-call"
                            }
                        ]
                    }
                ],
                "address": "https://url-for-video-chat.example.com?meeting=abc123"
            }
        ],
        "identifier": [
          {
              "id": "97b28298-f618-4972-9a6b-d095785587d6",
              "use": "usual",
              "system": "AssigningSystem",
              "value": "test123",
              "period": {
                  "start": "2024-01-01",
                  "end": "2024-12-31"
              }
          }
        ],
        "status": "cancelled",
        "appointmentType":
        {
            "coding":
            [
                {
                    "system": "http://snomed.info/sct",
                    "code": "448337001",
                    "display": "Telemedicine consultation with patient (procedure)"
                }
            ]
        },
        "reasonCode":
        [
            {
                "coding":
                [
                    {
                        "system": "INTERNAL",
                        "code": "INIV",
                        "display": "Initial Visit",
                        "userSelected": False
                    }
                ],
                "text": "Initial 30 Minute Visit"
            }
        ],
        "supportingInformation":
        [
            {
                "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060"
            },
            {
                "reference": "#appointment-meeting-endpoint",
                "type": "Endpoint"
            }
        ],
        "start": "2023-10-24T13:30:00.000Z",
        "end": "2023-10-24T14:00:00.000Z",
        "participant":
        [
            {
                "actor":
                {
                    "reference": "Patient/ee1c7803325b47b492008f3e7c9d7a3d"
                },
                "status": "accepted"
            },
            {
                "actor":
                {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e"
                },
                "status": "accepted"
            }
        ]
    }
    
    response = requests.put(url, json=payload, headers=headers)
    
    print(response.text)
    
  • null
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "invalid",
          "details": {
            "text": "Bad request"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "unknown",
          "details": {
            "text": "Authentication failed"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "forbidden",
          "details": {
            "text": "Authorization failed"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "not-found",
          "details": {
            "text": "Unknown Appointment resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "not-supported",
          "details": {
            "text": "Operation is not supported"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "conflict",
          "details": {
            "text": "Resource updated since If-Unmodified-Since date"
          }
        }
      ]
    }
    
  • {
      "resourceType": "OperationOutcome",
      "issue": [
        {
          "severity": "error",
          "code": "business-rule",
          "details": {
            "text": "Unprocessable entity"
          }
        }
      ]
    }