Available Slots ^ALPHA

Read as Markdown Required plan: Scheduler

This is an ALPHA feature and needs to be enabled by Cronofy support. Please email support@cronofy.com with the client_id of your Application to have it enabled.

Description #

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

This is the first of the two Time Selection integration operations. Read that page first for the shared response envelope, result vocabulary, authentication, and error shapes.

Listing requires the organizational_unit_scheduler 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.

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-09-17T09:00:00Z", "end": "2026-09-17T09:30:00Z" },
      { "start": "2026-09-17T09:30:00Z", "end": "2026-09-17T10:00:00Z" },
      { "start": "2026-09-17T14:00:00Z", "end": "2026-09-17T14:30:00Z" }
    ],
    "suggested_slots": [
      { "start": "2026-09-17T09:00:00Z", "end": "2026-09-17T09:30:00Z" },
      { "start": "2026-09-17T14:00:00Z", "end": "2026-09-17T14: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": { ... }
}

Available Slots ALPHA