Encounter

An interaction between a patient and healthcare provider(s) for the purpose of providing healthcare service(s) or assessing the health status of a patient.

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

Encounter creation in Canvas

An encounter is associated with some of our notes in Canvas. For our default base notes, an encounter will be created with these note types:

- Lab visit
- Phone visit
- Telehealth visit
- Office visit
- Home Visit
- In-patient Visit

With our Configurable Note Types Feature all custom note types will be associated with an encounter by default.

http://hl7.org/fhir/us/core/STU3.1.1/StructureDefinition-us-core-encounter.html

get
/Encounter/{id}

Encounter read

Read an Encounter resource

Path Parameters

id required
string
The unique identifier for the Encounter

Response Payload Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the encounter.

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]

Identifier(s) by which this encounter is known.

Click to view child attributes
id
string

The identifier of the encounter.

system
string

The namespace for the identifier value.

Value Options Supported:
  • http://canvasmedical.com
value
string

The value that is unique.

status
enum [ planned | cancelled | finished | in-progress ]

The status of the encounter.

- A planned encounter is an Appointment note that has not been check-in.
- A cancelled encounter is either 1) an Appointment that was cancelled or no-showed or 2) a Note that was deleted from the patient’s chart.
- A finished encounter is a Note that has been locked at least once. Notes that are in an unlocked/ammended state, will have a finished status; however, they will not have a period.end datetime.
- An in-progress encounter is a note that has not yet been locked.

class
json

Classification of patient encounter.

Click to view child attributes
system
string

Identity of the terminology system.

Value Options Supported:
  • https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html
code
string

Symbol in syntax defined by the system.

display
string

Representation defined by the system.

type
array[json]

Specific type of encounter.

In Canvas this will represent the Note Type the encounter is associated with. If the Note is in a planned status, the coding will correspond to Canvas’ appointment note type until the note is checked-in and converted to the scheduled note type.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

code
string

The code.

display
string

The display name of the coding.

subject
json

The patient or group present at the encounter.

Click to view child attributes
reference
string

The reference string of the subject in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

type
string

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

participant
array[json]

List of participants involved in the encounter.

Click to view child attributes
type
array[json]

Role of participant in encounter.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

Value Options Supported:
  • http://terminology.hl7.org/CodeSystem/v3-ParticipationType
code
string

The code.

Value Options Supported:
  • PART
display
string

The display name of the coding.

Value Options Supported:
  • Participant
period
json

Period of time during the encounter that the participant participated

Click to view child attributes
start
datetime

Starting time with inclusive boundary.

end
datetime

End time with inclusive boundary, if not ongoing.

individual
json

Persons involved in the encounter other than the patient.

Click to view child attributes
reference
string

The reference string of the participant in the format of "Practitioner/4150cd20de8a470aa570a852859ac87e".

type
string

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

display
string

Text alternative for the resource (e.g Credendialed name of the Practitioner).

appointment
array[json]

The appointment that scheduled this encounter if applicable. If an appointment was rescheduled at any point within the Canvas UI, there may be multiple appointments in this array.

Click to view child attributes
reference
string

The reference string of the appointment in the format of "Appointment/79f99d7d-2e55-41ec-8e39-01bd9408aacf".

type
string

Type the reference refers to (e.g. “Appointment”).

period
json

The start and end time of the encounter.

Appointment notes in Canvas will not have a period until the note is checked-in.

Encounter notes will not have period.end datetime until the note is locked/signed.

Notes that are in an unlocked/ammended state, will not have a period.end datetime until relocked/signed.

Click to view child attributes
start
datetime

Starting time with inclusive boundary.

end
datetime

End time with inclusive boundary, if not ongoing.

reasonCode
array[json]

Coded reason the encounter takes place.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

Value Options Supported:
  • http://snomed.info/sct
code
string

The code.

Value Options Supported:
  • 308335008
display
string

The display name of the coding.

Value Options Supported:
  • Patient encounter procedure (procedure)
reasonReference
array[json]

Reason the encounter takes place (reference).

In Canvas this represents any encounters that were diagnosed, assessed, or indicated during the encounter.

Click to view child attributes
reference
string

The reference string of the condition in the format of "Condition/e8921649-ec92-46b5-b663-8a4097c10513".

type
string

Type the reference refers to (e.g. “Condition”).

hospitalization
json

Details about the admission to a healthcare service.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

Value Options Supported:
  • http://terminology.hl7.org/CodeSystem/discharge-disposition
code
string

The code.

Value Options Supported:
  • oth
display
string

The display name of the coding.

Value Options Supported:
  • Other
location
array[json]

List of locations where the patient has been during the encounter.

Click to view child attributes
location
json

Location the encounter takes place.

Click to view child attributes
reference
string

The reference string of the location in the format of "Location/3c01c6ea-b7dc-4109-9d1c-1cf4ba7c211e".

type
string

Type the reference refers to (e.g. “Location”).

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.

Query Parameters

_id
string

A Canvas-issued unique identifier for a specific encounter.

appointment
string

The appointment that scheduled this encounter in the format Appointment/6e5234c4-2dd0-495d-98cf-ad04add1316e.

date
string

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

patient
string

The patient or group present at the encounter in the format Patient/a39cafb9d1b445be95a2e2548e12a787.

subject
string

Encounter subject in the format Patient/a39cafb9d1b445be95a2e2548e12a787.

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 encounter.

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]

Identifier(s) by which this encounter is known.

Click to view child attributes
id
string

The identifier of the encounter.

system
string

The namespace for the identifier value.

Value Options Supported:
  • http://canvasmedical.com
value
string

The value that is unique.

status
enum [ planned | cancelled | finished | in-progress ]

The status of the encounter.

- A planned encounter is an Appointment note that has not been check-in.
- A cancelled encounter is either 1) an Appointment that was cancelled or no-showed or 2) a Note that was deleted from the patient’s chart.
- A finished encounter is a Note that has been locked at least once. Notes that are in an unlocked/ammended state, will have a finished status; however, they will not have a period.end datetime.
- An in-progress encounter is a note that has not yet been locked.

class
json

Classification of patient encounter.

Click to view child attributes
system
string

Identity of the terminology system.

Value Options Supported:
  • https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html
code
string

Symbol in syntax defined by the system.

display
string

Representation defined by the system.

type
array[json]

Specific type of encounter.

In Canvas this will represent the Note Type the encounter is associated with. If the Note is in a planned status, the coding will correspond to Canvas’ appointment note type until the note is checked-in and converted to the scheduled note type.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

code
string

The code.

display
string

The display name of the coding.

subject
json

The patient or group present at the encounter.

Click to view child attributes
reference
string

The reference string of the subject in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

type
string

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

participant
array[json]

List of participants involved in the encounter.

Click to view child attributes
type
array[json]

Role of participant in encounter.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

Value Options Supported:
  • http://terminology.hl7.org/CodeSystem/v3-ParticipationType
code
string

The code.

Value Options Supported:
  • PART
display
string

The display name of the coding.

Value Options Supported:
  • Participant
period
json

Period of time during the encounter that the participant participated

Click to view child attributes
start
datetime

Starting time with inclusive boundary.

end
datetime

End time with inclusive boundary, if not ongoing.

individual
json

Persons involved in the encounter other than the patient.

Click to view child attributes
reference
string

The reference string of the participant in the format of "Practitioner/4150cd20de8a470aa570a852859ac87e".

type
string

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

display
string

Text alternative for the resource (e.g Credendialed name of the Practitioner).

appointment
array[json]

The appointment that scheduled this encounter if applicable. If an appointment was rescheduled at any point within the Canvas UI, there may be multiple appointments in this array.

Click to view child attributes
reference
string

The reference string of the appointment in the format of "Appointment/79f99d7d-2e55-41ec-8e39-01bd9408aacf".

type
string

Type the reference refers to (e.g. “Appointment”).

period
json

The start and end time of the encounter.

Appointment notes in Canvas will not have a period until the note is checked-in.

Encounter notes will not have period.end datetime until the note is locked/signed.

Notes that are in an unlocked/ammended state, will not have a period.end datetime until relocked/signed.

Click to view child attributes
start
datetime

Starting time with inclusive boundary.

end
datetime

End time with inclusive boundary, if not ongoing.

reasonCode
array[json]

Coded reason the encounter takes place.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

Value Options Supported:
  • http://snomed.info/sct
code
string

The code.

Value Options Supported:
  • 308335008
display
string

The display name of the coding.

Value Options Supported:
  • Patient encounter procedure (procedure)
reasonReference
array[json]

Reason the encounter takes place (reference).

In Canvas this represents any encounters that were diagnosed, assessed, or indicated during the encounter.

Click to view child attributes
reference
string

The reference string of the condition in the format of "Condition/e8921649-ec92-46b5-b663-8a4097c10513".

type
string

Type the reference refers to (e.g. “Condition”).

hospitalization
json

Details about the admission to a healthcare service.

Click to view child attributes
coding
array[json]

Code defined by a terminology system.

Click to view child attributes
system
string

The system url of the coding.

Value Options Supported:
  • http://terminology.hl7.org/CodeSystem/discharge-disposition
code
string

The code.

Value Options Supported:
  • oth
display
string

The display name of the coding.

Value Options Supported:
  • Other
location
array[json]

List of locations where the patient has been during the encounter.

Click to view child attributes
location
json

Location the encounter takes place.

Click to view child attributes
reference
string

The reference string of the location in the format of "Location/3c01c6ea-b7dc-4109-9d1c-1cf4ba7c211e".

type
string

Type the reference refers to (e.g. “Location”).

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/Encounter/<id>' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json'
    
  • import requests
    
    url = "https://fumage-example.canvasmedical.com/Encounter/<id>"
    
    headers = {
        "accept": "application/json",
        "Authorization": "Bearer <token>"
    }
    
    response = requests.get(url, headers=headers)
    
    print(response.text)
    
  • {
        "resourceType": "Encounter",
        "id": "7720a218-c0bd-4cee-82a2-729bd9c101f3",
        "extension": [
            {
                "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5",
            }
        ],
        "identifier": [
            {
                "id": "7720a218-c0bd-4cee-82a2-729bd9c101f3",
                "system": "http://canvasmedical.com",
                "value": "7720a218-c0bd-4cee-82a2-729bd9c101f3"
            }
        ],
        "status": "in-progress",
        "class": {
            "system": "https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html"
        },
        "type": [
            {
                "coding": [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "308335008",
                        "display": "Office Visit"
                    }
                ]
            }
        ],
        "subject": {
            "reference": "Patient/a1197fa9e65b4a5195af15e0234f61c2",
            "type": "Patient"
        },
        "participant": [
            {
                "type": [
                    {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                                "code": "PART",
                                "display": "Participation"
                            }
                        ]
                    }
                ],
                "period": {
                    "start": "2022-04-04T05:26:34.711718+00:00"
                },
                "individual": {
                    "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                    "type": "Practitioner",
                    "display": "Canvas Support MD"
                }
            }
        ],
        "period": {
            "start": "2022-04-04T05:26:34.711718+00:00"
        },
        "reasonCode": [
            {
                "coding": [
                    {
                        "system": "http://snomed.info/sct",
                        "code": "308335008",
                        "display": "Patient encounter procedure (procedure)"
                    }
                ]
            }
        ],
        "reasonReference": [
            {
                "reference": "Condition/b06982fa-9bcb-4695-a2f4-09cfdb21f03d",
                "type": "Condition"
            },
            {
                "reference": "Condition/e3df5e12-8ea4-46f8-922e-89a229945ef4",
                "type": "Condition"
            },
            {
                "reference": "Condition/266eae2b-4983-42b7-94ca-1397f80a7968",
                "type": "Condition"
            }
        ],
        "hospitalization": {
            "dischargeDisposition": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/discharge-disposition",
                        "code": "oth",
                        "display": "Other"
                    }
                ]
            }
        },
        "location": [
            {
                "location": {
                    "reference": "Location/50ea08f9-f4a5-4315-90e3-10d38922daa8",
                    "type": "Location"
                }
            }
        ]
    }
    
  • {
      "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 Encounter resource '7d1ce256fcd7408193b0459650937a07'"
                }
            }
        ]
    }
    
  • curl --request GET \
         --url 'https://fumage-example.canvasmedical.com/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15' \
         --header 'Authorization: Bearer <token>' \
         --header 'accept: application/json'
    
  • import requests
    
    url = "https://fumage-example.canvasmedical.com/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15"
    
    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": "/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15&_count=10&_offset=0"
            },
            {
                "relation": "first",
                "url": "/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15&_count=10&_offset=0"
            },
            {
                "relation": "last",
                "url": "/Encounter?patient=Patient/8f19219e36054ea89c4d98c9b258c2f1&date=ge2023-09-15&_count=10&_offset=0"
            }
        ],
        "entry": [
            {
                "resource": {
                    "resourceType": "Encounter",
                    "id": "06e0ee68-59f8-4899-b906-1298a36870ab",
                    "extension": [
                        {
                            "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                            "valueId": "2a8154d8-9420-4ab5-97f8-c2dae5a10af5",
                        }
                    ],
                    "identifier": [
                        {
                            "id": "06e0ee68-59f8-4899-b906-1298a36870ab",
                            "system": "http://canvasmedical.com",
                            "value": "06e0ee68-59f8-4899-b906-1298a36870ab"
                        }
                    ],
                    "status": "finished",
                    "class": {
                        "system": "https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html"
                    },
                    "type": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "308335008",
                                    "display": "Office Visit"
                                }
                            ]
                        }
                    ],
                    "subject": {
                        "reference": "Patient/8f19219e36054ea89c4d98c9b258c2f1",
                        "type": "Patient"
                    },
                    "participant": [
                        {
                            "type": [
                                {
                                    "coding": [
                                        {
                                            "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                                            "code": "PART",
                                            "display": "Participation"
                                        }
                                    ]
                                }
                            ],
                            "period": {
                                "start": "2023-09-20T18:41:54.885110+00:00",
                                "end": "2023-09-20T18:57:47.490741+00:00"
                            },
                            "individual": {
                                "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                                "type": "Practitioner",
                                "display": "Larry Weed"
                            }
                        }
                    ],
                    "period": {
                        "start": "2023-09-20T18:41:54.885110+00:00",
                        "end": "2023-09-20T18:57:47.490741+00:00"
                    },
                    "reasonCode": [
                        {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "308335008",
                                    "display": "Patient encounter procedure (procedure)"
                                }
                            ]
                        }
                    ],
                    "reasonReference": [
                        {
                            "reference": "Condition/82e02680-c37d-4705-876d-b845d85efc20",
                            "type": "Condition"
                        }
                    ],
                    "hospitalization": {
                        "dischargeDisposition": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/discharge-disposition",
                                    "code": "oth",
                                    "display": "Other"
                                }
                            ]
                        }
                    },
                    "location": [
                        {
                            "location": {
                                "reference": "Location/e332ff73-7fa4-4432-abe9-2adc43b1bb2c",
                                "type": "Location"
                            }
                        }
                    ]
                }
            },
            {
                "resourceType": "Encounter",
                "id": "f7663d7b-13bd-4236-843e-086306aea125",
                "extension": [
                    {
                        "url": "http://schemas.canvasmedical.com/fhir/extensions/note-id",
                        "valueId": "8c83a639-05c0-43e8-a39b-8b99ea75d7d2"
                    }
                ],
                "identifier": [
                    {
                        "id": "f7663d7b-13bd-4236-843e-086306aea125",
                        "system": "http://canvasmedical.com",
                        "value": "f7663d7b-13bd-4236-843e-086306aea125"
                    }
                ],
                "status": "planned",
                "class": {
                    "system": "https://www.hl7.org/fhir/v3/ActEncounterCode/vs.html"
                },
                "type": [
                    {
                        "coding": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "185418009",
                                "display": "Method appointment made"
                            }
                        ]
                    }
                ],
                "subject": {
                    "reference": "Patient/8f19219e36054ea89c4d98c9b258c2f1",
                    "type": "Patient"
                },
                "participant": [
                    {
                        "type": [
                            {
                                "coding": [
                                    {
                                        "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                                        "code": "PART",
                                        "display": "Participation"
                                    }
                                ]
                            }
                        ],
                        "individual": {
                            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
                            "type": "Practitioner",
                            "display": "Canvas Support MD"
                        }
                    }
                ],
                "appointment": [
                    {
                        "reference": "Appointment/65463607-866c-4c6f-812f-bf8616a5f755",
                        "type": "Appointment"
                    },
                    {
                        "reference": "Appointment/6e5234c4-2dd0-495d-98cf-ad04add1316e",
                        "type": "Appointment"
                    }
                ],
                "reasonCode": [
                    {
                        "coding": [
                            {
                                "system": "http://snomed.info/sct",
                                "code": "308335008",
                                "display": "Patient encounter procedure (procedure)"
                            }
                        ]
                    }
                ],
                "hospitalization": {
                    "dischargeDisposition": {
                        "coding": [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/discharge-disposition",
                                "code": "oth",
                                "display": "Other"
                            }
                        ]
                    }
                },
                "location": [
                    {
                        "location": {
                            "reference": "Location/b3476a18-3f63-422d-87e7-b3dc0cd55060",
                            "type": "Location"
                        }
                    }
                ]
            }
        ]
    }
    
  • {
      "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"
          }
        }
      ]
    }