Request
Basic information
| Field | Value |
|---|---|
| HTTP URL | https://api.dingtalk.io/v1.0/calendar/users/{userId}/querySchedule |
| HTTP Method | POST |
| Supported app types | appType-Internal app appType-Third-party enterprise app appType-Third-party personal app |
| Permission requirements | permission-Calendar.EventSchedule.Read-Read permission for event free/busy status 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 enterprise that authorized a third-party app API. - For a third-party personal app, call the Get user token API. |
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| userId | String | Yes | The unionId of the user to whom the resource of this request belongs. - For internal apps and third-party enterprise apps, call the Query user details API to obtain the value of the unionid parameter. - For third-party personal apps, call the Get user contacts profile API to obtain the value of the unionId parameter. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| userIds | Array of String | Yes | The unionId of the target user to query. - For internal apps and third-party enterprise apps, call the Query user details API to obtain the value of the unionid parameter. - For third-party personal apps, call the Get user contacts profile API to obtain the value of the unionId parameter. The maximum length of the user list is 20. |
| startTime | String | Yes | The start time of the query. |
| endTime | String | Yes | The end time of the query. |
Request example
HTTPResponse
Response body
| Name | Type | Description |
|---|---|---|
| scheduleInformation | Array | The user’s free/busy information. |
| userId | String | The unionId of the target user to query. |
| error | String | The error message. |
| scheduleItems | Array | The list of free/busy information. |
| status | String | The status. - BUSY: Busy - TENTATIVE: Tentatively busy |
| start | Object | The start time of the event. |
| date | String | The start date of the event, in the format yyyy-MM-dd. |
| dateTime | String | The start time of the event, in the date-time format of ISO-8601. |
| timeZone | String | The time zone name, following the IANA Time Zone Database standard, for example, Asia/Shanghai. The time zone for all-day events is fixed to UTC. For non-all-day events, the default time zone is Asia/Shanghai. |
| end | Object | The end time of the event. |
| date | String | The end date of the event, in the format yyyy-MM-dd. |
| dateTime | String | The end time of the event, in the date-time format of ISO-8601. |
| timeZone | String | The time zone name, following the IANA Time Zone Database standard, for example, Asia/Shanghai. The time zone for all-day events is fixed to UTC. For non-all-day events, the default time zone is Asia/Shanghai. |
Response body example
Error codes
If an error is returned when you call this API, refer to the Global error codes document for a solution based on the error message.| HttpCode | Error code | Error message | Description |
|---|---|---|---|
| 400 | paramIllegal | PARAM ILLEGAL | Invalid parameter |