Schedule Appointment

POST/api/v1/calendar/appointments

Schedules a new appointment for a Calendly event type and invitee. Books the appointment using the specified event type and start time.

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

API key for authentication

Request Body

eventTypeIdstringrequired

The unique identifier of the Calendly event type.

Example: 85f13305-0647-4473-9e63-0a56af405f6f

startTimestringrequired

Desired start time of the appointment in ISO 8601 format. Must be a valid date-time string and correct slot time.

Example: 2025-11-28T04:30:00Z

emailstringrequired

Invitee email address.

Example: invitee@example.com

firstNamestringoptional

Invitee first name.

Example: John

lastNamestringoptional

Invitee last name.

Example: Doe

timezonestringrequired

IANA timezone identifier for the invitee.

Example: Asia/Kolkata

locationstringrequired

Location type for the meeting.

Example: google_conference

Values:google_conferencezoom_conferencegotomeeting_conferencemicrosoft_teams_conferencewebex_conference

trackingobjectoptional

Object containing UTM and other tracking metadata.

Show 6 child properties

utmCampaignstring | nulloptional

UTM campaign identifier.

utmSourcestring | nulloptional

UTM source identifier.

utmMediumstring | nulloptional

UTM medium identifier.

utmContentstring | nulloptional

UTM content identifier.

utmTermstring | nulloptional

UTM term identifier.

salesforceUuidstring | nulloptional

Tracking identifier that can be used to correlate appointments with Salesforce or other external systems.

Examples

cURL

curl --location "https://api.example.com/api/v1/calendar/appointments" \
--header "cv-api-key: your-org-cv-api-key" \
--header "Content-Type: application/json" \
--data-raw '{
  "eventTypeId": "85f13305-0647-4473-9e63-0a56af405f6f",
  "startTime": "2025-11-28T04:30:00Z",
  "email": "invitee@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "timezone": "Asia/Kolkata",
  "location": "google_conference",
  "tracking": {
    "utmCampaign": null,
    "utmSource": null,
    "utmMedium": null,
    "utmContent": null,
    "utmTerm": null,
    "salesforceUuid": null
  }
}'

JavaScript

const response = await fetch("https://api.example.com/api/v1/calendar/appointments", {
method: "POST",
headers: {
  "Content-Type": "application/json",
  "cv-api-key": "your-org-cv-api-key",
},
body: JSON.stringify({
  eventTypeId: "85f13305-0647-4473-9e63-0a56af405f6f",
  startTime: "2025-11-28T04:30:00Z",
  email: "invitee@example.com",
  firstName: "John",
  lastName: "Doe",
  timezone: "Asia/Kolkata",
  location: "google_conference",
  tracking: {
    utmCampaign: null,
    utmSource: null,
    utmMedium: null,
    utmContent: null,
    utmTerm: null,
    salesforceUuid: null,
  },
}),
});

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

Python

import requests

response = requests.post(
  "https://api.example.com/api/v1/calendar/appointments",
  headers={
      "Content-Type": "application/json",
      "cv-api-key": "your-org-cv-api-key",
  },
  json={
      "eventTypeId": "85f13305-0647-4473-9e63-0a56af405f6f",
      "startTime": "2025-11-28T04:30:00Z",
      "email": "invitee@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "timezone": "Asia/Kolkata",
      "location": "google_conference",
      "tracking": {
          "utmCampaign": None,
          "utmSource": None,
          "utmMedium": None,
          "utmContent": None,
          "utmTerm": None,
          "salesforceUuid": None,
      },
  },
)

print(response.json())

Try It Out

Try itAPI Playground

▶

Responses

▶200SuccessMeeting scheduled successfully.

{
  "status": 200,
  "success": true,
  "message": "Meeting scheduled successfully"
}

▶400Bad RequestReturned when the request body is invalid, required fields are missing, or fields fail validation (e.g., invalid startTime format).

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