Create a Shift

Call this API to create a DingTalk attendance shift.

Request

Basic Information
HTTP URL	https://api.dingtalk.io/topapi/attendance/shift/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	6d1bxxxx	The app credential used to call this API. Obtain 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	user01	The userId of the operator.
shift	TopAtClassVo	Yes		The shift.
owner	String	No	user01	The shift owner.
class_group_name	String	No	def	The shift group name.
corp_id	String	No	ding23	The organization ID (corpId). Find it in the Developer Console. CorpId
name	String	Yes	Day shift	The shift name.
id	Number	No	124	The shift ID. Obtain it by calling the Get shift summaries API. Note: Leave id empty to create a shift. Specify id to modify an existing shift.
sections	TopAtSectionVo[]	Yes		The check-in sections.
times	TopAtTimeVo[]	Yes		The clock-in information.
check_type	String	Yes	OnDuty	The clock-in type: - OnDuty: Clock in - OffDuty: Clock out
across	Number	Yes	0	Whether the time spans to the next day: - 0: Same day - 1: Next day
end_min	Number	No	-1	The latest allowed clock-in time, in minutes. -1 indicates no limit.
check_time	Date	Yes	2020-12-02 09:00:00	The clock-in time.
free_check	Boolean	No	false	Whether clock-in is exempt: - false: Clock-in required - true: Clock-in exempt
begin_min	Number	No	30	The earliest allowed advance clock-in time, in minutes.
setting	TopAtClassSettingVo	No		The settings.
rest_begin_time	TopAtTimeVo	No		The break start.
check_type	String	No	OnDuty	The break type: - OnDuty: Break start - OffDuty: Break end
check_time	Date	No	2020-12-02 09:00:00	The break clock-in time.
free_check	Boolean	No	false	Whether clock-in is exempt: - true: Clock-in exempt - false: Clock-in required
across	Number	No	0	Whether the time spans to the next day. Spanning means the break falls on the next day: - 0: Same day - 1: Next day
class_id	Number	No	221	The shift ID. Obtain it by calling the Get shift summaries API.
is_flexible	Boolean	No	false	Whether the shift is flexible: - true: Flexible - false: Not flexible
corp_id	String	No	ding121	The organization ID (corpId). Find it in the Developer Console. CorpId
is_deleted	String	No	N	Whether the shift is deleted: - N: Yes - Y: No
rest_end_time	TopAtTimeVo	No		The break end.
check_type	String	No	OffDuty	The break type: - OnDuty: Break start - OffDuty: Break end
check_time	Date	No	2020-12-02 09:00:00	The break time.
free_check	Boolean	No	false	Whether clock-in is exempt: - false: Clock-in required - true: Clock-in exempt
across	Number	No	1	Whether the time spans to the next day. Spanning means the break falls on the next day: - 0: Same day - 1: Next day
serious_late_minutes	Number	No	31	The duration that counts as a serious late arrival or early leave, in minutes.
absenteeism_late_minutes	Number	No	60	The duration of a late arrival or early leave that counts as absenteeism, in minutes. Note This value must be greater than the serious late arrival duration.
extras	Json	No	`{"cause":"{\"type\":\"approve\",\"relatedId\":\"43494469-21a6-4111-953b-7810a709f27f\"}"}`	The extension field for shift settings. Not required for non-temporary shifts.
tags	String	No	temp:schedule:isv	The shift tags. Not required for non-temporary shifts.

Request Example

curl -X POST "https://api.dingtalk.io/topapi/attendance/shift/add" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=39cbcxxxx9058' \
-d 'op_user_id=abc' \
-d 'shift=null'

Java

DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/shift/add");
OapiAttendanceShiftAddRequest request = new OapiAttendanceShiftAddRequest();
TopAtClassVo topAtClassVo = new TopAtClassVo();
topAtClassVo.setOwner("user456");
topAtClassVo.setClassGroupName("Test shift group");
topAtClassVo.setCorpId("dinge8a56572xxxx");
topAtClassVo.setName("A1");
List<TopAtSectionVo> sectionVos = new ArrayList<>();
TopAtSectionVo sectionVo = new TopAtSectionVo();
List<TopAtTimeVo> timeVos = new ArrayList<>();
TopAtTimeVo timeVo = new TopAtTimeVo();
timeVo.setAcross(0L);
timeVo.setBeginMin(0L);
timeVo.setCheckTime(StringUtils.parseDateTime("2020-12-02 09:00:00"));
timeVo.setCheckType("OnDuty");
timeVo.setEndMin(-1L);
timeVo.setFreeCheck(false);
TopAtTimeVo timeVo1 = new TopAtTimeVo();
timeVo1.setAcross(0L);
timeVo1.setEndMin(0L);
timeVo1.setCheckTime(StringUtils.parseDateTime("2020-12-02 18:00:00"));
timeVo1.setCheckType("OffDuty");
timeVo1.setEndMin(-1L);
timeVo1.setFreeCheck(false);
timeVos.add(timeVo);
timeVos.add(timeVo1);
sectionVo.setTimes(timeVos);
sectionVos.add(sectionVo);
topAtClassVo.setSections(sectionVos);
TopAtClassSettingVo settingVo = new TopAtClassSettingVo();
topAtClassVo.setSetting(settingVo);
TopAtTimeVo restBeginTime = new TopAtTimeVo();
settingVo.setRestBeginTime(restBeginTime);
restBeginTime.setFreeCheck(false);
restBeginTime.setAcross(1L);
restBeginTime.setCheckType("OnDuty");
restBeginTime.setFreeCheck(false);
restBeginTime.setCheckTime(StringUtils.parseDateTime("2020-12-02 12:00:00"));
TopAtTimeVo restEndTime = new TopAtTimeVo();
settingVo.setRestEndTime(restEndTime);
restEndTime.setAcross(1L);
restEndTime.setCheckType("OffDuty");
restEndTime.setFreeCheck(false);
restEndTime.setCheckTime(StringUtils.parseDateTime("2020-12-02 13:00:00"));
settingVo.setCorpId("dinge8a56572xxxx");
settingVo.setIsDeleted("N");
settingVo.setAbsenteeismLateMinutes(60L);
settingVo.setIsFlexible(false);
settingVo.setSeriousLateMinutes(30L);
request.setOpUserId("user456");
request.setShift(topAtClassVo);
OapiAttendanceShiftAddResponse response = client.execute(request, access_token);
System.out.println(response.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiAttendanceShiftAddRequest("https://api.dingtalk.io/topapi/attendance/shift/add")

req.op_user_id="abc"
req.shift=""
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 OapiAttendanceShiftAddRequest;
$req->setOpUserId("abc");
$shift = new TopAtClassVo;
$shift->owner="abc";
$shift->class_group_name="def";
$shift->corp_id="ding23";
$shift->name="Day shift";
$sections = new TopAtSectionVo;
$times = new TopAtTimeVo;
$times->check_type="OnDuty";
$times->across="0";
$times->end_min="-1";
$times->check_time="2020-03-17 12:00:00";
$times->free_check="false";
$times->begin_min="30";
$sections->times = array($times);
$shift->sections = array($sections);
$setting = new TopAtClassSettingVo;
$rest_begin_time = new TopAtTimeVo;
$rest_begin_time->check_type="OnDuty";
$rest_begin_time->check_time="2020-03-17 12:00:00";
$rest_begin_time->free_check="false";
$rest_begin_time->across="0";
$setting->rest_begin_time = $rest_begin_time;
$setting->is_flexible="false";
$setting->corp_id="ding121";
$setting->is_deleted="N";
$rest_end_time = new TopAtTimeVo;
$rest_end_time->check_type="OffDuty";
$rest_end_time->check_time="2020-03-17 13:00:00";
$rest_end_time->free_check="false";
$rest_end_time->across="1";
$setting->rest_end_time = $rest_end_time;
$setting->serious_late_minutes="31";
$setting->absenteeism_late_minutes="60";
$shift->setting = $setting;
$req->setShift($shift);
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/attendance/shift/add");

IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/shift/add");
OapiAttendanceShiftAddRequest req = new OapiAttendanceShiftAddRequest();
req.OpUserId = "abc";
OapiAttendanceShiftAddRequest.TopAtClassVoDomain obj1 = new OapiAttendanceShiftAddRequest.TopAtClassVoDomain();
obj1.Owner = "abc";
obj1.ClassGroupName = "def";
obj1.CorpId = "ding23";
obj1.Name = "Day shift";
List<OapiAttendanceShiftAddRequest.TopAtSectionVoDomain> list3 = new List<OapiAttendanceShiftAddRequest.TopAtSectionVoDomain>();
OapiAttendanceShiftAddRequest.TopAtSectionVoDomain obj4 = new OapiAttendanceShiftAddRequest.TopAtSectionVoDomain();
list3.Add(obj4);
List<OapiAttendanceShiftAddRequest.TopAtTimeVoDomain> list6 = new List<OapiAttendanceShiftAddRequest.TopAtTimeVoDomain>();
OapiAttendanceShiftAddRequest.TopAtTimeVoDomain obj7 = new OapiAttendanceShiftAddRequest.TopAtTimeVoDomain();
list6.Add(obj7);
obj7.CheckType = "OnDuty";
obj7.Across = 0L;
obj7.EndMin = -1L;
obj7.CheckTime = DateTime.Parse("2020-03-17 12:00:00");
obj7.FreeCheck = false;
obj7.BeginMin = 30L;
obj4.Times= list6;
obj1.Sections= list3;
OapiAttendanceShiftAddRequest.TopAtClassSettingVoDomain obj8 = new OapiAttendanceShiftAddRequest.TopAtClassSettingVoDomain();
OapiAttendanceShiftAddRequest.TopAtTimeVoDomain obj9 = new OapiAttendanceShiftAddRequest.TopAtTimeVoDomain();
obj9.CheckType = "OnDuty";
obj9.CheckTime = DateTime.Parse("2020-03-17 12:00:00");
obj9.FreeCheck = false;
obj9.Across = 0L;
obj8.RestBeginTime= obj9;
obj8.IsFlexible = false;
obj8.CorpId = "ding121";
obj8.IsDeleted = "N";
OapiAttendanceShiftAddRequest.TopAtTimeVoDomain obj10 = new OapiAttendanceShiftAddRequest.TopAtTimeVoDomain();
obj10.CheckType = "OffDuty";
obj10.CheckTime = DateTime.Parse("2020-03-17 13:00:00");
obj10.FreeCheck = false;
obj10.Across = 1L;
obj8.RestEndTime= obj10;
obj8.SeriousLateMinutes = 31L;
obj8.AbsenteeismLateMinutes = 60L;
obj1.Setting= obj8;
req.Shift_ = obj1;
OapiAttendanceShiftAddResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response Body

Name	Type	Example	Description
result	TopAtClassVo		The shift information.
id	Number	706715401	The shift ID.
name	String	A1	The shift name.
errmsg	String	ok	The description of the return code.
errcode	Number	0	The return code.
success	Boolean	true	Whether the call succeeded: - true: Success - false: Failed
request_id	String	wp2oh4e4vlbu	The request ID.

Response Body Example

{
  "errcode": 0,
  "errmsg":"ok",
  "result": {
    "id": 706715401,
    "name": "A1"
  },
  "success": true,
  "request_id": "wp2oh4e4vlbu"
}

Error Codes

If the API 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