# Obtain attendance result
Get the results of the actual clock in the enterprise, including:
* clock in task list
* ID in clock
* User information
* Attendance Team ID
* shift id
* Attendance records
* Work record
* Off-duty records
* Results in work clock
* Results in clock
* Results added in work clock
* Results added in clock
* Work clock in time
* Time in clock
List of invalid user IDs
* List of user IDs without permission
**Notice**：- If the shift set by the Company for an employee is clock-in at 9:00 a.m. and clock-out at 6:00 p.m., even if the employee submits attendance for several times during this period, the API will only return one record.
- If you want to obtain detailed data of attendance, such as information of attendance location, you can use the API of "Obtain Attendance Flow Record" or "Batch Query of Attendance Flow Record".
## Request
Facts |
---|---
HTTP URL | https://open.feishu.cn/open-apis/attendance/v1/user_tasks/query
HTTP Method | POST
Rate Limit | [50 per second](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App
Required scopes
**To use this API, you must have at least 1 of the listed scopes.** | Export attendance data(attendance:task:readonly)
### Request header
Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `tenant_access_token`
**Value format**: "Bearer `access_token`"
**Example value**: "Bearer t-7f1bcd13fc57d46bac21793a18e560"
[How to choose and get access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | Yes | **Fixed value**: "application/json; charset=utf-8"
### Query parameters
Parameter | Type | Required | Description
---|---|---|---
employee_type | string | Yes | Employee ID type. If you don't have background administrative privileges, you can use [Get user ID by mobile phone number or email](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/batch_get_id)
**Example value**: employee_id
**Optional values are**:
- employee_id：Employee's employee ID, that is the user ID in [Feishu Admin](https://example.larksuite.com/admin/index) > Organization > Member and Department > Member Details
- employee_no：Employee ID, that is the employee ID in [Feishu Admin](https://example.larksuite.com/admin/index) > Organization > Member and Department > Member Details
ignore_invalid_users | boolean | No | Whether to ignore invalid and no permissions users, the corresponding employee_type. If true, return the information of the valid user and inform the invalid and no permissions user; if false, and there are invalid or no permissions in the user_ids, return an error
**Example value**: true
include_terminated_user | boolean | No | Since the new employee can reuse the employee_no/employee_id of the departed employee, corresponding to employee_type. If true, return the data of all current + departing employees corresponding to employee_no/employee_id; if false, only return the data of the current or most recent employee corresponding to employee_no/employee_id
**Example value**: true
### Request body
Parameter | Type | Required | Description
---|---|---|---
user_ids | string\[\] | Yes | employee_no or employee_id list, corresponding to employee_type, not more than 50 in length
**Example value**: ["abd754f7"]
check_date_from | int | Yes | The starting working day of the query, in the format yyyyMMdd.
**Example value**: 20190817
check_date_to | int | Yes | The closing working day of the query, in the format yyyyMMdd.
**Example value**: 20190820
need_overtime_result | boolean | No | Whether you need the overtime shift clock in result; when need_overtime_result = true, the overtime shift will be returned. The overtime shift is marked by task_shift_type = 1, and there will be shared record_id when the overtime shift is connected to the normal shift. For example: 9-18 is the normal shift, 18-19 is the overtime shift, and the clock in result records two segments, 9-18, 18-19 and the two segments record_id the same (check_in_record_id and check_out_record_id are the same). Non-connected overtime shifts are returned in normal segments. When need_overtime_result = false, only the normal shift is returned and task_shift_type = 0.
**Example value**: true
### Request body example
```json
{
"user_ids": [
"abd754f7"
],
"check_date_from": 20190817,
"check_date_to": 20190820,
"need_overtime_result": true
}
```
## Response
### Response body
Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
user_task_results | user_task\[\] | Attendance tasks list
result_id | string | Attendance record ID
user_id | string | User ID, corresponding employee_type
employee_name | string | User name
day | int | Date in yyyyMMdd format
group_id | string | Attendance group ID (special note: 1 means not joining the attendance group), which can be used for [Query the attendance group by ID](/ssl: ttdoc/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/group/get)
shift_id | string | Shift ID (special note: 9 represents the default shift), which can be used for [query shift by ID](/ssl: ttdoc/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/shift/get)
records | task_result\[\] | User attendance records
check_in_record_id | string | Clock-in record ID
check_in_record | user_flow | Clock-in record
user_id | string | User ID, corresponding employee_type
creator_id | string | Record creator ID, corresponding to employee_type
location_name | string | Attendance location name information
check_time | string | Attendance time, with the timestamp accurate to seconds
comment | string | Attendance note
record_id | string | Record ID of the clock in attendance (this parameter is invalid when importing)
ssid | string | SSID of attendance Wi-Fi
bssid | string | MAC address of attendance Wi-Fi
is_field | boolean | Whether it is offsite attendance
is_wifi | boolean | Whether Wi-Fi is used for attendance
type | int | Record generation method
**Optional values are**:
- 0：User attendance
- 1：Administrator modification
- 2：User correction
- 3：Automatically generated by the system
- 4：Clock-out is not required
- 5：Attendance machine
- 6：Express attendance
- 7：Imports to attendance open platform
photo_urls | string\[\] | Attendance image list
device_id | string | Clock in device ID (only Mini Program clock in support, invalid when importing)
check_result | string | Results in clock. Currently only returns `PendingApproval`. If you want to get the punch result, please use the `check_in_result` parameter.
**Optional values are**:
- NoNeedCheck：No clock in
- SystemCheck：System clock in (deprecated)
- Normal：Normal
- Early：Leave early
- Late：Late
- SeriousLate：Seriously late
- Lack：Missing card
- Invalid：Invalid
- None：Stateless
- Todo：Not clocked in yet
external_id | string | Record ID of external clock in user import
idempotent_id | string | Unique idempotent key
check_out_record_id | string | Clock-out record ID
check_out_record | user_flow | Clock-out record
user_id | string | User ID, corresponding employee_type
creator_id | string | Record creator ID, corresponding to employee_type
location_name | string | Attendance location name information
check_time | string | Attendance time, with the timestamp accurate to seconds
comment | string | Attendance note
record_id | string | Record ID of the clock in attendance (this parameter is invalid when importing)
ssid | string | SSID of attendance Wi-Fi
bssid | string | MAC address of attendance Wi-Fi
is_field | boolean | Whether it is offsite attendance
is_wifi | boolean | Whether Wi-Fi is used for attendance
type | int | Record generation method
**Optional values are**:
- 0：User attendance
- 1：Administrator modification
- 2：User correction
- 3：Automatically generated by the system
- 4：Clock-out is not required
- 5：Attendance machine
- 6：Express attendance
- 7：Imports to attendance open platform
photo_urls | string\[\] | Attendance image list
device_id | string | Clock in device ID (only Mini Program clock in support, invalid when importing)
check_result | string | Results in clock. Currently only returns `PendingApproval`. If you want to get the punch result, please use the `check_out_result` parameter.
**Optional values are**:
- NoNeedCheck：No clock in
- SystemCheck：System clock in (deprecated)
- Normal：Normal
- Early：Leave early
- Late：Late
- SeriousLate：Seriously late
- Lack：Missing card
- Invalid：Invalid
- None：Stateless
- Todo：Not clocked in yet
external_id | string | Record ID of external clock in user import
idempotent_id | string | Unique idempotent key
check_in_result | string | Clock-in results
**Optional values are**:
- NoNeedCheck：No attendance is required
- SystemCheck：System attendance (deprecated)
- Normal：Available
- Early：Early out
- Late：Late in
- Lack：No record
- Todo：Not clocked in
check_out_result | string | Clock-out results
**Optional values are**:
- NoNeedCheck：No attendance is required
- SystemCheck：System attendance (deprecated)
- Normal：Available
- Early：Early out
- Late：Late in
- Lack：No record
- Todo：Not clocked in
check_in_result_supplement | string | Supplement of clock-in results
**Optional values are**:
- None：None
- ManagerModification：Administrator modification
- CardReplacement：Correction approved
- ShiftChange：Shift swap
- Travel：Business trip
- Leave：Leave
- GoOut：Offsite
- CardReplacementApplication：Applying correction
- FieldPunch：Offsite attendance
check_out_result_supplement | string | Supplement of clock-out results
**Optional values are**:
- None：None
- ManagerModification：Administrator modification
- CardReplacement：Correction approved
- ShiftChange：Shift swap
- Travel：Business trip
- Leave：Leave
- GoOut：Offsite
- CardReplacementApplication：Applying correction
- FieldPunch：Offsite attendance
check_in_shift_time | string | Work clock in seconds timestamp
check_out_shift_time | string | Off clock in seconds timestamp
task_shift_type | int | Shift type, 0 normal, 1 overtime shift
invalid_user_ids | string\[\] | List of invalid user IDs, corresponding to employee_type
unauthorized_user_ids | string\[\] | No permissions User ID list, corresponding employee_type
### Response body example
```json
{
"code": 0,
"msg": "success",
"data": {
"user_task_results": [
{
"result_id": "6709359313699356941",
"user_id": "abd754f7",
"employee_name": "John",
"day": 20190819,
"group_id": "6737202939523236110",
"shift_id": "6753520403404030215",
"records": [
{
"check_in_record_id": "6709359313699356941",
"check_in_record": {
"user_id": "abd754f7",
"creator_id": "abd754f7",
"location_name": "Xixi Ba Fang City",
"check_time": "1611476284",
"comment": "Clock-in",
"record_id": "6709359313699356941",
"ssid": "b0:b8:67:5c:1d:72",
"bssid": "b0:b8:67:5c:1d:72",
"is_field": true,
"is_wifi": true,
"type": 7,
"photo_urls": [
"https://time.clockin.biz/manage/download/6840389754748502021"
],
"device_id": "（只支持小程序打卡，导入时无效）99e0609ee053448596502691a81428654d7ded64c7bd85acd982d26b3636c37d",
"check_result": "Invalid",
"external_id": "record_123",
"idempotent_id": "****_***"
},
"check_out_record_id": "6709359313699356942",
"check_out_record": {
"user_id": "abd754f7",
"creator_id": "abd754f7",
"location_name": "Xixi Ba Fang City",
"check_time": "1611476284",
"comment": "Clock-in",
"record_id": "6709359313699356941",
"ssid": "b0:b8:67:5c:1d:72",
"bssid": "b0:b8:67:5c:1d:72",
"is_field": true,
"is_wifi": true,
"type": 7,
"photo_urls": [
"https://time.clockin.biz/manage/download/6840389754748502021"
],
"device_id": "（只支持小程序打卡，导入时无效）99e0609ee053448596502691a81428654d7ded64c7bd85acd982d26b3636c37d",
"check_result": "Invalid",
"external_id": "record_123",
"idempotent_id": "****_***"
},
"check_in_result": "SystemCheck",
"check_out_result": "SystemCheck",
"check_in_result_supplement": "None",
"check_out_result_supplement": "None",
"check_in_shift_time": "1609722000",
"check_out_shift_time": "1609754400",
"task_shift_type": 0
}
]
}
],
"invalid_user_ids": [
"abd754f7"
],
"unauthorized_user_ids": [
"abd754f7"
]
}
}
```
### Error code
HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
400 | 1220001 | param is invalis | The imported parameter verification failed. Please check the imported parameter according to the specific returned information. For example, "employee_type invalid" means that the person type is abnormal. If it still cannot be solved, please contact [Technical Support](https://applink.feishu.cn/TLJpeNdW)
400 | 1220002 | tenant_id is empty | Please check if the tenant_access_token in imported parameter is correct
400 | 1220004 | param is invalis | Please refer to the actual error message returned to troubleshoot the problem. For example, "user_id is not exist or does not have permission" means that the user id passed in by imported parameter does not exist or does not have permission. If it still cannot be solved, please contact [Technical Support](https://applink.feishu.cn/TLJpeNdW)
400 | 1220005 | No scope | Please go to [Attendance Admin](https://oa.feishu.cn/attendance/manage/member/list) to check permission scope on data
500 | 1225000 | param is invalis | Please refer to the actual error message returned to troubleshoot the problem. For example, "internal server error" represents an internal service exception. If it still cannot be solved, please contact [technical support](https://applink.feishu.cn/TLJpeNdW)
500 | 1226500 | Error history code, no longer used | -
500 | 1227500 | param is invalis | Shift server error error code, please refer to the actual error message returned to troubleshoot the problem. For example, "[BatchGetLarkIDByOpenID] not found user larkID" means the corresponding lark uid was not found. If it still cannot be solved, please contact [technical support](https://applink.feishu.cn/TLJpeNdW)
400 | 1220600 | Generic error message | The general error message contains multiple messages, and detailed error messages and handling suggestions can be found in [Error Messages] (/ssl: ttdoc/uAjLw4CM/ukTMukTMukTM/reference/attachment-v1/attendance-development-guidelines).