Appointment
Overview
The Appointment resource provides information about scheduled appointments such as a Procedure (mammogram) or office visit for a Patient, Practitioner, or Location.
When integrating your application with a client’s environments you will work with the client to determine the Practitioner and Location IDs (Millennium personnel and location codes, respectively), which they want to make available to third-party applications for enabling scheduling functionality.
The following fields are returned if valued:
- Appointment ID
- Status
- Type
- Participant
- Reason
- Description
- Start Date/Time
- End Date/Time
- Duration in minutes
- Comment
- Details of participants involved in the appointment:
Note: The examples provided here are non-normative and replaying them in the public sandbox is not guaranteed to yield the results shown on the site.
The common errors and OperationOutcomes may be returned.
Terminology Bindings
Appointment.type |
|
Search
Search for Appointments that meet supplied query parameters:
GET /Appointment?:parameters
Implementation Notes
- Valid IDs for the
practitioner
andlocation
search parameters will be determined by the client and provided when integrating your application with the client’s environments. See overview for details.
Authorization Types
Parameters
Name | Required? | Type | Description |
---|---|---|---|
_id |
Yes, or patient or practitioner or location . |
token |
The logical resource id associated with the Appointment. Example: _id=3005759
|
patient |
Yes, or _id or practitioner or location . |
reference |
A single or comma separated list of Patient references. Example: patient=4704007
|
practitioner |
Yes, or _id or patient or location . |
reference |
A single or comma separated list of Practitioner references. Example: practitioner=2578010
|
location |
Yes, or _id or patient or practitioner . |
reference |
A single or comma separated list of Location references. Example: location=633867
|
date |
Yes when using patient , practitioner , or location . |
date |
The Appointment date/time. Example: date=2020-01
|
status |
No | token |
A single or comma separated list of appointment statuses. Example: status=arrived
|
_count |
No | number |
The maximum number of results to return. |
Notes:
-
The
patient
,practitioner
, andlocation
parameters may be included only once and may not be used in combination. For example,patient=1234,5678
is supported butpatient=1234&patient=5678
andpatient=1234&location=5678
are not. - The
date
parameter may be provided:- once without a prefix or time component to imply a date range. (e.g.
&date=2016
,&date=2016-07
,&date=2016-07-04
) - once without a prefix and with a time component to indicate a specific date/time. (e.g
&date=2016-07-04T13:00:00.000-05:00
) - twice with the prefixes
ge
orgt
andle
orlt
to indicate a specific range. The date and prefix pairs must define an upper and lower bound. (e.g.&date=ge2014&date=lt2016
,&date=ge2014-03-15&date=le2017
)
- once without a prefix or time component to imply a date range. (e.g.
- The retrieved appointments are sorted by
start
date, ascending (earliest first).
Headers
Accept: application/json+fhir
Authorization: <OAuth2 Bearer Token>
Example
Request
GET https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Appointment?patient=12724066&date=2020-02
Response
Status: 200 OK
{
"resourceType": "Bundle",
"id": "c1502c8d-2f96-4d7e-996c-5b39f96046c8",
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Appointment?date=2020&patient=12724066&_count=50"
}
],
"entry": [
{
"fullUrl": "https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Appointment/4817508",
"resource": {
"resourceType": "Appointment",
"id": "4817508",
"meta": {
"versionId": "1",
"lastUpdated": "2020-07-06T16:41:32.000Z"
},
"text": {
"status": "generated",
"div": "<div><p><b>Appointment</b></p><p><b>Description</b>: PT Eval</p><p><b>Type</b>: PT Eval</p><p><b>Start</b>: Oct 6, 2020 2:00 P.M. UTC</p><p><b>End</b>: Oct 6, 2020 3:00 P.M. UTC</p><p><b>Duration</b>: 60 Minutes</p><p><b>Status</b>: Booked</p><p><b>Reason</b>: torn ACL</p><p><b>Location</b>: OP Rehab1</p><p><b>Participants</b>:</p><p><b>Patient</b>: SMART, NANCY</p><br /><p><b>Participant</b>: Sisko, Jon PT</p><p><b>Primary</b>: Yes</p></div>"
},
"status": "booked",
"type": {
"coding": [
{
"system": "https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/14249",
"code": "26054577",
"display": "PT Eval",
"userSelected": true
}
],
"text": "PT Eval"
},
"reason": {
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unsupported"
}
]
}
],
"text": "torn ACL"
},
"description": "PT Eval",
"start": "2020-10-06T14:00:00.000Z",
"end": "2020-10-06T15:00:00.000Z",
"minutesDuration": 60,
"participant": [
{
"type": [
{
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
],
"text": "PT Therapists"
},
{
"coding": [
{
"system": "http://hl7.org/fhir/v3/ParticipationType",
"code": "PPRF",
"display": "primary performer",
"userSelected": false
}
]
}
],
"actor": {
"display": "Sisko, Jon PT"
},
"required": "required",
"status": "accepted"
},
{
"type": [
{
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
],
"text": "Patient"
}
],
"actor": {
"reference": "Patient/12724066",
"display": "SMART, NANCY"
},
"required": "required",
"status": "accepted"
},
{
"actor": {
"reference": "Location/21503380",
"display": "OP Rehab1"
},
"required": "required",
"status": "accepted"
}
]
}
}
]
}
Retrieve by ID
List an individual Appointment by its ID:
GET /Appointment/:id
Authorization Types
Headers
Accept: application/json+fhir
Authorization: <OAuth2 Bearer Token>
Example
Request
GET https://fhir-open.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Appointment/4817508
Response
Status: 200 OK
{
"resourceType": "Appointment",
"id": "4817508",
"meta": {
"versionId": "1",
"lastUpdated": "2020-07-06T16:41:32.000Z"
},
"text": {
"status": "generated",
"div": "<div><p><b>Appointment</b></p><p><b>Description</b>: PT Eval</p><p><b>Type</b>: PT Eval</p><p><b>Start</b>: Oct 6, 2020 2:00 P.M. UTC</p><p><b>End</b>: Oct 6, 2020 3:00 P.M. UTC</p><p><b>Duration</b>: 60 Minutes</p><p><b>Status</b>: Booked</p><p><b>Reason</b>: torn ACL</p><p><b>Location</b>: OP Rehab1</p><p><b>Participants</b>:</p><p><b>Patient</b>: SMART, NANCY</p><br /><p><b>Participant</b>: Sisko, Jon PT</p><p><b>Primary</b>: Yes</p></div>"
},
"status": "booked",
"type": {
"coding": [
{
"system": "https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/14249",
"code": "26054577",
"display": "PT Eval",
"userSelected": true
}
],
"text": "PT Eval"
},
"reason": {
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unsupported"
}
]
}
],
"text": "torn ACL"
},
"description": "PT Eval",
"start": "2020-10-06T14:00:00.000Z",
"end": "2020-10-06T15:00:00.000Z",
"minutesDuration": 60,
"participant": [
{
"type": [
{
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
],
"text": "PT Therapists"
},
{
"coding": [
{
"system": "http://hl7.org/fhir/v3/ParticipationType",
"code": "PPRF",
"display": "primary performer",
"userSelected": false
}
]
}
],
"actor": {
"display": "Sisko, Jon PT"
},
"required": "required",
"status": "accepted"
},
{
"type": [
{
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
],
"text": "Patient"
}
],
"actor": {
"reference": "Patient/12724066",
"display": "SMART, NANCY"
},
"required": "required",
"status": "accepted"
},
{
"actor": {
"reference": "Location/21503380",
"display": "OP Rehab1"
},
"required": "required",
"status": "accepted"
}
]
}
Create
Create a new Appointment.
POST /Appointment
Implementation Notes
- The modifier elements implicitRules and modifierExtension are not supported and will be rejected if present.
-
Appointment.status
must be set toproposed
. -
Appointment.slot
must be a list containing a single reference to the Slot in which this appointment is being booked.-
Appointment.slot[0].reference
specifies an availability in the Scheduling system.
-
-
Appointment.participant
must have exactly one participant.-
Appointment.participant.status
must be set toneeds-action
. -
Appointment.participant.type
must not be set.
-
Scheduling examples are time sensitive. Recreating the below example will require a Slot with a status of free
.
Authorization Types
Headers
Authorization: <OAuth2 Bearer Token>
Accept: application/json+fhir
Content-Type: application/json+fhir
Body Fields
Name | Required | Type | |
---|---|---|---|
resourceType
|
Yes |
string |
|
|
|||
slot
|
Yes |
List of Reference (Slot ) |
|
|
|||
status
|
Yes |
code |
|
|
|||
participant
|
Yes |
List of BackboneElement |
|
|
|||
participant.actor
|
Yes |
Reference (Patient ) |
|
|
|||
participant.status
|
Yes |
code |
|
|
|||
comment
|
No |
string |
|
|
Example
Request
POST https://fhir-ehr-code.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Appointment/
Body
{
"resourceType": "Appointment",
"slot": [
{
"reference": "Slot/24477854-21304876-62852027-0"
}
],
"participant": [
{
"actor": {
"reference": "Patient/12724066"
},
"status": "needs-action"
}
],
"status": "proposed"
}
Response
Status: 201 Created
Connection: Keep-Alive Content-Encoding: gzip Content-Length: 20 Content-Type: text/html; charset=UTF-8 Date: Wed, 13 Jan 2016 21:45:47 GMT Keep-Alive: timeout=15, max=100 Last-Modified: Tue, 15 Dec 2015 19:13:20 GMT access-control-allow-methods: DELETE, GET, POST, PUT, OPTIONS, HEAD access-control-allow-origin: * access-control-expose-headers: ETag, Content-Location, Location, X-Request-Id, WWW-Authenticate, Date access-control-max-age: 0 cache-control: no-cache etag: W/"0" location: https://fhir-ehr-code.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Appointment/20465903 opc-request-id: /A6715F018F26C503BBE42F2625DF3DF0/6CEB8EC1BDBB5BC448FE51BCA94E7149 strict-transport-security: max-age=631152000 vary: Origin,User-Agent,Accept-Encoding x-content-type-options: nosniff x-frame-options: SAMEORIGIN x-request-id: 682c633c-b20f-4f6f-8fae-c58b3aeffe04 x-xss-protection: 1; mode=block
The ETag
response header indicates the current If-Match
version to use on subsequent updates.
Update
Update an Appointment.
PUT /Appointment/:id
Implementation Notes
- The only supported change is to update the Appointment.status to either
arrived
orcancelled
.
The common errors and OperationOutcomes may be returned.
Note: The examples provided here are non-normative and replaying them in the public sandbox is not guaranteed to yield the results shown on the site.
Authorization Types
Headers
Authorization: <OAuth2 Bearer Token>
Accept: application/json+fhir
Content-Type: application/json+fhir
If-Match: W/"<Current version of the Appointment resource>"
Body fields
Name | Required | Type | |
---|---|---|---|
resourceType
|
Yes |
string |
|
|
|||
status
|
Yes |
code |
|
|
|||
participant
|
Yes |
List of BackboneElement |
|
|
|||
participant.actor
|
Yes |
Reference |
|
|
|||
participant.status
|
Yes |
code |
|
|
Example
Request
PUT https://fhir-ehr-code.cerner.com/dstu2/ec2458f2-1e24-41c8-b71b-0e701af7583d/Appointment/4817508
Body
{
"resourceType": "Appointment",
"id": "4817508",
"meta": {
"versionId": "1",
"lastUpdated": "2020-07-06T16:41:32.000Z"
},
"text": {
"status": "generated",
"div": "<div><p><b>Appointment</b></p><p><b>Description</b>: PT Eval</p><p><b>Type</b>: PT Eval</p><p><b>Start</b>: Oct 6, 2020 2:00 P.M. UTC</p><p><b>End</b>: Oct 6, 2020 3:00 P.M. UTC</p><p><b>Duration</b>: 60 Minutes</p><p><b>Status</b>: Booked</p><p><b>Reason</b>: torn ACL</p><p><b>Location</b>: OP Rehab1</p><p><b>Participants</b>:</p><p><b>Patient</b>: SMART, NANCY</p><br /><p><b>Participant</b>: Sisko, Jon PT</p><p><b>Primary</b>: Yes</p></div>"
},
"status": "accepted",
"type": {
"coding": [
{
"system": "https://fhir.cerner.com/ec2458f2-1e24-41c8-b71b-0e701af7583d/codeSet/14249",
"code": "26054577",
"display": "PT Eval",
"userSelected": true
}
],
"text": "PT Eval"
},
"reason": {
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unsupported"
}
]
}
],
"text": "torn ACL"
},
"description": "PT Eval",
"start": "2020-10-06T14:00:00.000Z",
"end": "2020-10-06T15:00:00.000Z",
"minutesDuration": 60,
"participant": [
{
"type": [
{
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
],
"text": "PT Therapists"
},
{
"coding": [
{
"system": "http://hl7.org/fhir/v3/ParticipationType",
"code": "PPRF",
"display": "primary performer",
"userSelected": false
}
]
}
],
"actor": {
"display": "Sisko, Jon PT"
},
"required": "required",
"status": "accepted"
},
{
"type": [
{
"coding": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode": "unknown"
}
]
}
],
"text": "Patient"
}
],
"actor": {
"reference": "Patient/12724066",
"display": "SMART, NANCY"
},
"required": "required",
"status": "accepted"
},
{
"actor": {
"reference": "Location/21503380",
"display": "OP Rehab1"
},
"required": "required",
"status": "accepted"
}
]
}
In this example, only the Appointment.status
field was updated.
Response
Status: 200 OK
Connection: Keep-Alive Content-Encoding: gzip Content-Length: 20 Content-Type: text/html; charset=UTF-8 Date: Wed, 13 Jan 2016 21:50:53 GMT Keep-Alive: timeout=15, max=100 Last-Modified: Tue, 15 Dec 2015 19:13:20 GMT access-control-allow-methods: DELETE, GET, POST, PUT, OPTIONS, HEAD access-control-allow-origin: * access-control-expose-headers: ETag, Content-Location, Location, X-Request-Id, WWW-Authenticate, Date access-control-max-age: 0 cache-control: no-cache etag: W/"1" strict-transport-security: max-age=631152000 vary: Origin,User-Agent,Accept-Encoding x-content-type-options: nosniff x-frame-options: SAMEORIGIN x-request-id: 9dba8326-899a-406f-a125-3fc3d6605dad x-xss-protection: 1; mode=block
The ETag
response header indicates the current If-Match
version to use on subsequent updates.
Errors
The following errors may be returned:
-
412 Precondition Failed
- TheIf-Match
header was not provided. -
422 Unprocessable Entity
- The resource is in a status that cannot be changed. -
422 Unprocessable Entity
- Thestatus
provided is not supported. See notes above. -
422 Unprocessable Entity
- The patient URL or the provider URLs are longer than 255 characters. -
423 Locked
- The resource is currently being modified elsewhere. -
424 Failed Dependency
- An external operation is necessary for the update (e.g. encounter association).