Fetch Appointments

GET/api/v1/calendar/appointments

Retrieves calendar appointments for an organization. Supports filtering by date range and user email. Returns only active, non-deleted, future appointments for non-archived cases.

cv-api-keyRate Limited

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

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

Parameters

Headers

cv-api-keystringrequired

Organization API key for authentication and authorization

Query Parameters

start_datestringoptional

Start date of the date range filter. Format: YYYY-MM-DD. If provided, end_date must also be provided. If user_email is not provided, this field is required.

Example: 2024-01-01

end_datestringoptional

End date of the date range filter. Format: YYYY-MM-DD. If provided, start_date must also be provided. start_date must be less than or equal to end_date.

Example: 2024-01-31

user_emailstringoptional

Filter appointments by user email. If not provided, both start_date and end_date are required.

Example: user@example.com

Behavior Details

• Date Filtering: start_date is set to start of day (00:00:00), end_date is set to end of day (23:59:59). Matches events that overlap the range.
• User Filtering: If user_email is provided, the system looks up the user by email (case-insensitive) and filters appointments to that user only. Returns NotFoundError if user does not exist.
• Data Filtering: Only returns appointments where isDeleted = false, end >= current date, associated case is not archived, and case belongs to the authenticated organization.
• Sorting: Results are sorted by endDateTime in ascending order (earliest end times first).
• Rate Limit: 500 requests per 60 seconds per organization.

Examples

cURL

curl -X GET "https://api.example.com/api/v1/calendar/appointments?start_date=2024-01-01&end_date=2024-01-31&user_email=user@example.com" \
-H "cv-api-key: your-api-key-here"

JavaScript

const params = new URLSearchParams({
start_date: "2024-01-01",
end_date: "2024-01-31",
user_email: "user@example.com",
});

const response = await fetch(
`https://api.example.com/api/v1/calendar/appointments?${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/appointments",
  headers={
      "cv-api-key": "your-api-key-here",
  },
  params={
      "start_date": "2024-01-01",
      "end_date": "2024-01-31",
      "user_email": "user@example.com",
  },
)

print(response.json())

Try It Out

Try itAPI Playground

▶

Responses

▶200SuccessAppointments fetched successfully. Returns an array of appointment objects with case and submitter information. Empty results return an empty array in the data field.

{
  "status": 200,
  "success": true,
  "message": "Appointments fetched successfully",
  "data": [
    {
      "id": "event-id",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z",
      "title": "Appointment Title",
      "start": "2024-01-20T14:00:00Z",
      "end": "2024-01-20T15:00:00Z",
      "topic": "Meeting Topic",
      "description": "Appointment description",
      "color": "#FF5733",
      "isEditable": true,
      "agentEventId": "agent-event-id",
      "agentName": "Agent Name",
      "status": "CONFIRMED",
      "isDeleted": false,
      "meetingDetails": {},
      "case": {
        "id": "case-id",
        "shortId": "CASE-123",
        "status": "ACTIVE",
        "title": "Case Title"
      },
      "submitter": {
        "id": "user-id",
        "firstName": "John",
        "lastName": "Doe",
        "email": "user@example.com"
      }
    }
  ]
}

▶400Bad RequestReturned when query parameters are invalid, date format is incorrect, required dates are missing, date range is invalid, or user is not found.

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

▶429Too Many RequestsReturned when rate limit is exceeded. Maximum 500 requests per 60 seconds.

{
  "status": 429,
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Maximum 500 requests per 60 seconds exceeded",
  "retryAfter": 60
}