Available Slots

Read as Markdown

Description #

Lists the available times for a Scheduling Request so your application can present them or choose one directly.

This is an integration operation. Read Integration Operations first for the shared response envelope, result vocabulary, authentication, and error shapes.

Once you have the times, book one with Select Slot, using the simple_select_slot_url returned alongside them.

Listing requires the organizational_unit_scheduling scope.

You do not build this URL. It is returned as the opaque simple_available_slots_url under the request’s integration_operations. No request body is required.

When a request qualifies #

A Scheduling Request advertises simple_available_slots_url only when it can be completed with just a time. That means it is awaiting slot selection, places a single event, and needs no further input from the person booking.

Requests that need more than a time are excluded. Required data capture, consent questions, and custom questions all require the person to complete the booking page. Multi-event and sequence requests place an event per step, so a single time can never complete them.

An excluded request has an empty integration_operations object, and the person should be sent to the booking page via recipient_operations.view_url. If the operation is called by URL regardless, the response is not_possible with a result_detail of requires_more_input.

Example Request #

Send the request to the simple_available_slots_url returned on the Scheduling Request, exactly as given.

POST {SIMPLE_AVAILABLE_SLOTS_URL} HTTP/1.1
Authorization: Bearer {API_KEY}

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "integration_operation_result": {
    "type": "available_slots",
    "result": "success",
    "integration_operations": {
      "simple_select_slot_url": "{SIMPLE_SELECT_SLOT_URL}"
    },
    "available_slots": [
      { "start": "2026-10-24T09:00:00Z", "end": "2026-10-24T09:30:00Z" },
      { "start": "2026-10-24T09:30:00Z", "end": "2026-10-24T10:00:00Z" },
      { "start": "2026-10-24T14:00:00Z", "end": "2026-10-24T14:30:00Z" }
    ],
    "suggested_slots": [
      { "start": "2026-10-24T09:00:00Z", "end": "2026-10-24T09:30:00Z" },
      { "start": "2026-10-24T14:00:00Z", "end": "2026-10-24T14:30:00Z" }
    ]
  },
  "scheduling_request": {
    "scheduling_request_id": "srq_7b9784257940f9bbbfcad097",
    "slot_selection": "pending",
    "primary_select_url": "https://app.cronofy.com/rts/wZ9tLbN4sWjH6yD1cF0a",
    "dashboard_url": "https://app.cronofy.com/scheduler/requests/7b9784257940f9bbbfcad097",
    "summary": "Intro call with Riya Patel",
    "duration": { "minutes": 30 },
    "recipient_operations": {
      "view_url": "https://app.cronofy.com/rts/wZ9tLbN4sWjH6yD1cF0a"
    },
    "integration_operations": {
      "simple_available_slots_url": "{SIMPLE_AVAILABLE_SLOTS_URL}"
    }
  }
}

Request parameters #

This operation takes no request body; the only input is the credential.

API_KEY Required  #

An access token for the Organizational Unit or the client_secret of the linked Internal Application. See Authentication.

Response parameters #

integration_operation_result  #

An Object describing the outcome of the operation. See The response envelope.

integration_operation_result.type  #

A String of available_slots for this operation.

integration_operation_result.result  #

A String outcome, one of:

  • success: the times were listed (200).
  • not_possible: the request cannot be booked with just a time in its current state (409); see result_detail.

integration_operation_result.result_detail  #

Present only when result is not_possible. A String explaining why, one of no_longer_possible, superseded, requires_more_input, or configuration_error. See result_detail.

integration_operation_result.integration_operations  #

An Object of the actions available next. On a success it carries simple_select_slot_url; otherwise it is empty.

integration_operation_result.integration_operations.simple_select_slot_url  #

A String URL to select a time. Returned here, alongside the times, because a time cannot be selected before it has been listed.

integration_operation_result.available_slots  #

An array of the available times. Present when result is success. Each is an Object with start and end.

integration_operation_result.available_slots.start  #

A Time representing the UTC start of the slot.

integration_operation_result.available_slots.end  #

A Time representing the UTC end of the slot, derived from the request’s fixed duration.

integration_operation_result.suggested_slots  #

A small, spread-out subset of available_slots to highlight if you want to offer a shortlist rather than the full list. Each has the same start and end shape as available_slots.

scheduling_request  #

The full Scheduling Request, in the same shape as the Query response. It travels alongside every envelope response so you can render the current state without a second call.

Error responses #

Beyond the shared errors for authentication, authorization, an unknown token, and rate limiting, this operation returns not_possible (409) when the request cannot be booked with just a time. No times are returned and the accompanying scheduling_request shows why. Because listing takes no input and never books, it never returns invalid or conflict.

{
  "integration_operation_result": {
    "type": "available_slots",
    "result": "not_possible",
    "result_detail": "requires_more_input",
    "integration_operations": {}
  },
  "scheduling_request": { ... }
}