POST

Create Appointment

Books a new appointment for a contact on a calendar.

POSThttps://api.vantaxai.com/v1/appointments

`contact_id`, `title`, `appointment_date`, and `sub_account_id` are required. When a `calendar_id` is supplied, the appointment's `duration` defaults to that calendar's configured slot length unless you override it. `status` defaults to `confirmed`. If the calendar is connected to an external provider (e.g. Google Calendar), VantaX mirrors the event automatically.

Agent assignment

When an appointment is booked by an Agent during a call or conversation, the originating `agent_id` is recorded on the appointment automatically. Booking through the API on behalf of a contact behaves the same way once the calendar is tied to an Agent.

Headers

Authorizationstringrequired
Bearer authentication with your secret API key.
example: Bearer vx_live_3fa9c2…
Content-Typestringrequired
Must be application/json for requests with a body.
example: application/json

Body Parameters

contact_idstringrequired
The contact the appointment is booked for.
example: ct_4f8a21
titlestringrequired
Short title shown on the calendar event.
example: Dental cleaning consultation
appointment_datestringrequired
Start time of the appointment as an ISO-8601 UTC timestamp.
example: 2026-06-09T15:00:00Z
sub_account_idstringrequired
Sub-account that will own the appointment.
example: sub_8a1f4c2e
calendar_idstringoptional
Calendar to book on. Determines the default duration and any external sync.
example: cal_22f9
descriptionstringoptional
Longer notes about the appointment.
durationintegeroptional
Length in minutes. Defaults to the calendar's slot length, or 30 if none is set.
statusstringoptional
Initial status. Defaults to `confirmed`.
scheduledconfirmedcompletedcancelledno_show
example: confirmed
locationstringoptional
Where the appointment takes place (address, room, or 'Phone').
example: Downtown Clinic, Suite 200
assigned_user_idstringoptional
Team member responsible for the appointment.
example: usr_61b8af

Request

curl -X POST https://api.vantaxai.com/v1/appointments \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "ct_4f8a21",
    "calendar_id": "cal_22f9",
    "title": "Dental cleaning consultation",
    "appointment_date": "2026-06-09T15:00:00Z",
    "duration": 30,
    "location": "Downtown Clinic, Suite 200",
    "sub_account_id": "sub_8a1f4c2e"
  }'

const res = await fetch("https://api.vantaxai.com/v1/appointments", {
  method: "POST",
  headers: {
    Authorization: "Bearer vx_live_3fa9c2...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "ct_4f8a21",
    calendar_id: "cal_22f9",
    title: "Dental cleaning consultation",
    appointment_date: "2026-06-09T15:00:00Z",
    sub_account_id: "sub_8a1f4c2e",
  }),
});
const { data: appointment } = await res.json();

const appointment = await vantax.appointments.create({
  contactId: "ct_4f8a21",
  calendarId: "cal_22f9",
  title: "Dental cleaning consultation",
  appointmentDate: "2026-06-09T15:00:00Z",
  subAccountId: "sub_8a1f4c2e",
});

appointment = vantax.appointments.create(
    contact_id="ct_4f8a21",
    calendar_id="cal_22f9",
    title="Dental cleaning consultation",
    appointment_date="2026-06-09T15:00:00Z",
    sub_account_id="sub_8a1f4c2e",
)

Response

{
  "success": true,
  "message": "Appointment created successfully",
  "data": {
    "id": "appt_7c1d90",
    "contact_id": "ct_4f8a21",
    "calendar_id": "cal_22f9",
    "agent_id": "agt_3d9b21",
    "title": "Dental cleaning consultation",
    "description": null,
    "appointment_date": "2026-06-09T15:00:00Z",
    "duration": 30,
    "status": "confirmed",
    "location": "Downtown Clinic, Suite 200",
    "created_at": "2026-06-08T09:12:00Z"
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "appointment_date", "message": "appointment_date is required" }
  ]
}