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:

Terminology Bindings

Appointment.type

Search for Appointments that meet supplied query parameters:

GET /Appointment?:parameters

Implementation Notes

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:

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

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
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.
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".
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.
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.
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".
comment No string
  • Description
    • Additional text to aid in facilitating the appointment.
  • Example
    • {
        "comment: "Further explain MRI results"
      }
      

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

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
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".
participant Yes List of BackboneElement
  • Description
    • Participants involved in appointment.
  • Example
    • {
        "participant": [
          {
            "actor": {
              "reference": "Patient/4704007",
              "display": "Smart, Barney R"
            },
            "status": "accepted"
          }
        ]
      }
      
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"
        }
      }
      
participant.status Yes code
  • Description
    • Participation status of the actor.
  • Example
    • {
        "status": "accepted"
      }
      
  • Notes
    • When updating an appointment, this value must be "accepted".

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: