# Query

#### Description
Queries Scheduling Requests in an Organizational Unit.

Authentication is with either:

- an access token for the Organizational Unit, created by authorizing an application for an [Organizational Unit scope](/developers/authorization/organization-connect/index.md) like `organizational_unit_scheduler`

- the `client_secret` of an [Internal Application](/developers/application-management/internal-applications/index.md) linked to the Organizational Unit.

> **INFO:** This API will be extended to support for more advanced queries.

If you have a particular use case that you'd like to ask about, please reach out to us at [support@cronofy.com](mailto:support@cronofy.com).

Your feedback helps us design and prioritize feature enhancements.

#### URL format
```
{data_center_url}/v1/scheduling_requests/query
```

#### Example Request
```http
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
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": "2026-04-27T14:00:00Z",
            "tzid": "Europe/London"
          },
          "end": {
            "time": "2026-04-27T14: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](/developers/data-centers/index.md).
##### `scheduling_request_ids` *(required)*

An array containing the ID [`String`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) containing the details of a scheduling request.

##### `scheduling_requests.scheduling_request.scheduling_request_id` *(required)*

Cronofy's unique identifier for the Scheduling Request [`String`](/developers/api/data-types/index.md).

##### `scheduling_requests.scheduling_request.slot_selection` *(required)*

A [`String`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) value of the URL to the Cronofy dashboard page to view and manage the Scheduling Request.

##### `scheduling_requests.scheduling_request.summary` *(required)*

The [`String`](/developers/api/data-types/index.md) value of the summary, sometimes referred to as the name, of the event.

##### `scheduling_requests.scheduling_request.duration` *(optional)*

A [`Duration`](/developers/api/data-types/index.md) value representing the duration of the event.

##### `scheduling_requests.scheduling_request.buffer` *(optional)*

A set of [`Buffer`](/developers/scheduling/buffers/index.md) values that override participants default buffers configured in their scheduler preferences.

##### `scheduling_requests.scheduling_request.buffer.before` *(optional)*

A [`Duration`](/developers/api/data-types/index.md) specifying the minimum number of minutes that must be free before an available period starts.

##### `scheduling_requests.scheduling_request.buffer.after` *(optional)*

A [`Duration`](/developers/api/data-types/index.md) specifying the minimum number of minutes that must be free after the available period ends.

##### `scheduling_requests.scheduling_request.recipient_operations` *(required)*

An [`Object`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) value of the URL to the page to view the Scheduling Request.

##### `scheduling_requests.scheduling_request.recipient_operations.decline_url` *(optional)*

A [`String`](/developers/api/data-types/index.md) value of the URL to the page to decline the Scheduling Request.

##### `scheduling_requests.scheduling_request.recipient_operations.reschedule_url` *(optional)*

A [`String`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md) email address of the recipient of the Scheduler Request.

##### `scheduling_requests.scheduling_request.recipients.display_name` *(required)*

A [`String`](/developers/api/data-types/index.md) value representing the name of the recipient.

##### `scheduling_requests.scheduling_request.recipients.slot_selector` *(required)*

A [`Boolean`](/developers/api/data-types/index.md) 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`](/developers/api/data-types/index.md).

##### `scheduling_requests.scheduling_request.collaborator_groups.required` *(required)*

Either a [`String`](/developers/api/data-types/index.md) of `all` to specify that all `members` of the group need to be available for a period to be viable, or an [`Integer`](/developers/api/data-types/index.md) to specify the minimum number of the group that must be available.

##### `scheduling_requests.scheduling_request.event` *(required)*

An [`Object`](/developers/api/data-types/index.md) containing the details of the event.

##### `scheduling_requests.scheduling_request.event.host` *(optional)*

An [`Object`](/developers/api/data-types/index.md) containing the details of the event host.

##### `scheduling_requests.scheduling_request.event.host.email` *(required)*

A [`String`](/developers/api/data-types/index.md) of the email of the host on the event.

##### `scheduling_requests.scheduling_request.event.host.display_name` *(required)*

A [`String`](/developers/api/data-types/index.md) of the name of the host on the event.

##### `scheduling_requests.scheduling_request.event.host.sub` *(required)*

A [`String`](/developers/api/data-types/index.md) of the account ID of the host.

##### `scheduling_requests.scheduling_request.event.host.status` *(required)*

A [`String`](/developers/api/data-types/index.md) representing the participation status of the host with regard to the event.

One of:

- `needs_action`<br/>the event needs action by the host, usually they have been sent an invite but are yet to respond

- `accepted`<br/>they have accepted an invitation to the event

- `declined`<br/>they have declined an invitation to the event

- `tentative`<br/>they have tentatively accepted an invitation to the event

- `unknown`<br/>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`](/developers/api/data-types/index.md) of the email of the attendee on the event.

##### `scheduling_requests.scheduling_request.event.attendees.display_name` *(required)*

A [`String`](/developers/api/data-types/index.md) of the name of the attendee on the event.

##### `scheduling_requests.scheduling_request.event.attendees.sub` *(optional)*

A [`String`](/developers/api/data-types/index.md) of the account ID of the attendee if it has an account.

##### `scheduling_requests.scheduling_request.event.attendees.status` *(required)*

A [`String`](/developers/api/data-types/index.md) representing the participation status of the attendee with regard to the event.

One of:

- `needs_action`<br/>the event needs action by the attendee, usually they have been sent an invite but are yet to respond

- `accepted`<br/>they have accepted an invitation to the event

- `declined`<br/>they have declined an invitiation to the event

- `tentative`<br/>they have tentatively accepted an invitation to the event

- `unknown`<br/>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`](/developers/api/data-types/index.md) value of the summary, sometimes referred to as the name, of the event.

##### `scheduling_requests.scheduling_request.event.start.time` *(optional)*

A [`Time`](/developers/api/data-types/index.md) representing the UTC start time of the event.

##### `scheduling_requests.scheduling_request.event.start.tzid` *(optional)*

A string representing the [`Timezone`](/developers/calendars-events/time-zones/index.md) of the event

##### `scheduling_requests.scheduling_request.event.end.time` *(optional)*

A [`Time`](/developers/api/data-types/index.md) representing the UTC end time of the event.

##### `scheduling_requests.scheduling_request.event.end.tzid` *(optional)*

A string representing the [`Timezone`](/developers/calendars-events/time-zones/index.md) of the event

##### `scheduling_requests.scheduling_request.event.metadata` *(optional)*

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


---
[Read in HTML](/developers/api/scheduling-requests/query/)