Query ALPHA

Required plan: Scheduler

Description #

Queries Scheduling Requests in an Organizational Unit.

Authentication is with a client_secret of an Internal Application linked to the Organizational Unit.

URL format #

{data_center_url}/v1/scheduling_requests/query

Example Request #

POST /v1/scheduling_requests/query HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "scheduling_request_ids": [
    "srq_52b65401a5d87bb4f0bee44e",
    "srq_45e852c2a1f88ca940cc6e35",
    "srq_d6f3f8165239d662963fc09b"
  ]
}

Example Response #

HTTP/1.1 200 Accepted

{
  "scheduling_requests": [
    {
      "scheduling_request": {
        "scheduling_request_id": "srq_52b65401a5d87bb4f0bee44e",
        "slot_selection": "pending",
        "primary_select_url": "https://app.cronofy.com/rts/VFbnUVCv",
        "dashboard_url": "https://app.cronofy.com/scheduler/requests/52b65401a5d87bb4f0bee44e",
        "summary": "Driving test - Marty & Doc",
        "recipient_operations": {
          "view_url": "https://app.cronofy.com/rts/VFbnUVCv"
        },
        "recipients": [
          {
            "email": "marty@evenitron.com",
            "display_name": "Marty McFly",
            "slot_selector": true,
            "select_url": "https://app.cronofy.com/rts/VFbnUVCv"
          }
        ],
        "collaborator_groups": [
          {
            "name": "Driving Examiners",
            "members": [
              { "sub": "acc_61815034636bd5c5ce4fwd" },
              { "sub": "acc_61815034636bd5c5ce48a4" },
              { "sub": "acc_61815034636bd5c5ce29c7" }
            ],
            "required": 1
          }
        ],
        "event": {
          "summary": "Driving test - Marty & Doc"
        }
      }
    },
    {
      "scheduling_request": {
        "scheduling_request_id": "srq_d6f3f8165239d662963fc09b",
        "slot_selection": "complete",
        "primary_select_url": "https://app.cronofy.com/rts/suDzyKHW",
        "dashboard_url": "https://app.cronofy.com/scheduler/requests/d6f3f8165239d662963fc09b",
        "summary": "Driving lessons - Marty & Doc",
        "recipient_operations": {
          "view_url": "https://app.cronofy.com/rts/suDzyKHW",
          "decline_url": "https://app.cronofy.com/rts/suDzyKHW?decline=true",
          "reschedule_url": "https://app.cronofy.com/rts/suDzyKHW?reschedule=true"
        },
        "recipients": [
          {
            "email": "marty@evenitron.com",
            "display_name": "Marty McFly",
            "slot_selector": true,
            "select_url": "https://app.cronofy.com/rts/suDzyKHW"
          }
        ],
        "event": {
          "start": {
            "time": "2023-10-03T14:00:00Z",
            "tzid": "Europe/London"
          },
          "end": {
            "time": "2023-10-03T14:30:00Z",
            "tzid": "Europe/London"
          },
          "summary": "Driving lessons - Marty & Doc"
        }
      }
    }
  ]
}

Request Parameters #

data_center_url required

The URL for the data center you want to communicate with. Possible choices are:

  • api-au.cronofy.com - 🇦🇺 Australia
  • api-ca.cronofy.com - 🇨🇦 Canada
  • api-de.cronofy.com - 🇩🇪 Germany
  • api-sg.cronofy.com - 🇸🇬 Singapore
  • api-uk.cronofy.com - 🇬🇧 United Kingdom
  • api.cronofy.com - 🇺🇸 United States

Find out more about Cronofy's data centers.

scheduling_request_ids required  #

An array containing the ID String of the Scheduling Requests.

Response Parameters #

scheduling_requests required  #

An array containing a maximum of the 10 most recently created Scheduling Requests returned by the query.

Each Scheduling Request will have a scheduling_request key detailing the request itself.

Note that any IDs that could not be found are omitted. From the example, the ID srq_45e852c2a1f88ca940cc6e35 was requested in the query but is not in the output.

scheduling_requests.scheduling_request.scheduling_request_id required  #

Cronofy’s unique identifier for the Scheduling Request String.

scheduling_requests.scheduling_request.slot_selection required  #

A String representing the current state of the Scheduling Request.

Can be one of the following values:

  • pending - Waiting for the slot selector to choose a time slot.
  • pending_rescheduling - The request has been marked as needing to be rescheduled and we are waiting for the slot selector to choose a new time.
  • complete - A time has been selected for the event.
  • expired - The request has been open for too long such that there are no longer any slots within the requests time range.
  • cancelled - Scheduling request was cancelled.
scheduling_requests.scheduling_request.primary_select_url required  #

A String value of the URL to the page which a time can be chosen for the event.

scheduling_requests.scheduling_request.dashboard_url required  #

A String value of the URL to the Cronofy dashboard page to view and manage the Scheduling Request.

scheduling_requests.scheduling_request.summary required  #

The String value of the summary, sometimes referred to as the name, of the event.

scheduling_requests.scheduling_request.recipient_operations required  #

An Object containing the URLs for various operations that can be performed on the scheduling request.

scheduling_requests.scheduling_request.recipient_operations.view_url required  #

A String value of the URL to the page to view the Scheduling Request.

scheduling_requests.scheduling_request.recipient_operations.decline_url optional  #

A String value of the URL to the page to decline the Scheduling Request.

scheduling_requests.scheduling_request.recipient_operations.reschedule_url optional  #

A String value of the URL to the page to reschedule the Scheduling Request.

scheduling_requests.scheduling_request.recipients optional  #

An Array of recipients.

scheduling_requests.scheduling_request.recipients.email required  #

A String email address of the recipient of the Scheduler Request.

scheduling_requests.scheduling_request.recipients.display_name required  #

A String value representing the name of the recipient.

scheduling_requests.scheduling_request.recipients.slot_selector required  #

A Boolean value indicating whether or not the recipient is responsible for choosing the time slot for the event.

scheduling_requests.scheduling_request.recipients.select_url optional  #

A [String] of the URL for the recipient to the page which a time can be chosen for the event.

scheduling_requests.scheduling_request.collaborator_groups optional  #

One or more participants (people or resources) who’s availability should be considered alongside the host and invited to the resulting calendar event.

The parameters marked required are only required if a group is specified.

scheduling_requests.scheduling_request.collaborator_groups.name required  #

A name for the group that will be used when viewing the request in the Scheduler app.

scheduling_requests.scheduling_request.collaborator_groups.members required  #

An array of collaborators.

scheduling_requests.scheduling_request.collaborator_groups.members.sub required  #

The internal Cronofy ID for the group member, as an ASCII-only String.

scheduling_requests.scheduling_request.collaborator_groups.required required  #

Either a String of all to specify that all members of the group need to be available for a period to be viable, or an Integer to specify the minimum number of the group that must be available.

scheduling_requests.scheduling_request.event.summary required  #

The String value of the summary, sometimes referred to as the name, of the event.

scheduling_requests.scheduling_request.event.start.time optional  #

A Time representing the UTC start time of the event.

scheduling_requests.scheduling_request.event.start.tzid optional  #

A string representing the Timezone of the event

scheduling_requests.scheduling_request.event.end.time optional  #

A Time representing the UTC end time of the event.

scheduling_requests.scheduling_request.event.end.tzid optional  #

A string representing the Timezone of the event

scheduling_requests.scheduling_request.event.metadata optional  #

Any metadata written to the event which has been shared with your application.

scheduling_requests.scheduling_request.buffer optional  #

A set of Buffer values that override participants default buffers configured in their scheduler preferences.

scheduling_requests.scheduling_request.buffer.before optional  #

A Duration specifying the minimum number of minutes that must be free before an available period starts.

scheduling_requests.scheduling_request.buffer.after optional  #

A Duration specifying the minimum number of minutes that must be free after the available period ends.