Get Provider Availability

Endpoint

GET /api/v1/provider-availability

Description

Fetches Calendly availability links for providers based on provider states. This route retrieves the Calendly event types and availability links associated with providers in a specific organization, optionally filtered by provider email, event type id, start time, end time and provider states.

Authentication

This endpoint requires API key authentication via the cv-api-key header.

Headers

Header Name	Type	Required	Description
cv-api-key	string	Yes	API key for authentication

Query Parameters

Parameter	Type	Required	Description
provider_email	string	No	Email address of the provider to filter by. If provided, will be converted to lowercase and trimmed.
provider_states	string	Yes	Comma-separated list of US state abbreviations (e.g., "CA,NY,TX"). Must be valid US state codes.
event_type_id	string	No	The unique identifier of the calendly event type
start_time	string	Conditional*	Start time of the event in ISO 8601 format (e.g., "2024-01-01T12:00:00Z"). If provided, end_time and event_type_id must also be provided (and vice versa)
end_time	string	Conditional*	End time of the event in ISO 8601 format (e.g., "2024-01-01T12:00:00Z"). If provided, start_time and event_type_id must also be provided (and vice versa)

Query Parameter Details

provider_states

• Format: Comma-separated string of state abbreviations
• Example: "CA,NY,TX" or "CA, NY, TX" (spaces are trimmed)
• Validation:
  • Must contain at least one character
  • Each state code must be a valid US state abbreviation (e.g., CA, NY, TX, FL)
  • Invalid state codes will result in a validation error

provider_email

• Format: Valid email address string
• Example: "provider@example.com" or "Provider@Example.COM"
• Note: If not provided, the endpoint will return availability for all providers matching the state criteria

event_type_id

• Format: Valid calendly event type id string
• Example: "event-type-id"
• Note: If not provided, the endpoint will return availability for all event types and matching the state criteria

start_time

• Format: Valid ISO 8601 date-time string
• Example: "2024-01-01T12:00:00Z"
• Note: If not provided, the endpoint will return availability for all time ranges and matching the state criteria

end_time

• Format: Valid ISO 8601 date-time string
• Example: "2024-01-01T12:00:00Z"
• Note: If not provided, the endpoint will return availability for all time ranges and matching the state criteria

Rate Limiting

This endpoint is protected by rate limiting middleware. Excessive requests may result in rate limit errors.

Request Example

Request with provider states and provider email

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

Request with provider states, event type id, start time and end time

curl -X GET "https://api.example.com/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"

Success Response

Status Code

200 OK

Response Body (When provider states and provider email are provided)

{
  "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"
    }
  ]
}

Response Fields

Field	Type	Description
status	number	HTTP status code (200)
success	boolean	Indicates successful request (true)
message	string	Success message
data	array	Array of provider availability objects
data[].providerName	string	Name of the provider
data[].calendlyLink	string	Calendly scheduling link with event type id for the provider
data[].eventTypeId	string	Event type id of the event

Response Body (When provider states, event type id, start time and end time are provided)

{
  "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"
    }
  ]
}

Response Fields

Field	Type	Description
status	number	HTTP status code (200)
success	boolean	Indicates successful request (true)
message	string	Success message
data	array	Array of provider availability objects
data[].providerName	string	Name of the provider
data[].calendlyLink	string	Calendly scheduling link with slot time for the provider
data[].startTime	array	Array of start times of the event in ISO 8601 format
data[].eventTypeId	string	Event type id of the event

Error Responses

400 Bad Request

Returned when:

• Invalid query parameters are provided
• Invalid state codes are included in provider_states
• Required parameters are missing
• Other validation errors occur

Response Body

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

429 Too Many Requests

Returned when rate limit is exceeded.

401 Unauthorized

Returned when API key is missing or invalid.