Calendar and Appointments API

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.