This tutorial guides you through building a complete, custom appointment booking workflow using the CarePortals Public API. You will learn how to fetch available services, check for open time slots, retrieve the necessary booking form, and create the final appointment.

This guide is designed for developers building a bespoke booking experience, such as embedding an appointment scheduler into a custom application or website.

Prerequisites

Before you begin, make sure you have the following:

Configured Services: Ensure your organization has services, schedules, and forms configured in the CRM, as these are required to offer appointments.
Organization ID (<ORG_ID>): If you are hosting the booking flow on a custom domain, you must send the Organization ID (<ORG_ID>) in the request header. For requests made from a CarePortals subdomain, this header is not required, as the ID is retrieved from the domain itself.

Flow Overview

Here's a high-level overview of the booking flow we'll build:

Fetch Available Services: Retrieve a list of all appointment services available for booking.
Get Service Availability: Get the available time slots for a specific service selected by the patient.
Retrieve the Booking Form: Fetch the specific form associated with the selected service.
Create the Appointment: Submit the patient's details and selected time to book the appointment.

Step 1: Fetch Available Services

To begin the booking process, you must first display a list of available appointment services to the patient. You can retrieve this list by calling the Retrieve all Services endpoint. The response will include an array of service objects, each containing details like its name, description, duration, and the associated form ID.

curl -X GET 'https://public-api.portals.care/services' \
-H 'organization: <ORG_ID>'

[
  {
    "_id": "60d5ecb3a0b3f1001fbaa123",
    "organization": "<ORG_ID>",
    "label": "General Consultation",
    "description": "A standard consultation with one of our healthcare providers.",
    "status": "active",
    "slotDuration": 15,
    "slotGap": 5,
    "minLeadTime": 2,
    "maxLeadTime": 720,
    "form": {
      "id": "60d5f2a9a0b3f1001fbaa456"
    },
    "payment": {
      "enabled": true,
      "price": 50,
      "currency": "CAD",
      "payLater": false,
      "saveCardOnly": false,
      "hcCoverage": 0
    },
    "isVirtualMeeting": true
  },
  {
    "_id": "60d5ecb3a0b3f1001fbaa789",
    "organization": "<ORG_ID>",
    "label": "Follow-up Visit",
    "description": "A follow-up appointment to discuss previous results.",
    "status": "active",
    "slotDuration": 10,
    "slotGap": 0,
    "minLeadTime": 24,
    "maxLeadTime": 360,
    "form": {
      "id": "60d5f2a9a0b3f1001fbaa457"
    },
    "payment": {
      "enabled": false,
      "price": 0,
      "currency": "CAD",
      "payLater": false,
      "saveCardOnly": false,
      "hcCoverage": 100
    },
    "isVirtualMeeting": true
  }
]

A successful request returns a 200 OK status code and an array of service objects.

Step 2: Get Service Availability

After the patient selects a service, you must fetch its available time slots. Retrieve this schedule data by calling the Get Service Availability endpoint, passing the id of the chosen service as a path parameter. This will return a structured object of open time slots that can be presented to the patient.

curl -X GET 'https://public-api.portals.care/services/60d5ecb3a0b3f1001fbaa123/availability-v2' \
-H 'organization: <ORG_ID>'

{
  "2024-10-28": [
    "2024-10-28T14:00:00.000Z",
    "2024-10-28T14:15:00.000Z",
    "2024-10-28T14:30:00.000Z",
    "2024-10-28T15:00:00.000Z"
  ],
  "2024-10-29": [
    "2024-10-29T10:00:00.000Z",
    "2024-10-29T10:15:00.000Z",
    "2024-10-29T10:45:00.000Z"
  ],
  "2024-10-30": []
}

Step 3: Retrieve the Booking Form

Each service is linked to a specific form that the patient must complete. The form.id is included in the service object retrieved in Step 1.

To get the structure and fields of this form, you can use our Booking Web App in form mode.

Step 4: Create the Appointment

Once the patient has selected a time slot and filled out the required form, you can finalize the booking. To create the appointment record, call the Create an Appointment endpoint. The request body must include the serviceId, the chosen reservation time in UTC, and the form submission values.

curl -X POST 'https://public-api.portals.care/appointments' \
-H 'organization: <ORG_ID>' \
-H 'Content-Type: application/json' \
-d '{
  "serviceId": "60d5ecb3a0b3f1001fbaa123",
  "reservation": "2024-10-28T14:00:00.000Z",
  "values": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+15551234567",
    "visitReason": "General check-up and consultation."
  },
  "meta": {
    "timezone": "America/New_York"
  }
}'

{
  "_id": "60d5f3b7a0b3f1001fbaa999",
  "organization": "<ORG_ID>",
  "service": {
    "_id": "60d5ecb3a0b3f1001fbaa123",
    "label": "General Consultation"
  },
  "status": "booked",
  "reservation": "2024-10-28T14:00:00.000Z",
  "duration": 15,
  "accessKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "virtualMeeting": {
    "joinUrl": "https://zoom.us/j/1234567890"
  },
  "createdAt": "2024-09-22T21:40:00.000Z",
  "updatedAt": "2024-09-22T21:40:00.000Z"
}

A successful request returns a 201 Created status code and the complete appointment object. The accessKey can be used for future appointment management, such as cancellations.