Get a Practitioner's Availability

Overview

In this guide, we will find the earliest available appointments for a practitioner near your patient.

Since we are in test mode, we return simulated data but you will get a sense of how to use our API to get availability information.

Getting a practitioner's availability

Let's say we want our patient to see a Family Medicine physician and we even know her NPI.

First, we want to retrieve the Practitioner object and the physician's Railway id. This object represents a practitioner who exposes their open slots and/or booking capabilities through our API, and holds basic demographic and specialty information of the practitioner. Open up your terminal and send the following curl command.

curl --request GET \
     --url 'https://api.closurehealth.com/practitioners?npis=4321098765' \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic Y2hfc2tfdGVzdF9xdWlja3N0YXJ0Og==' \
     --header 'Closure-API-Version: 2022-04-01' \
     --header 'Closure-Index-Version: idx_standard'

You will get back the following response indicating (1) the requested physician is on Railway and (2) you will be able to view availabilities and book appointments with her.

[
  {
    "id": "prac_j3uc7oA7FYMtXhGZi2rbt9",
    "npi": "4321098765",
    "first_name": "Deepika",
    "last_name": "Sanon",
    "middle_name": "K",
    "preferred_name": "Deepika",
    "administrative_gender": "Female",
    "type": "Physician",
    "specialties": [
      "sp_c32Biop9tvoo1pR8JUZR55",
      "sp_9FjLB5Xj497FAbVkazRRFr"
    ],
    "primary_specialty": "sp_c32Biop9tvoo1pR8JUZR55",
    "languages": [
      "English",
      "Hindi",
      "Telugu"
    ],
    "created_at": "2022-04-01T00:00:00.000Z",
    "updated_at": "2022-04-01T00:00:00.000Z"
  }
]

You'll see that her Railway-provided id is prac_j3uc7oA7FYMtXhGZi2rbt9. You'll also notice some other ids prefixed with sp_. sp_ ids identify Specialty objects. Try using our documentation to send an API request to the GET /specialties/{specialty_id} endpoint to expand the ids!

📘
Each Railway API resource has a prefixed id to help easily distinguish the type of the resource. You can always query a resource's GET endpoint to expand the id.

Let's now use Dr. Sanon's id to view her schedules.

curl --request GET \
     --url 'https://api.closurehealth.com/schedules?practitioner_ids=prac_j3uc7oA7FYMtXhGZi2rbt9' \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic Y2hfc2tfdGVzdF9xdWlja3N0YXJ0Og==' \
     --header 'Closure-API-Version: 2022-04-01' \
     --header 'Closure-Index-Version: idx_standard'

You will get back a list of schedules. Physicians will often have different schedules for different types of appointments. They may also practice at multiple locations, each with its own schedule.

Let's say we want to find Dr. Sanon's schedule for in-person, new patient appointments. We send the same request with an additional query parameter appointment_type_ids to filter down our response. You can find the list of appointment type ids here.

curl --request GET \
     --url 'https://api.closurehealth.com/schedules?practitioner_ids=prac_j3uc7oA7FYMtXhGZi2rbt9&appointment_type_ids=aptp_1jHntMhNReS4zkUKftYvKo' \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic Y2hfc2tfdGVzdF9xdWlja3N0YXJ0Og==' \
     --header 'Closure-API-Version: 2022-04-01' \
     --header 'Closure-Index-Version: idx_standard'

You will get back the following response.

[
  {
    "id": "sch_u5oQnnMdSbyb83xgqgkUgX",
    "practitioner": "prac_j3uc7oA7FYMtXhGZi2rbt9",
    "location": "loc_rMVtnVcJ7HLtUC9ydntLBP",
    "insurances": [
      "ins_8rdzjCQtD1VLg9aLRwARNF",
      "ins_uhdLdVFFLTWa3V2ffrgHmy"
    ],
    "appointment_type": "aptp_1jHntMhNReS4zkUKftYvKo",
    "estimated_earliest_slot": "2022-05-20",
    "scheduling_method": "direct_api",
    "created_at": "2022-04-01T00:00:00.000Z",
    "updated_at": "2022-04-01T00:00:00.000Z"
  }
]

Similar to the previous GET /practitioners response, each Schedule object has an id and some other prefixed ids. Remember you can query a resource's GET endpoint to expand ids.

Now, to finally get the latest (and live) availabilities, or open slots, send the following request from your terminal.

curl --request GET \
     --url 'http://localhost:8000/schedules/sch_u5oQnnMdSbyb83xgqgkUgX/slots' \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic Y2hfc2tfdGVzdF9xdWlja3N0YXJ0Og==' \
     --header 'Closure-API-Version: 2022-04-01' \
     --header 'Closure-Index-Version: idx_standard

You will get back the doctor's available slots!

[
  {
    "start_at": "2022-05-20T16:45:00.000Z",
    "duration": 30
  },
  {
    "start_at": "2022-05-20T17:00:00.000Z",
    "duration": 30
  },
  {
    "start_at": "2022-05-20T17:15:00.000Z",
    "duration": 30
  }
]

Wrapping up

Congratulations! With just the practitioner's NPI, you were successfully able to retrieve her availabilities.