Provider Availability

GET/api/v1/calendar/provider-availability

Retrieves Calendly availability links for providers in an organization, filtered by US state. Optionally filter by provider email, event type ID, or time range.

cv-api-keyRate Limited

Productionhttps://api.care360-next.carevalidate.com/api/v1/calendar/provider-availability

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/calendar/provider-availability

Parameters

Headers

cv-api-keystringrequired

API key for authentication

Query Parameters

provider_statesstringrequired

Comma-separated list of US state abbreviations. Must contain at least one valid US state code. Spaces are trimmed.

Example: CA,NY,TX

provider_emailstringoptional

Email address of the provider to filter by. Will be converted to lowercase and trimmed. If not provided, returns availability for all providers matching the state criteria.

Example: provider@example.com

event_type_idstringoptional

The unique identifier of the Calendly event type. If not provided, returns availability for all event types matching the state criteria.

Example: event-type-id

start_timestringoptional

Start time of the event in ISO 8601 format. If provided, end_time and event_type_id must also be provided.

Example: 2024-01-01T12:00:00Z

end_timestringoptional

End time of the event in ISO 8601 format. If provided, start_time and event_type_id must also be provided.

Example: 2024-01-01T12:00:00Z

Examples

cURL (by state & email)

curl -X GET "https://api.example.com/api/v1/calendar/provider-availability?provider_states=CA,NY&provider_email=doctor@example.com" \
-H "cv-api-key: your-api-key-here"

cURL (with time range)

curl -X GET "https://api.example.com/api/v1/calendar/provider-availability?provider_states=CA,NY&event_type_id=event-type-id&start_time=2024-01-01T12:00:00Z&end_time=2024-01-01T12:00:00Z" \
-H "cv-api-key: your-api-key-here"

JavaScript

const params = new URLSearchParams({
provider_states: "CA,NY",
provider_email: "doctor@example.com",
});

const response = await fetch(
`https://api.example.com/api/v1/calendar/provider-availability?${params}`,
{
  method: "GET",
  headers: {
    "cv-api-key": "your-api-key-here",
  },
}
);

const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
  "https://api.example.com/api/v1/calendar/provider-availability",
  headers={
      "cv-api-key": "your-api-key-here",
  },
  params={
      "provider_states": "CA,NY",
      "provider_email": "doctor@example.com",
  },
)

print(response.json())

Try It Out

Try itAPI Playground

▶

Responses

▶200Success (by state & email)Provider availability links fetched successfully. Returns provider name, Calendly link, and event type ID.

{
  "status": 200,
  "success": true,
  "message": "Providers Availability link fetched successfully",
  "data": [
    {
      "providerName": "Dr. John Doe",
      "calendlyLink": "https://calendly.com/provider/john-doe",
      "eventTypeId": "85f13305-0647-4473-9e63-0a56af405f6f"
    },
    {
      "providerName": "Dr. Jane Smith",
      "calendlyLink": "https://calendly.com/provider/jane-smith",
      "eventTypeId": "85f13305-0647-4473-9e63-0a56af405f6f"
    }
  ]
}

▶200Success (with time range)When event_type_id, start_time, and end_time are provided, the response includes available start time slots.

{
  "status": 200,
  "success": true,
  "message": "Providers Availability link fetched successfully",
  "data": [
    {
      "providerName": "Dr. John Doe",
      "calendlyLink": "https://calendly.com/provider/john-doe/2025-12-01T03:30:00+00:00",
      "startTime": [
        "2025-12-01T03:30:00Z",
        "2025-12-01T04:00:00Z",
        "2025-12-01T05:00:00Z",
        "2025-12-01T05:30:00Z"
      ],
      "eventTypeId": "85f13305-0647-4473-9e63-0a56af405f6f"
    }
  ]
}

▶400Bad RequestReturned when query parameters are invalid, state codes are invalid, or required parameters are missing.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Error message describing the validation failure"
}

▶401UnauthorizedReturned when API key is missing or invalid.

{
  "status": 401,
  "success": false,
  "message": "Unauthorized"
}

▶429Too Many RequestsReturned when rate limit is exceeded.

{
  "status": 429,
  "success": false,
  "message": "Rate limit exceeded"
}