Integrating DingTalk Organization Structure and Attendance via API

The article begins with a brief background on why DingTalk became popular during the pandemic and introduces the goal of quickly connecting corporate organization structures and attendance to DingTalk.

Step 1 – Obtain an access token : Log in to the DingTalk developer portal, retrieve appKey and appSecret , then request a token via a GET request to https://oapi.dingtalk.com/gettoken?appkey=YOUR_APPKEY&appsecret=YOUR_APPSECRET . The token is valid for 7200 seconds.

Step 2 – Sync departments : Use the token to call the department creation API ( POST https://oapi.dingtalk.com/department/create?access_token=ACCESS_TOKEN ) with a JSON body such as:

{
  "name": "helloworld",
  "parentid": "1",
  "order": null,
  "createDeptGroup": true,
  "deptHiding": false,
  "deptPerimits": null,
  "userPerimits": null,
  "outerDept": false,
  "outerPermitDepts": null,
  "outerPermitUsers": null,
  "soureIdentifier": null,
  "id": null
}

After creating a department, you can update or delete it using the corresponding /department/update and /department/delete endpoints.

Step 3 – Sync employees : Create users with a POST request to https://oapi.dingtalk.com/user/create?access_token=ACCESS_TOKEN . Example payload:

{
  "userid": "fuleli",
  "name": "福乐里",
  "department": [371046100],
  "position": "狗产品",
  "mobile": "15172391968",
  "tel": "xxxx-xxxxxxxx",
  "email": "[email protected]",
  "orgEmail": "[email protected]",
  "jobnumber": "xxx",
  "isHide": false,
  "isSenior": false,
  "extattr": {"爱好": "旅游", "年龄": "24"}
}

Update and delete users via /user/update and /user/delete . Note that the mobile number is the primary key; changing it requires deleting the old user and creating a new one.

Step 4 – Retrieve attendance : After employees are synced, configure DingTalk's clock‑in settings (e.g., location and Wi‑Fi). Then request attendance data with a POST to https://oapi.dingtalk.com/attendance/list?access_token=ACCESS_TOKEN using a body like:

{
  "workDateFrom": "2020-06-29 00:00:00",
  "workDateTo": "2020-07-03 00:00:00",
  "userIdList": ["manager962"],
  "offset": 0,
  "limit": 50
}

The response contains each employee's clock‑in records, which can be used for attendance statistics.

Common pitfalls :

Do not call DingTalk APIs too frequently; excessive calls trigger rate limiting and block further requests.

When updating an employee's phone number, the operation will fail because the phone number is the unique identifier; delete the old record and create a new one instead.

Finally, the article warns against attempting to fake location or use another person's device for clock‑in, as DingTalk monitors such behavior.