Query BETA

Required plan: Scheduler

Description #

Queries Scheduling Requests in an Organizational Unit.

Authentication is with either:

  1. an access token for the Organizational Unit, created by authorizing an application for an Organizational Unit scope like organizational_unit_scheduler
  2. the 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 OK
Content-Type: application/json; charset=utf-8

{
  "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",
        "duration": { "minutes": 30 },
        "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"
          }
        ],
        "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",
        "duration": { "minutes": 30 },
        "buffer": {
          "before": { "minutes": 20 },
          "after": { "minutes": 15 }
        },
        "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"
          }
        ],
        "collaborators": [
          { "sub": "acc_7fad963a87459cefb4010b71" }
        ],
        "collaborator_groups": [
          {
            "name": "Driving Examiners",
            "members": [
              { "sub": "acc_75623a84e774744c496051d7" },
              { "sub": "acc_51bb3cc0c34e5364ff06bb6e" },
              { "sub": "acc_c1278d31ed6c4a9dd262afa2" }
            ],
            "required": 1
          }
        ],
        "event": {
          "host": {
            "email": "ihost@evenitron.com",
            "display_name": "Ian Host",
            "sub": "acc_962bfe62001ed91c7e906242",
            "status": "accepted"
          },
          "attendees": [
            {
              "email": "marty@evenitron.com",
              "display_name": "Dr Emmet Brown",
              "status": "accepted"
            },
            {
              "email": "bob@evenitron.com",
              "display_name": "Bob Visser"
              "sub": "acc_7fad963a87459cefb4010b71",
              "status": "needs_action"
            },
            {
              "email": "alice@hiring.evenitron.com",
              "display_name": "Alice McHiring",
              "sub": "acc_75623a84e774744c496051d7",
              "status": "tentative"
            }
          ],
          "start": {
            "time": "2024-10-31T14:00:00Z",
            "tzid": "Europe/London"
          },
          "end": {
            "time": "2024-10-31T14:30:00Z",
            "tzid": "Europe/London"
          },
          "summary": "Driving lessons - Marty & Doc",
          "metadata": {
            "scheduler": {
              "correlation_id": "foobar",
              "utm_medium": "email",
              "utm_source": "automated_email_workflow",
              "utm_campaign": "candidate_interview_offer_email",
              "captured_data.phone_number": "0118999881999119725 3",
              "captured_data.notes": "No dietary requirements."
            }
          }
        }
      }
    }
  ]
}

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.

Note that you can query up to 10 ID’s at a time.

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 required  #

An Object containing the details of a scheduling request.

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.duration optional  #

A Duration value representing the duration of the event.

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.

scheduling_requests.scheduling_request.recipient_operations required  #

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

Please note that it will only contain URLs for actions that are available for the Scheduling Request in its current state. For example, if the Scheduling Request is not allowed to reschedule, reschedule_url will not be provided.

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 required  #

An Object containing the details of the event.

scheduling_requests.scheduling_request.event.host optional  #

An Object containing the details of the event host.

scheduling_requests.scheduling_request.event.host.email required  #

A String of the email of the host on the event.

scheduling_requests.scheduling_request.event.host.display_name required  #

A String of the name of the host on the event.

scheduling_requests.scheduling_request.event.host.sub required  #

A String of the account ID of the host.

scheduling_requests.scheduling_request.event.host.status required  #

A String representing the participation status of the host with regard to the event.

One of:

  • needs_action
    the event needs action by the host, usually they have been sent an invite but are yet to respond
  • accepted
    they have accepted an invitation to the event
  • declined
    they have declined an invitation to the event
  • tentative
    they have tentatively accepted an invitation to the event
  • unknown
    their participation status for the event is unknown

unknown is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize.

scheduling_requests.scheduling_request.event.attendees optional  #

An array containing the attendees other than the host.

scheduling_requests.scheduling_request.event.attendees.email required  #

A String of the email of the attendee on the event.

scheduling_requests.scheduling_request.event.attendees.display_name required  #

A String of the name of the attendee on the event.

scheduling_requests.scheduling_request.event.attendees.sub optional  #

A String of the account ID of the attendee if it has an account.

scheduling_requests.scheduling_request.event.attendees.status required  #

A String representing the participation status of the attendee with regard to the event.

One of:

  • needs_action
    the event needs action by the attendee, usually they have been sent an invite but are yet to respond
  • accepted
    they have accepted an invitation to the event
  • declined
    they have declined an invitiation to the event
  • tentative
    they have tentatively accepted an invitation to the event
  • unknown
    their participation status for the event is unknown

unknown is not expected to be used but is included and documented so there is a documented response for attendees we may not know how to categorize.

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.