Availability

Free slots for a person, a role, or whoever can take an appointment type, from the same diary and working hours the CRM uses.

GET Availability

GET/v1/appointments/availability

Which staff are free when. Ask for particular people, for everyone with a role, or let an appointment type choose the role, and get each person's slots for the days requested plus, per slot, who is free in it. One of users, roles or a role-bearing type is required. At most 50 people per request; narrow with users or roles for more.

Query parameters

fromstring · date

First calendar day, in your timezone.

Default: today

tostring · date

Last calendar day, inclusive. At most 31 days.

Default: six days after from

usersstring · listOne of required

User ids or emails.

At least one of: users, roles, type

rolesstring · listOne of required

Everyone holding any of these roles.

At least one of: users, roles, type

typestring · name, value or idOne of required

When neither users nor roles is sent, the type's roles (see appointment types) pick the people. A type for anyone still needs users or roles.

At least one of: users, roles, type

slotMinutesinteger · 15 to 480

Slot length.

Default: 60

availablestring

only drops the slots, and the people in each slot, that are not free.

Valid values: only, all

Default: all

How a slot is decided

Slots run across your organisation's working time, the Morning and Afternoon set under the CRM's schedule settings (09:00 to 17:00 when none is set), starting when the day opens. For each person a slot is free unless it is:

closed: the day is a bank holiday or shutdown in the CRM's working days.
busy: they are on an appointment that overlaps it, directly or through a team, in any status but cancelled. An all-day appointment, including an approved absence, blocks its whole days.
not_working: your organisation runs the CRM's Work Schedules and they are not scheduled then. As in the CRM's Slot view this is advisory, and booking is still allowed.

Weekends are not treated specially; close them with the CRM's working days if needed.

Responses

200

`users`, each with their `slots`, and `slots`, each with who is free in it.

422

No `users`, `roles` or role-bearing `type`; an unknown user or type; more than 50 people; or a window over 31 days. `fields` names it.

Example request

# any salesman, next week, hour slots
curl "https://api.evacrm.co.uk/v1/appointments/availability?roles=salesman&from=2026-10-12&to=2026-10-16" \
  -H "Authorization: Bearer sk_..."

# one person's diary, half-hour slots, free ones only
curl "https://api.evacrm.co.uk/v1/appointments/availability?users=jo@example.com&from=2026-10-13&slotMinutes=30&available=only" \
  -H "Authorization: Bearer sk_..."

# a showroom slot: the type is booked for salesmen, so their free slots come back
curl "https://api.evacrm.co.uk/v1/appointments/availability?type=showroom&from=2026-10-13&available=only" \
  -H "Authorization: Bearer sk_..."

Example response · 200

{
  "from": "2026-10-13",
  "to": "2026-10-13",
  "timezone": "Europe/London",
  "slotMinutes": 240,
  "workingHours": [{ "start": "08:00", "end": "17:00" }],
  "workingHoursSource": "organisation",
  "workSchedules": false,
  "type": null,
  "roles": ["salesman"],
  "closedDays": [],
  "users": [
    {
      "id": "cd9356b7-dd81-4f9a-a6fd-9cc9ae967a4e",
      "name": "Tuan Dinh",
      "email": "tuan@example.com",
      "roles": ["salesman", "surveyor"],
      "slots": [
        { "start": "2026-10-13T08:00:00.000+01:00", "end": "2026-10-13T12:00:00.000+01:00", "available": true },
        { "start": "2026-10-13T12:00:00.000+01:00", "end": "2026-10-13T16:00:00.000+01:00", "available": false, "reason": "busy" }
      ]
    }
  ],
  "slots": [
    { "start": "2026-10-13T08:00:00.000+01:00", "end": "2026-10-13T12:00:00.000+01:00", "available": ["cd9356b7-dd81-4f9a-a6fd-9cc9ae967a4e"] },
    { "start": "2026-10-13T12:00:00.000+01:00", "end": "2026-10-13T16:00:00.000+01:00", "available": [] }
  ]
}

users[].slots is one person's diary; slots is the same information turned round, for "who can I send at ten on Tuesday". closedDays lists the days that came back closed and why, and workingHoursSource is default when your organisation has no working time set.

Booking a slot

Take a slot's start and the person's id to book an appointment. The booking runs the CRM's clash check again, so a slot taken between the two calls comes back as a 409.

Availability

GET Availability

How a slot is decided

Booking a slot

On this page