Appointment

• Overview
• Terminology Bindings
• Search
  • Authorization Types
  • Parameters
  • Headers
  • Example
  • Errors
• Retrieve by id
  • Authorization Types
  • Headers
  • Example
  • Errors
• Create
  • Authorization Types
  • Headers
  • Body Fields
  • Example
• Update
  • Authorization Types
  • Headers
  • Body fields
  • Example
  • Errors

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:
  • Type
  • Actor (name)
  • Required (always ‘required’)
  • Status

Terminology Bindings

Appointment.type

Description Additional details about where the content was created (e.g. clinical specialty). Details: Practice Setting Code Value Set System: http://snomed.info/sct Details: Millennium Scheduling Appointment Synonyms or Types System: https://fhir.cerner.com/<EHR source id>/codeSet/14249

Search

Search for Appointments that meet supplied query parameters:

GET /Appointment?:parameters

Implementation Notes

• Valid ids for the practitioner and location 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, and location parameters may be included only once and may not be used in combination with the others. For example, patient=1234,5678 is supported but patient=1234&patient=5678 and patient=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, or lt 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)
• The retrieved appointments are sorted first by start date ascending (earliest first), followed by the provided search parameter (patient, practitioner or location) and start 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 to proposed.
• 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 to needs-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
Description The type of the FHIR resource. Example { "resourceType: "Appointment" } Notes resourceType must be Appointment top of section
slot	Yes	List of Reference (Slot)
Description The availability to which the appointment is booked. Example { "slot": [ { "reference": "Slot/21265426-633867-6828001-60" } ] } Notes At most one slot can be populated. top of section
status	Yes	code
Description A code representing the overall status of the Appointment. Each of the participants has their own participation status which indicates their involvement in the process, however this status indicates the shared status. Example { "status": "proposed" } Notes When creating a new appointment, the status must be "proposed". top of section
participant	Yes	List of BackboneElement
Description Participants involved in appointment. Example { "participant": [ { "actor": { "reference": "Patient/4704007", "display": "Smart, Barney R" }, "status": "needs-action" } ] } Notes When creating a new appointment, at most one participant can be populated. top of section
participant.actor	Yes	Reference (Patient)
Description A person, location, healthcare service or device that is participating in the appointment. Example { "actor": { "reference": "Patient/4704007", "display": "Smart, Barney R" } } Notes When creating a new appointment, this must be a Patient participant. top of section
participant.status	Yes	code
Description Participation status of the Patient. Example { "status": "needs-action" } Notes When creating a new appointment, this value must be "needs-action". top of section
comment	No	string
Description Additional text to aid in facilitating the appointment. Example { "comment: "Further explain MRI results" } top of section

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 or cancelled.
• Appointment.participant must have at least one participant.
• Appointment.participant.status must be accepted 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
Description The type of the FHIR resource. Example { "resourceType: "Appointment" } Notes resourceType must be Appointment top of section
status	Yes	code
Description A code representing the overall status of the Appointment. Each of the participants has their own participation status which indicates their involvement in the process, however this status indicates the shared status. Example { "status": "arrived" } Notes When updating an appointment, the status must be "arrived" or "cancelled". top of section
participant	Yes	List of BackboneElement
Description Participants involved in appointment. Example { "participant": [ { "actor": { "reference": "Patient/4704007", "display": "Smart, Barney R" }, "status": "accepted" } ] } top of section
participant.actor	Yes	Reference
Description A person, location, healthcare service or device that is participating in the appointment. Example { "actor": { "reference": "Patient/4704007", "display": "Smart, Barney R" } } top of section
participant.status	Yes	code
Description Participation status of the actor. Example { "status": "accepted" } Notes When updating an appointment, this value must be "accepted". top of section

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 a 412 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.