Request
Basic information
| Field | Value |
|---|---|
| HTTP URL | https://api.dingtalk.io/v1.0/calendar/users/{userId}/meetingRooms/schedules/query |
| HTTP Method | POST |
| Supported app types | appType-Internal app appType-Third-party enterprise app |
| Required permissions | permission-Calendar.Event.Read-Read permission for events in the Calendar app |
Request headers
| Name | Type | Required | Description |
|---|---|---|---|
| x-acs-dingtalk-access-token | String | Yes | The access credential for calling this API. Obtain it as follows: - For an internal app, call the Get the access token of an internal app API. - For a third-party enterprise app, call the Get the access token of an organization authorized to a third-party app API. |
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| userId | String | Yes | The unionId of the user who owns the resource for this request. Call the Query user details API to obtain it. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| roomIds | Array of String | Yes | The list of roomIds to query. Call the Query the room list API to obtain them. We recommend that the number of roomIds does not exceed 5. |
| startTime | String | Yes | The start time of the query, in ISO 8601 format. Example: 2022-07-29T14:55Z. |
| endTime | String | Yes | The end time of the query, in ISO 8601 format. Example: 2022-07-29T14:55Z. |
Request example
HTTPResponse
Response body
| Name | Type | Description |
|---|---|---|
| scheduleInformation | Array | The free/busy information list of the rooms. |
| roomId | String | The roomId of the room. |
| error | String | The error message. |
| scheduleItems | Array | The free/busy information list. If this field returns empty, the room is free during the specified time range. |
| status | String | The free/busy status. - BUSY: Busy - TENTATIVE: Pending approval |
| eventId | String | The event ID. |
| organizer | Object | The information about the event organizer. |
| id | String | The unionId of the organizer. |
| start | Object | The information about the event start time. |
| dateTime | String | The event start time, in ISO 8601 format. Example: 2022-07-29T14:55Z. |
| timeZone | String | The time zone name, following the IANA Time Zone Database standard. Example: Asia/Shanghai. For all-day events, the time zone is fixed to UTC. For non-all-day events, the default time zone is Asia/Shanghai. |
| end | Object | The information about the event end time. |
| dateTime | String | The event end time, in ISO 8601 format. Example: 2022-07-29T14:55Z. |
| timeZone | String | The time zone name, following the IANA Time Zone Database standard. Example: Asia/Shanghai. For all-day events, the time zone is fixed to UTC. For non-all-day events, the default time zone is Asia/Shanghai. |
Response body example
Error codes
If the API call fails, find a solution by error message in the Global error codes document.| HttpCode | Error code | Error message | Description |
|---|---|---|---|
| 400 | invalidParameter | forwardErrorMessage | Invalid parameter |
| 400 | invalidParameter | query ids cannot be empty | The query IDs cannot be empty |
| 400 | invalidParameter | Cannot get schedule information for more than limit. | The number of queries exceeds the limit |
| 400 | invalidParameter | Cannot query schedule for more than 90 days. | The query duration exceeds the limit |
| 400 | invalidParameter | roomId invalid | The roomId is invalid |
| 400 | meetingRoomNotAvailable | room busy | The room is already occupied |