Schedule Appointment

Endpoint

POST /api/v1/calendar/appointments

Description

Creates a calendar appointment for a given Calendly event type and invitee. This endpoint uses an existing Calendly event type and the requested start time to book the appointment.

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

Request Body

Body Fields

Field	Type	Required	Description
eventTypeId	string	Yes	The unique identifier of the calendly event type.
startTime	string	Yes	Desired start time of the appointment in ISO 8601 format (e.g., "2025-11-28T04:30:00Z"). This should be a valid ISO 8601 date-time string. and correct slot time.
email	string	Yes	Invitee email address.
firstName	string	No	Invitee first name.
lastName	string	No	Invitee last name.
timezone	string	Yes	IANA timezone identifier for the invitee (e.g., "Asia/Kolkata").
location	string	Yes	Location type for the meeting (e.g., "google_conference").
tracking	object	No	Object containing UTM and other tracking metadata.

tracking Object Fields

Field	Type	Required	Description
utmCampaign	string | null	No	UTM campaign identifier.
utmSource	string | null	No	UTM source identifier.
utmMedium	string | null	No	UTM medium identifier.
utmContent	string | null	No	UTM content identifier.
utmTerm	string | null	No	UTM term identifier.
salesforceUuid	string | null	No	Tracking identifier that can be used to correlate appointments with Salesforce or other external systems.

Location types

The location field can be one of the following values:

• google_conference
• zoom_conference
• gotomeeting_conference
• microsoft_teams_conference
• webex_conference

Request Example

curl --location "https://api.example.com/api/v1/calendar/appointments" \
  --header "cv-api-key: your-org-cv-api-key" \
  --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
    }
  }'

Rate Limiting

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

Success Response

Status Code

200 OK

Response Body

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

Response Fields

Field	Type	Description
status	number	HTTP status code (200).
success	boolean	Indicates successful request (true).
message	string	Success message.

Error Responses

400 Bad Request

Returned when:

• Invalid request body is provided
• Required fields are missing
• Fields fail validation (e.g., invalid startTime format)

Response Body

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

401 Unauthorized

Returned when API key is missing or invalid.

429 Too Many Requests

Returned when rate limit is exceeded.