Skip to content
This repository was archived by the owner on Dec 20, 2024. It is now read-only.

Scheduling Appointments

Jump to bottom
jay-lee00 edited this page May 29, 2019 · 13 revisions

IMPORTANT NOTE:

The v2.1/clinicians/appointments API has been deprecated in favor of v3/admin/appointments.

The information below is intended to support those still using the v2.1/clinicians/appointments API. Documentation for the most recent version of the scheduling API can be found here.

A central point of the Virtual Care Management system is handling appointments between patients and clinicians. In the system, this means managing both availability blocks and scheduling encounters within those blocks.

While each call is itself a standalone action, managing appointments requires organizing each action into a series of steps to complete the process.

The Process of Scheduling an Appointment

Scheduling an appointment can be broken into a series of steps that mirror much of what you would do manually in a traditional appointment book.

  1. Check the schedule and find an open time where a doctor can see the patient.
  2. If there isn't any availability scheduled, create some, if possible.
  3. Take basic information on why the patient wishes to see a doctor.
  4. Mark down the appointment to reserve the time block with the intake information you gathered.

Overall, the process is very straightforward, although you may need to make several API calls to get the required information to make the appointment in the system. These extra API calls are documented for the endpoints where they are required.

Creating an Appointment

Creating an appointment requires an open availability block for the provider you wish the patient to see.

To create an appointment, you will need to post a JSON request to /api/v2.1/clinicians/appointments with the following parameters:

  • appointmentTypeCode - (integer) Either 1 for a scheduled "future" appointment or 2 for an "on-demand" appointment.
  • availabilityBlockId - (GUID) The GUID for the appointment block in which you are scheduling the appointment.
  • startTime - (string) An ISO 8601 date and time indicating the start time of the appointment.
  • endTime - (string) An ISO 8601 date and time indicating the end time of the appointment.
  • intakeMetadata - An intake metadata item.
  • participants - (array) An array of participants
  • waiveFee - (boolean) Optional. A boolean indicating if the appointment fee should be waived or not. Defaults to false.

If the scheduling was a success, you will get back an object with an appointment in the data field.

If an availability block does not exist for the appointment time, you will get back an error message with a 400 status code. If there is a conflicting appointment, you will get back an error message with a 409 status code.

Note that you must provide a bearer authentication token for a user that has permission to create appointments.

Example:

The following example shows us scheduling an appointment to an existing availability block.

Request

POST https://sandbox.connectedcare.md/api/v2.1/clinicians/appointments

Headers Sent:

  • X-Developer-Id: ****
  • X-Api-Key: ****
  • Authorization: ****

Request Body:

{
  "appointmentTypeCode": 1,
  "intakeMetadata": {
    "additionalNotes": "None! <strong>Bold </strong><em>Ital</em>",
    "concerns": [
      {
        "isPrimary": true,
        "customCode": {
          "code": 3262,
          "description": "Stomach and Abdominal Pain"
        }
      }
    ]
  },
  "participants": [
    {
      "appointmentId": 0,
      "attendenceCode": 1,
      "personId": "85673c2c-f429-4d90-8ffd-6b750f20c8ae",
      "person": {
        "id": "85673c2c-f429-4d90-8ffd-6b750f20c8ae",
        "name": {
          "given": "Kotoori",
          "prefix": "",
          "suffix": "",
          "family": "Sarasa"
        },
        "providerId": 131,
        "statusCode": 1,
        "contactTypeCode": 2,
        "phones": [
          {
            "id": "49e7e769-32be-43b8-9276-4b76b65fd329",
            "use": "home",
            "value": "+15555551212"
          }
        ]
      },
      "participantTypeCode": 2
    },
    {
      "appointmentId": 0,
      "attendenceCode": 1,
      "personId": "3fbcfe23-7f18-4222-809a-2a9af209c118",
      "person": {
        "id": "3fbcfe23-7f18-4222-809a-2a9af209c118",
        "name": {
          "given": "John",
          "prefix": "",
          "suffix": "",
          "family": "TestPatient"
        },
        "providerId": 131,
        "statusCode": 1,
        "contactTypeCode": 1,
        "phones": [
          {
            "id": "7943dd7c-e45d-4a85-a090-016747692ed9",
            "use": "mobile",
            "value": "+1-555-555-2345"
          }
        ]
      },
      "participantTypeCode": 1
    }
  ],
  "waiveFee": true,
  "availabilityBlockId": "c9565bf7-fce6-441c-8acb-eef047fdfadc",
  "startTime": "2016-05-06T14:15:00+0100",
  "endTime": "2016-05-06T14:45:00+0100"
}

Response

Response Code (Success): 200 OK

{
  "data": [
    {
      "appointmentId": "e9365425-a9a8-48f7-9f62-20be2140fcef",
      "patientId": 3381,
      "clinicianId": 234,
      "appointmentStatusCode": "Scheduled",
      "participants": [
        {
          "participantId": "a3e7f1ab-bada-4f36-a92b-6191d274c860",
          "person": {
            "id": "85673c2c-f429-4d90-8ffd-6b750f20c8ae",
            "name": {
              "given": "Kotoori",
              "prefix": "",
              "suffix": "",
              "family": "Sarasa"
            },
            "providerId": 131,
            "statusCode": 1,
            "contactTypeCode": 2,
            "phones": [
              {
                "id": "49e7e769-32be-43b8-9276-4b76b65fd329",
                "use": "home",
                "value": "+15555551212"
              }
            ]
          },
          "status": 1,
          "attendenceCode": 1,
          "personId": "85673c2c-f429-4d90-8ffd-6b750f20c8ae",
          "participantTypeCode": 2
        },
        {
          "participantId": "aad91a91-2d0f-409e-9c19-333bfa77e300",
          "person": {
            "id": "3fbcfe23-7f18-4222-809a-2a9af209c118",
            "name": {
              "given": "John",
              "prefix": "",
              "suffix": "",
              "family": "TestPatient"
            },
            "providerId": 131,
            "statusCode": 1,
            "contactTypeCode": 1,
            "phones": [
              {
                "id": "7943dd7c-e45d-4a85-a090-016747692ed9",
                "use": "mobile",
                "value": "+1-555-555-2345"
              }
            ]
          },
          "status": 1,
          "attendenceCode": 1,
          "personId": "3fbcfe23-7f18-4222-809a-2a9af209c118",
          "participantTypeCode": 1
        }
      ],
      "availabilityBlockId": "c9565bf7-fce6-441c-8acb-eef047fdfadc",
      "waiveFee": true,
      "startTime": "2016-05-06T15:15:00+01:00",
      "endTime": "2016-05-06T15:45:00+01:00",
      "appointmentTypeCode": 1,
      "intakeMetadata": {
        "concerns": [
          {
            "customCode": {
              "code": 3262,
              "description": "Stomach and Abdominal Pain"
            },
            "isPrimary": true
          }
        ],
        "additionalNotes": "None! <strong>Bold </strong><em>Ital</em>"
      }
    }
  ],
  "total": 1
}

Listing Appointments

When you need to see what appointments are scheduled, you can send an API request to see upcoming appointments.

To use this endpoint, make a get request to v2.1/clinicians/appointments. Include the query string with parameters from the Parameter List.

There are many query string parameters you can use to narrow the list, but if you do not include any, you will get a full list. The optional query string parameters you can use include:

  • startDate - (string) A string in ISO 8601 format representing a date or date and time for the beginning of your search.
  • endDate - (string) A string in ISO 8601 format representing a date or date and time for the end of your search.
  • excludeTotalCount - (boolean) true or false (default false) to return total count of search result.
Because get total count is a resource intensive process, excludeTotalCount=true should be included if total is not needed for the response.

It is important to set at least a startDate when requesting a list. If you do not provide either parameter, you will get back all appointments at all times for your site.

If you have appointments in the date range, you will get back an object with an appointment in the data field.

Note that you must provide a bearer authentication token for a user that has permission to view appointments for the provider.

Example:

The following example shows us requesting a list of all upcoming appointments.

Request

GET https://sandbox.connectedcare.md/api/v2.1/clinicians/appointments?excludeTotalCount=true

Headers Sent:

  • X-Developer-Id: ****
  • X-Api-Key: ****
  • Authorization: ****

Response

Response Code (Success): 200 OK

{
  "data": [
    {
      "appointmentId": "5524e95d-7cac-4043-8e85-89adc9f12927",
      "patientId": 3381,
      "clinicianId": 234,
      "appointmentStatusCode": "Scheduled",
      "participants": [
        {
          "participantId": "7c77885e-6b3f-49ab-95ed-3be17ea55029",
          "person": {
            ...
          },
          "status": 1,
          "attendenceCode": 1,
          "personId": "3fbcfe23-7f18-4222-809a-2a9af209c118",
          "participantTypeCode": 1
        },
        {
          "participantId": "aa132e10-c549-4f58-a916-fdcd57bb6809",
          "person": {
            ...
          },
          "status": 1,
          "attendenceCode": 1,
          "personId": "85673c2c-f429-4d90-8ffd-6b750f20c8ae",
          "participantTypeCode": 2
        }
      ],
      "availabilityBlockId": "f3a3c1a8-7177-4a99-ac73-fde8a46249f6",
      "waiveFee": false,
      "startTime": "2016-05-04T12:00:00+01:00",
      "endTime": "2016-05-04T12:30:00+01:00",
      "appointmentTypeCode": 1,
      "intakeMetadata": {
        ...
      }
    }
  ],
  "total": 1
}

Contents

Clone this wiki locally