GET
/
availability
curl --request GET \
  --url https://api.usecobalt.com/v1/availability \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'
{
  "success": true,
  "results": {
    "availability": [
      {
        "day_of_week": 123,
        "date": "<string>",
        "duration_string": "<string>",
        "range_start": "<string>",
        "range_end": "<string>",
        "provider_name": "<string>",
        "timezone_abbr": "<string>"
      }
    ]
  }
}

​
Example Request

curl -X GET https://api.usecobalt.com/v1/availability \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-G \
--data-urlencode "start_date=2024-03-14T00:00:00-07:00" \
--data-urlencode "end_date=2024-04-14T23:59:59-07:00" \
--data-urlencode "buffer=30" \
--data-urlencode "visit_type=np" \
--data-urlencode "calculation_method=slots" \
--data-urlencode "slot_type=Open"

​
Example Response

{
    "success": true,
    "results": {
        "availability": [
            {
                "day_of_week": 5,
                "date": "2024-04-05",
                "duration_string": "9h",
                "range_start": "2024-04-05T08:00:00.000-07:00",
                "range_end": "2024-04-05T17:00:00.000-07:00",
                "provider_name": "John Doe",
                "timezone_abbr": "PDT"
            }
        ]
    },
    "timezone": "America/Los_Angeles"
}

Authorizations

​
client_id
string
header
required
​
client_secret
string
header
required
​
access_token
string
header
required

Query Parameters

​
start_date
string
required

The start of the date range (YYYY-MM-DD)

​
end_date
string
required

The end of the date range (YYYY-MM-DD)

​
provider_type
enum<string>
default:primary

Whether to check availability for the primary provider (default) or secondary provider

Available options:
primary,
secondary
​
fallback_to_default_hours
enum<string>
default:false

Whether to fallback to the default hours if no availability rules are defined for the provider

Available options:
true,
false
​
calculation_method
enum<string>
default:gaps

Specifies the method for determining availability. "gaps" (Default): Calculates availability based on the free time (also known as gaps) in a provider's schedule between their working hours and existing appointments. "slots": Retrieves availability based on pre-defined appointment slots (often derived from appointment notes/titles).

Available options:
gaps,
slots
​
slot_type
string

Required if calculation_method is 'slots'. Specifies the type/title of the appointment slots to retrieve. The matching is case-insensitive.

​
buffer
integer

Specifies a buffer time in minutes to add after appointments of a specific visit_type or all visit types. This effectively makes the provider unavailable for this duration after such an appointment. Must be a non-negative integer less than 60.

Required range: 0 <= x < 60
​
visit_type
string

Used in conjunction with buffer. Specifies the type of visit after which the buffer should be applied. Can also be 'all' to apply the buffer after all appointments. If buffer is set and visit_type is omitted, it defaults to 'all'. Must be 'all' or a valid visit type code configured for the user/organization (case-insensitive).

​
daily_appointment_limit
integer

If provided along with daily_limit_type, specifies the maximum number of appointments of that type a provider can have on a single day. If the limit is reached, no further availability will be shown for that day for that appointment type. Must be a positive integer. Requires daily_limit_type to also be provided.

Required range: x >= 1
​
daily_limit_type
string

Specifies the appointment type to which the daily_appointment_limit applies. Must be a valid visit type code configured for the user/organization (case-insensitive). Requires daily_appointment_limit to also be provided.

​
max_slot_duration
integer

If provided and calculation_method is 'gaps', this parameter instructs the system to subdivide large availability blocks into smaller, contiguous slots of this specified duration in minutes. Must be an integer between 5 and 60 (inclusive) and must be an increment of 5 (e.g., 5, 10, 15, ..., 60). When an available block of time is not an exact multiple of the max_slot_duration, the system will create as many full slots of the specified duration as possible. Any remaining portion of the block that is smaller than the max_slot_duration will not be returned as an available slot. For example, if there is a 45-minute availability block and max_slot_duration is set to 30 minutes, one 30-minute slot will be returned, and the remaining 15 minutes will not form an additional slot.

Required range: 5 <= x <= 60Must be a multiple of 5

Response

200 - application/json

Successful response

The response is of type object.