Calendars & Appointments

Calendars define how and when people can book time on your SMBcrm account: the services offered, appointment length, and availability. Appointments are the individual bookings placed on those calendars, whether created through a booking widget or directly through the API. Some endpoints refer to them as events rather than appointments.

Base URL: https://services.smbcrm.com · Version header: v3 · Scopes: calendars.readonly / calendars.write for calendar configuration, calendars/events.readonly / calendars/events.write for appointments. See Scopes.

List & retrieve calendars

GET/calendars/

List the calendars configured in your SMBcrm account/location.

scope calendars.readonlyauth Location token or PIT

curl "https://services.smbcrm.com/calendars/?locationId=<location_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "calendars": [
    {
      "id": "<calendar_id>",
      "locationId": "<location_id>",
      "name": "Sales Consultation",
      "description": "30-minute intro call with a sales rep",
      "calendarType": "event",
      "slotDuration": 30,
      "slotDurationUnit": "mins"
    }
  ]
}

GET/calendars/{calendarId}

Fetch a single calendar by ID.

scope calendars.readonlyauth Location token or PIT

curl https://services.smbcrm.com/calendars/<calendar_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "calendar": {
    "id": "<calendar_id>",
    "locationId": "<location_id>",
    "name": "Sales Consultation",
    "description": "30-minute intro call with a sales rep",
    "calendarType": "event",
    "slotDuration": 30,
    "slotDurationUnit": "mins"
  }
}

Create, update & delete a calendar

POST/calendars/

Create a calendar in your SMBcrm account/location.

scope calendars.writeauth Location token or PIT

locationId and name are required. The remaining fields configure the calendar’s availability and booking behavior.

curl -X POST https://services.smbcrm.com/calendars/ \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "<location_id>",
    "name": "Sales Consultation",
    "description": "30-minute intro call with a sales rep",
    "calendarType": "event",
    "slotDuration": 30,
    "slotDurationUnit": "mins"
  }'

201 Created

{
  "calendar": {
    "id": "<calendar_id>",
    "locationId": "<location_id>",
    "name": "Sales Consultation",
    "description": "30-minute intro call with a sales rep",
    "calendarType": "event",
    "slotDuration": 30,
    "slotDurationUnit": "mins"
  }
}

PUT/calendars/{calendarId}

Update settings on an existing calendar.

scope calendars.writeauth Location token or PIT

curl -X PUT https://services.smbcrm.com/calendars/<calendar_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sales Consultation (30 min)", "slotDuration": 30 }'

DELETE/calendars/{calendarId}

Permanently delete a calendar.

scope calendars.writeauth Location token or PIT

curl -X DELETE https://services.smbcrm.com/calendars/<calendar_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

Caution

Cancel or reschedule any upcoming appointments on a calendar before deleting it.

Check availability

GET/calendars/{calendarId}/free-slots

Get open booking slots for a calendar within a date range.

scope calendars.readonlyauth Location token or PIT

startDate and endDate are Unix timestamps in milliseconds; timezone is an IANA timezone name used to compute the returned slot times.

curl "https://services.smbcrm.com/calendars/<calendar_id>/free-slots?startDate=1784073600000&endDate=1784419200000&timezone=America/Chicago" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "2026-07-15": {
    "slots": ["2026-07-15T09:00:00-05:00", "2026-07-15T09:30:00-05:00", "2026-07-15T10:00:00-05:00"]
  },
  "2026-07-16": {
    "slots": ["2026-07-16T09:00:00-05:00", "2026-07-16T09:30:00-05:00"]
  }
}

Tip

Check free-slots again immediately before booking. A slot that was open when the page loaded can be taken by another booking before your request arrives.

List & retrieve appointments

GET/calendars/events

List appointments and events on a calendar within a time range.

scope calendars/events.readonlyauth Location token or PIT

curl "https://services.smbcrm.com/calendars/events?locationId=<location_id>&calendarId=<calendar_id>&startTime=1784073600000&endTime=1784678400000" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "events": [
    {
      "id": "<event_id>",
      "calendarId": "<calendar_id>",
      "locationId": "<location_id>",
      "contactId": "<contact_id>",
      "title": "Sales Consultation",
      "appointmentStatus": "confirmed",
      "startTime": "2026-07-15T20:00:00.000Z",
      "endTime": "2026-07-15T20:30:00.000Z"
    }
  ]
}

GET/calendars/events/appointments/{eventId}

Fetch a single appointment by ID.

scope calendars/events.readonlyauth Location token or PIT

curl https://services.smbcrm.com/calendars/events/appointments/<event_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "event": {
    "id": "<event_id>",
    "calendarId": "<calendar_id>",
    "locationId": "<location_id>",
    "contactId": "<contact_id>",
    "title": "Sales Consultation",
    "appointmentStatus": "confirmed",
    "startTime": "2026-07-15T20:00:00.000Z",
    "endTime": "2026-07-15T20:30:00.000Z"
  }
}

Book, update & delete appointments

POST/calendars/events/appointments

Book a new appointment on a calendar.

scope calendars/events.writeauth Location token or PIT

calendarId, locationId, contactId, and startTime are required; endTime is optional.

curl -X POST https://services.smbcrm.com/calendars/events/appointments \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "calendarId": "<calendar_id>",
    "locationId": "<location_id>",
    "contactId": "<contact_id>",
    "startTime": "2026-07-15T20:00:00.000Z",
    "endTime": "2026-07-15T20:30:00.000Z",
    "title": "Sales Consultation"
  }'

201 Created

{
  "id": "<event_id>",
  "calendarId": "<calendar_id>",
  "locationId": "<location_id>",
  "contactId": "<contact_id>",
  "title": "Sales Consultation",
  "appointmentStatus": "confirmed",
  "startTime": "2026-07-15T20:00:00.000Z",
  "endTime": "2026-07-15T20:30:00.000Z"
}

PUT/calendars/events/appointments/{eventId}

Reschedule or update an existing appointment.

scope calendars/events.writeauth Location token or PIT

appointmentStatus accepts new, confirmed, cancelled, showed, noshow, invalid, completed, or active.

curl -X PUT https://services.smbcrm.com/calendars/events/appointments/<event_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-07-16T18:00:00.000Z",
    "endTime": "2026-07-16T18:30:00.000Z",
    "appointmentStatus": "confirmed"
  }'

DELETE/calendars/events/{eventId}

Permanently delete an appointment or event.

scope calendars/events.writeauth Location token or PIT

eventId is the same id returned by the appointment endpoints above.

curl -X DELETE https://services.smbcrm.com/calendars/events/<event_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

Related

• Contacts: the contactId you pass when booking an appointment.
• Opportunities & Pipelines: track a booked appointment through a sales pipeline.
• Workflows: automate reminders and follow-ups around bookings.