Create an Attendance Group

Call this API to create an attendance group.

Request

Basic Information
HTTP URL	https://api.dingtalk.io/topapi/attendance/group/add
HTTP Method	POST
Supported App Types	appType-Internal app
Required Permissions	permission-qyapi_attendance_group_manage-Attendance group management permission

Query Parameters

Name	Type	Required	Example	Description
access_token	String	Yes	4c9d5xxxx	The App credential used to call this API. Get it by calling the Get the access_token of an Internal App API.

Request Body

Name	Type	Required	Example	Description
op_user_id	String	Yes	123dfd	The user ID of the operator.
top_group	TopGroupVo	Yes		The attendance group information.
owner	String	No	123dfdf	The owner of the attendance group.
enable_emp_select_class	Boolean	No	true	Specifies whether to allow employees to select a shift to clock in when no shift is scheduled. - true: Allow - false: Do not allow
corp_id	String	No	dingdfe	The CorpId of the organization. Get it on the Home page of the Developer Console.
skip_holidays	Boolean	No	true	Specifies whether to skip holidays. - true (default): Skip - false: Do not skip
special_days	String	No	`{"onDuty":{1400000:123,1400001:123},"offDuty":[1400000,1400001]}`	The special date configuration.
enable_outside_camera_check	Boolean	No	true	Specifies whether to require a photo for field clock-in. - true: On - false (default): Off
positions	`List<TopPositionVo>`	No		The attendance location settings.
address	String	No	No. 21, Jing’er Road, Biotech Industrial Park	The attendance address.
corp_id	String	No	123dfd	The CorpId of the organization. Get it on the Home page of the Developer Console.
latitude	String	No	36.687495	The latitude.
longitude	String	No	101.750329	The longitude.
accuracy	String	No	0	The accuracy. Note This field has no actual effect and does not affect accuracy. It was deprecated on March 7, 2022.
title	String	No	Qinghai-Tibet Plateau Natural History Museum	The attendance location title.
modify_member	Boolean	No	true	Specifies whether the attendance group member information is modified. - true: Modified - false: Not modified
type	String	Yes	TURN	The attendance group type: - FIXED: Fixed shift attendance group - TURN: Shift-based attendance group - NONE: Flexible working hours attendance group
enable_camera_check	Boolean	No	true	Specifies whether to enable photo clock-in. - true: On - false (default): Off
shift_vo_list	`List<TopShiftVo>`	No		The shift configuration.
id	Number	No	123	The shift ID. Get the id value by calling the Get Shift Summaries API.
enable_outside_check	Boolean	No	true	Specifies whether to allow field clock-in. - true (default): Allow - false: Do not allow
members	`List<TopMemberVo>`	Yes		The attendance group member settings.
role	String	Yes	Attendance	The role. Fixed value: Attendance.
corp_id	String	No	123dfd	The CorpId of the organization. Get it on the Home page of the Developer Console.
type	String	Yes	StaffMember	The type: - StaffMember: User type - DeptMember: Department type
user_id	String	Yes	1212jfkd	The ID: - User: userId - Department: deptId
name	String	Yes	Day Shift Attendance	The attendance group name.
id	Number	No	123	The attendance group ID.
enable_next_day	Boolean	No	false	Specifies whether the settings take effect the next day. - true: Yes - false: No
manager_list	String[]	No	[“userId1”,“userId2”]	The list of user IDs of the attendance group Sub Admins.
workday_class_list	Number[]	No	[0,12,12,12,12,12,0]	The weekly shift list. Note - Required for fixed shift attendance. 0 indicates a rest day. - From left to right, the values in the array represent the scheduling for each day from Sunday to Saturday.
default_class_id	Number	No	1234	The default shift ID. Note Required for fixed shift attendance. Get the id value by calling the Get Shift Summaries API.
offset	Number	No	500	The attendance range.
resource_permission_map	TopGroupManageRolePermissionVo	No		The permission scope of Sub Admins. - w: Manage - r: Read-only
schedule	String	No	w	Employee scheduling.
group_member	String	No	w	Configure attendance members.
group_type	String	No	r	Configure the attendance type.
check_time	String	No	w	Configure the attendance time.
check_position_type	String	No	r	Configure the clock-in method.
over_time_rule	String	No	r	Configure overtime rules.
camera_check	String	No	w	Configure photo clock-in rules.
out_side_check	String	No	w	Configure field clock-in.
wifis	`List<TopWifiVo>`	No		The Wi-Fi clock-in configuration.
mac_addr	String	No	C0:E0:D0:E0:C0:0F	The MAC address.
ssid	String	No	OFFICE-WiFi	The SSID of the Wi-Fi network.
corp_id	String	No	123dfd	The CorpId of the organization. Get it on the Home page of the Developer Console.
disable_check_without_schedule	Boolean	No	false	Specifies whether to prohibit employees from clocking in when no shift is scheduled. - true: Prohibit - false: Do not prohibit
freecheck_work_days	Number[]	No	[1,2,3,4,5,6,0]	The workdays of the flexible working hours attendance group. Note - 0 indicates a rest day. - From left to right, the values in the array represent the scheduling for each day from Sunday to Saturday.
freecheck_day_start_min_offset	Number	No	240	The offset in minutes between the attendance start time of the flexible working hours attendance group and 00:00 of the day. For example, 540 indicates 9:00.
disable_check_when_rest	Boolean	No	false	Specifies whether clock-in on rest days requires approval: - true: Required - false: Not required

Request Example

curl -X POST "https://api.dingtalk.io/topapi/attendance/group/add" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=e02c4xxxx5043' \
-d 'op_user_id=123dfd' \
-d 'top_group=null'

Java

DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/add");
OapiAttendanceGroupAddRequest req = new OapiAttendanceGroupAddRequest();
req.setOpUserId("dinge8xxxx");
TopGroupVo topGroupVo = new TopGroupVo();
topGroupVo.setOwner("user1");
topGroupVo.setEnableEmpSelectClass(true);
topGroupVo.setCorpId("dinge8xxxx");
topGroupVo.setSkipHolidays(true);
topGroupVo.setSpecialDays("{\"onDuty\":{1400000:123,1400001:123},\"offDuty\":[1400000,1400001]}");
topGroupVo.setEnableOutsideCameraCheck(true);
List<TopPositionVo> positionVos = new ArrayList<TopPositionVo>();
TopPositionVo topPositionVo = new TopPositionVo();
positionVos.add(topPositionVo);
topPositionVo.setAddress("No. 21, Jing'er Road, Biotech Industrial Park");
topPositionVo.setCorpId("dinge8xxxx");
topPositionVo.setLatitude("36.687495");
topPositionVo.setAccuracy("0");
topPositionVo.setTitle("Qinghai-Tibet Plateau Natural History Museum");
topPositionVo.setLongitude("101.750329");
topGroupVo.setPositions(positionVos);
topGroupVo.setModifyMember(true);
topGroupVo.setType("TURN");
topGroupVo.setEnableCameraCheck(true);
List<TopShiftVo> topShiftVos = new ArrayList<TopShiftVo>();
TopShiftVo topShiftVo = new TopShiftVo();
topShiftVos.add(topShiftVo);
topShiftVo.setId(123L);
topGroupVo.setShiftVoList(topShiftVos);
topGroupVo.setEnableOutsideCheck(true);
List<TopMemberVo> memberVos = new ArrayList<TopMemberVo>();
TopMemberVo topMemberVo = new TopMemberVo();
memberVos.add(topMemberVo);
topMemberVo.setRole("Attendance");
topMemberVo.setCorpId("dinge8xxxx");
topMemberVo.setType("StaffMember");
topMemberVo.setUserId("user1");
topGroupVo.setMembers(memberVos);
topGroupVo.setName("Day Shift Attendance");
topGroupVo.setEnableNextDay(false);
topGroupVo.setManagerList(Arrays.asList("userId1","userId2"));
topGroupVo.setDefaultClassId(1234L);
topGroupVo.setOffset(500L);
TopGroupManageRolePermissionVo groupManageRolePermissionVo = new TopGroupManageRolePermissionVo();
groupManageRolePermissionVo.setSchedule("w");
groupManageRolePermissionVo.setGroupMember("w");
groupManageRolePermissionVo.setGroupType("r");
groupManageRolePermissionVo.setCheckTime("w");
groupManageRolePermissionVo.setCheckPositionType("r");
groupManageRolePermissionVo.setOverTimeRule("r");
groupManageRolePermissionVo.setCameraCheck("w");
groupManageRolePermissionVo.setOutSideCheck("w");
topGroupVo.setResourcePermissionMap(groupManageRolePermissionVo);
List<TopWifiVo> topWifiVos = new ArrayList<TopWifiVo>();
TopWifiVo topWifiVo = new TopWifiVo();
topWifiVos.add(topWifiVo);
topWifiVo.setMacAddr("C0:E0:D0:E0:C0:0F");
topWifiVo.setSsid("OFFICE-WiFi");
topWifiVo.setCorpId("dinge8xxxx");
topGroupVo.setWifis(topWifiVos);
topGroupVo.setDisableCheckWithoutSchedule(false);
topGroupVo.setFreecheckDayStartMinOffset(240L);
topGroupVo.setDisableCheckWhenRest(true);
req.setTopGroup(topGroupVo);
OapiAttendanceGroupAddResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiAttendanceGroupAddRequest("https://api.dingtalk.io/topapi/attendance/group/add")

req.op_user_id="123dfd"
req.top_group=""
try:
  resp= req.getResponse(access_token)
  print(resp)
except Exception,e:
  print(e)

PHP

include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST, DingTalkConstant::$FORMAT_JSON);
$req = new OapiAttendanceGroupAddRequest;
$req->setOpUserId("123dfd");

$top_group = new TopGroupVo;
$top_group->name = "Day Shift Attendance";
$top_group->type = "TURN"; 
$top_group->enable_camera_check = "true";
$top_group->enable_outside_camera_check = "true";
$top_group->enable_outside_check = "true";
$top_group->enable_next_day = "false";
$top_group->modify_member = "true";
$top_group->offset = "500";
$top_group->default_class_id = "1234";
$top_group->manager_list = "[\"userId1\",\"userId2\"]";
$top_group->workday_class_list = "[12,12,12,12,12,0,0]";
$top_group->disable_check_without_schedule = "false";
$top_group->freecheck_work_days = "[1,2,3,4,5,6,0]";
$top_group->freecheck_day_start_min_offset = "240";
$top_group->disable_check_when_rest = "false";
$positions = new TopPositionVo;
$positions->title = "Qinghai-Tibet Plateau Natural History Museum";
$positions->address = "No. 21, Jing'er Road, Biotech Industrial Park";
$positions->latitude = "36.687495";
$positions->longitude = "101.750329";
$positions->accuracy = "0";
$top_group->positions = array($positions);
$members = new TopMemberVo;
$members->user_id = "1212jfkd";
$members->type = "StaffMember";
$members->role = "Attendance";
$top_group->members = array($members);
$wifis = new TopWifiVo;
$wifis->ssid = "OFFICE-WiFi";
$wifis->mac_addr = "C0:E0:D0:E0:C0:0F";
$top_group->wifis = array($wifis);
$shift_vo_list = new TopShiftVo;
$shift_vo_list->id = "123";
$top_group->shift_vo_list = array($shift_vo_list);
$resource_permission_map = new TopGroupManageRolePermissionVo;
$resource_permission_map->schedule = "w";
$resource_permission_map->group_member = "w";
$resource_permission_map->group_type = "r";
$resource_permission_map->check_time = "w";
$resource_permission_map->check_position_type = "r";
$resource_permission_map->over_time_rule = "r";
$resource_permission_map->camera_check = "w";
$resource_permission_map->out_side_check = "w";
$top_group->resource_permission_map = $resource_permission_map;
$req->setTopGroup($top_group);
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/attendance/group/add");

IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/group/add");
OapiAttendanceGroupAddRequest req = new OapiAttendanceGroupAddRequest();
req.OpUserId = "123dfd";
OapiAttendanceGroupAddRequest.TopGroupVoDomain obj1 = new OapiAttendanceGroupAddRequest.TopGroupVoDomain();
obj1.Owner = "123dfdf";
obj1.EnableEmpSelectClass = true;
obj1.CorpId = "dingdfe";
obj1.SkipHolidays = true;
obj1.SpecialDays = "{\"onDuty\":{1400000:123,1400001:123},\"offDuty\":[1400000,1400001]}";
obj1.EnableOutsideCameraCheck = true;
List<OapiAttendanceGroupAddRequest.TopPositionVoDomain> list3 = new List<OapiAttendanceGroupAddRequest.TopPositionVoDomain>();
OapiAttendanceGroupAddRequest.TopPositionVoDomain obj4 = new OapiAttendanceGroupAddRequest.TopPositionVoDomain();
list3.Add(obj4);
obj4.Address = "No. 21, Jing'er Road, Biotech Industrial Park";
obj4.CorpId = "123dfd";
obj4.Latitude = "36.687495";
obj4.Accuracy = "0";
obj4.Title = "Qinghai-Tibet Plateau Natural History Museum";
obj4.Longitude = "101.750329";
obj1.Positions = list3;
obj1.ModifyMember = true;
obj1.Type = "TURN";
obj1.EnableCameraCheck = true;
List<OapiAttendanceGroupAddRequest.TopShiftVoDomain> list6 = new List<OapiAttendanceGroupAddRequest.TopShiftVoDomain>();
OapiAttendanceGroupAddRequest.TopShiftVoDomain obj7 = new OapiAttendanceGroupAddRequest.TopShiftVoDomain();
list6.Add(obj7);
obj7.Id = 123L;
obj1.ShiftVoList = list6;
obj1.EnableOutsideCheck = true;
List<OapiAttendanceGroupAddRequest.TopMemberVoDomain> list9 = new List<OapiAttendanceGroupAddRequest.TopMemberVoDomain>();
OapiAttendanceGroupAddRequest.TopMemberVoDomain obj10 = new OapiAttendanceGroupAddRequest.TopMemberVoDomain();
list9.Add(obj10);
obj10.Role = "Attendance";
obj10.CorpId = "123dfd";
obj10.Type = "StaffMember";
obj10.UserId = "1212jfkd";
obj1.Members = list9;
obj1.Name = "Day Shift Attendance";
obj1.EnableNextDay = false;
obj1.ManagerList = "\"userId1\",\"userId2\"";
obj1.DefaultClassId = 1234L;
obj1.Offset = 500L;
OapiAttendanceGroupAddRequest.TopGroupManageRolePermissionVoDomain obj11 = new OapiAttendanceGroupAddRequest.TopGroupManageRolePermissionVoDomain();
obj11.Schedule = "w";
obj11.GroupMember = "w";
obj11.GroupType = "r";
obj11.CheckTime = "w";
obj11.CheckPositionType = "r";
obj11.OverTimeRule = "r";
obj11.CameraCheck = "w";
obj11.OutSideCheck = "w";
obj1.ResourcePermissionMap = obj11;
List<OapiAttendanceGroupAddRequest.TopWifiVoDomain> list13 = new List<OapiAttendanceGroupAddRequest.TopWifiVoDomain>();
OapiAttendanceGroupAddRequest.TopWifiVoDomain obj14 = new OapiAttendanceGroupAddRequest.TopWifiVoDomain();
list13.Add(obj14);
obj14.MacAddr = "C0:E0:D0:E0:C0:0F";
obj14.Ssid = "OFFICE-WiFi";
obj14.CorpId = "123dfd";
obj1.Wifis = list13;
obj1.DisableCheckWithoutSchedule = false;
obj1.FreecheckDayStartMinOffset = 240L;
obj1.DisableCheckWhenRest = false;
req.TopGroup_ = obj1;
OapiAttendanceGroupAddResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response Body

Name	Type	Example	Description
result	TopGroupVo		The call result.
name	String	Day Shift Attendance	The attendance group name.
id	Number	712070073	The attendance group ID.
success	Boolean	true	Indicates whether the call succeeded. - true: Success - false: Failed
errcode	Number	0	The return code.
errmsg	String	System error	The description of the return code.
request_id	String	6pcx0i2ujtt9	The request ID.

Response Body Example

{
  "result":{
    "name":"Day Shift Attendance",
    "id":712070073
  },
  "errcode":0,
  "success":true,
  "errmsg":"ok",
  "request_id":"6pcx0i2ujtt9"
}

Error Codes

If the call returns an error, find a solution in the Global Error Codes document based on the error message.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Attendance

Docs & files

IM

Request

Query Parameters

Request Body

Request Example

Response

Response Body

Response Body Example

Error Codes

​Request

​Query Parameters

​Request Body

​Request Example

​Response

​Response Body

​Response Body Example

​Error Codes

Request

Query Parameters

Request Body

Request Example

Response

Response Body

Response Body Example

Error Codes