Appointment
Overview
The Appointment resource provides information about scheduled appointments such as a procedure (mammogram) or office visit for a patient, practitioner or location. Date is required when searching by patient, practitioner or location.
When integrating your application with a client’s production environment 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.
We understand this is a bit cumbersome, but we are always evaluating community feedback and look to improve the API in the future.
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:
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 production environment. See overview for details.
Authorization Types
Parameters
Name | Required? | Type | Description |
---|---|---|---|
_id |
Yes, or one of patient , practitioner , or location . |
token |
The logical resource id associated with the Appointment. Example: 3005759
|
date |
Yes when using patient , practitioner , or location . |
date |
The Appointment date/time. Example: 2016
|
patient |
Yes, or _id
|
reference |
A single or comma separated list of Patient references. Example: 4704007
|
practitioner |
Yes, or _id
|
reference |
A single or comma separated list of Practitioner references. Example: 2578010
|
location |
Yes, or _id
|
reference |
A single or comma separated list of Location references. Example: 633867
|
status |
No | token |
A single or comma separated list of appointment statuses. Example: 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 with the others. 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
,gt
,le
, 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 first by
start
date ascending (earliest first), followed by the provided search parameter (patient
,practitioner
orlocation
) andstart
time 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?date=2020&patient=12724066
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"
}
]
}
}
]
}
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.
Errors
The common errors and OperationOutcomes may be returned.
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"
}
]
}
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.
Errors
The common errors and OperationOutcomes may be returned.
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, which indicates details such as practitioner, location, and time.
-
-
Appointment.participant
must have exactly one participant.-
Appointment.participant.status
must be set toneeds-action
. -
Appointment.participant.type
must not be set.
-
-
Appointment.comment
must be a string.
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 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.
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.
Scheduling examples are time-sensitive and could already be booked when attempted. Recreating this example will require an available Slot reference, populated from the Slot Resource.
Update
Update an Appointment.
PUT /Appointment/:id
Implementation Notes
- The only supported change is to update the Appointment.status to either
arrived
orcancelled
. -
Appointment.participant
must have at least one participant. -
Appointment.participant.status
must beaccepted
for each participant.
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.
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.
Scheduling examples are time-sensitive and could already be booked when attempted. Recreating this example will require a new appointment for an available slot, then updating its status.
Errors
The common errors and OperationOutcomes may be returned.
In addition, the following errors may be returned:
- If either the patient URL or the provider URLs are longer than 255 characters, it will return a
422 Unprocessable Entity
response. - Updating an Appointment resource without sending the
If-Match
header will result in a412 Precondition Failed
response. - Updating an Appointment resource which is currently being modified will result in a
423 Locked
response. - If the Appointment resource could not be updated because of an operation that is necessary for the update (eg. encounter association),
424 Failed Dependency
response will be returned.