Calendar and Appointments API

How to check available time slots and create appointments in Omnifox's Calendar module via API.

Jul 11, 2026

Watch this step in the video · Automations with appointments

The Calendar module lets you schedule appointments (meetings, demos, support sessions) linked to a contact, an agent, and optionally a conversation or a CRM deal. The API exposes the same engine that powers public booking links.

Requirements

  • A Bearer token for the workspace.
  • An existing calendar_id (GET /api/v1/calendar/calendars) and, if applicable, a service_id (GET /api/v1/calendar/services).

Main endpoints

  • GET/POST /api/v1/calendar/calendars — the workspace's calendars (one per agent or resource).
  • GET/POST /api/v1/calendar/services — service/duration types (e.g. "30-min demo").
  • GET /api/v1/calendar/slots — available time slots for a calendar/service within a date range.
  • GET/POST /api/v1/calendar/appointments — list or create appointments.
  • PUT /api/v1/calendar/appointments/{id} — reschedule.
  • POST /api/v1/calendar/appointments/{id}/cancel — cancel.
  • GET/POST /api/v1/calendar/booking-links — public self-service booking links.

Fields to create an appointment

{
  "calendar_id": 3,
  "service_id": 7,
  "contact_id": 55,
  "starts_at": "2026-07-20T15:00:00-05:00",
  "ends_at": "2026-07-20T15:30:00-05:00",
  "title": "Omnifox demo",
  "notes": "Customer interested in the CRM module"
}

Only calendar_id and starts_at are required; if you send service_id, the duration is calculated automatically.

Example: check open slots before booking

curl -X GET "https://app.omnifox.io/api/v1/calendar/slots?calendar_id=3&service_id=7&from=2026-07-20&to=2026-07-22" \
  -H "Authorization: Bearer YOUR_TOKEN"

Tips

  • Always query /slots before POST /appointments to avoid scheduling conflicts; the create endpoint still validates availability server-side as a safety net.
  • Attach deal_id or conversation_id to the appointment so it's traceable in the contact's history and the CRM timeline.

Troubleshooting

  • 422 when creating the appointment: the starts_at/ends_at range overlaps another appointment on the same calendar.
  • The slot looked open but creation failed: it may have been booked between your query and your request; re-fetch /slots.
  • The appointment doesn't show the contact: verify contact_id belongs to the correct workspace.
Was this helpful?

Related articles

Message us on WhatsApp