API call walkthrough - DingTalk Help Center

This guide walks developers through the full process of calling DingTalk Open Platform APIs, from creating an app to a successful API call. It covers key steps, code examples, considerations, and debugging methods to help developers get started quickly and call APIs successfully.

This example is based on an internal app and demonstrates how to retrieve user details from Contacts by calling the API. The same approach applies to other app types.

Prerequisites

Basic concepts: Be familiar with the basic concepts of the DingTalk Open Platform and the documentation for each product module. See the basic concepts documentation for details.
API rate limits: Be familiar with the API rate limits. See the API call frequency and rate limit documentation for details.
Developer permissions: Have Sub Admin and developer permissions in the Developer Backend. You can also sign in to DingTalk Developer to register and activate a new user.
Obtain the user UserId: Sign in to the DingTalk Admin Console and view the UserId under Contacts > User management. See the basic concepts documentation for details.

Step 1: Create a DingTalk app

Go to the Developer Backend and click App Development > DingTalk App > Create app.

Enter the app information and click Save.

Field	Required	Description
App name	Yes	Enter the app name. The minimum length is 2 characters.
App description	Yes	Briefly describe the products or services provided by the app. The minimum length is 4 characters.
App icon	No	Upload the app icon. The icon must be in JPG or PNG format, at least 240 px * 240 px, with a 1:1 aspect ratio, no rounded corners, and no larger than 2 MB.

Go to the app details page and view the app credential and basic information under Basic information > Credential and basic information.
Save the Client ID and Client Secret of the app for subsequent API calls.

Note

For details about how to obtain the Client ID and Client Secret, see the basic concepts documentation. Keep them safe after you obtain them to prevent leaks.

Step 2: Configure permissions

Find the required permission: According to the API documentation, calling the user details API requires the Read user information permission.
Add the permission: Go to the Developer Backend, locate the app you created, go to the app details page, search for Read user information under Manage permissions, and click Apply now.

Step 3: Obtain the Access Token

Before obtaining the Access Token, determine whether the API requires a standard permission or a sensitive permission. The two have different acquisition methods.

Standard-permission API

Call the API to obtain the Token

Open the Obtain the access token of an internal app API page and click the API Debug button on the right to open the Server-side debugging tool.
In the debugging tool, replace the values of appkey (replace with the Client ID you obtained earlier) and appSecret (replace with the Client Secret you obtained earlier), and click Debug.

Important

You must be signed in to use the server-side debugging console and must bind the corresponding app. You can also copy the code below and use a cURL command. Replace the values of appkey (with the Client ID you obtained earlier) and appSecret (with the Client Secret you obtained earlier), then send the request directly. Example:

curl -X POST 'https://api.dingtalk.io/v1.0/oauth2/accessToken' \
  -H 'Content-Type: application/json' \
  -d '{
    "appKey": "Replace with the Client ID you obtained earlier",
    "appSecret": "Replace with the Client Secret you obtained earlier"
  }'

Parse the response

After the call succeeds, an access token value is generated, as shown below:

{
  "accessToken" : "fw8ef8we8f76e6f7s8dxxxx", # Core credential
  "expireIn" : 7200 # Validity period (2 hours)
}

Cache and refresh

Cache the access_token in a database or memory and set up scheduled refreshes (10 minutes before expiration).
Avoid calling the Token API frequently, otherwise rate limits may be triggered.

Sensitive-permission API

To enable cross-organization data sharing and feature invocation, third-party apps must go through a strict authorization process. They need to obtain usage permission and user data access permission from the target organization through both organization-level and user-level authorization.

Apply for the API permission

Apply for the API permission according to the Use sensitive permissions documentation.

Integrate the authorization suite

After applying for the sensitive permission, integrate the authorization suite. When a user accepts the authorization in the prompt, an authCode is returned. Then call the Obtain user token API to exchange it for a user-level access_token.

Step 4: Call the user details API

Standard-permission API

To retrieve user details, call the Query user details API. You can use the DingTalk SDK or send an HTTP request directly. Choose the method that fits your needs.

Option 1: Use the DingTalk SDK (recommended)

Before using the DingTalk SDK, learn about the differences in the Server API, then download the corresponding SDK version. See the Server API differences documentation for details.

Install the SDK (Python example)
```
pip install dingtalk-sdk
```

Code example

# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiV2UserGetRequest("https://oapi.dingtalk.io/topapi/v2/user/get")

req.userid="zhangsan"  # Replace with the actual user ID
req.language="zh_CN"
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)

Option 2: Send an HTTP request directly

curl -i 'https://oapi.dingtalk.io/topapi/v2/user/get' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -d '{"userid":"Replace with the actual user ID","language":"zh_CN"}'

Successful response

If the response contains "errcode":"0" and "errmsg":"ok", the call succeeded.

{
        "errcode":"0",
        "result":{
                "extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}",
                "unionid":"z21HjQliSzpw0YWxxxxx",
                "boss":"true",
                "role_list":{
                        "group_name":"Position",
                        "name":"Director",
                        "id":"100"
                },
                "exclusive_account":false,
                "manager_userid":"manager240",
                "admin":"true",
                "remark":"Remark",
                "title":"Technical Director",
                "hired_date":"1597573616828",
                "userid":"zhangsan",
                "work_place":"Future Park",
                "dept_order_list":{
                        "dept_id":"2",
                        "order":"1"
                },
                "real_authed":"true",
                "dept_id_list":"[2,3,4]",
                "job_number":"4",
                "email":"test@xxx.com",
                "leader_in_dept":{
                        "leader":"true",
                        "dept_id":"2"
                },
                "mobile":"13800138000",
                "active":"true",
                "org_email":"test@xxx.com",
                "telephone":"010-86123456-2345",
                "avatar":"xxx",
                "hide_mobile":"false",
                "senior":"true",
                "name":"John",
                "union_emp_ext":{
                        "union_emp_map_list":{
                                "userid":"5000",
                                "corp_id":"dingxxx"
                        },
                        "userid":"500",
                        "corp_id":"dingxxx"
                },
                "state_code":"86"
        },
        "errmsg":"ok"
}

Error handling

Insufficient permissions: Check whether the Read user information permission has been requested.
User does not exist: Verify that the userid is valid and free of typos.
Token expired: Refresh the access_token and try again. Make sure the access_token is valid and free of typos.

Sensitive-permission API

After exchanging the authCode for a user-level access_token, call Retrieve user profile from Contacts to obtain the user’s name, unionId, and other information. If the API returns 200, the call succeeded. The response is as follows:

{
  "nick" : "zhangsan",
  "avatarUrl" : "https://xxx",
  "mobile" : "150xxxx9144",
  "openId" : "123",
  "unionId" : "z21HjQliSzpw0Yxxxx",
  "email" : "zhangsan@example.com",
  "stateCode" : "86"
}

​Prerequisites

​Step 1: Create a DingTalk app

​Note

​Step 2: Configure permissions

​Step 3: Obtain the Access Token

​Standard-permission API

​Call the API to obtain the Token

​Important

​Parse the response

​Cache and refresh

​Sensitive-permission API

​Apply for the API permission

​Integrate the authorization suite

​Step 4: Call the user details API

​Standard-permission API

​Option 1: Use the DingTalk SDK (recommended)

​Option 2: Send an HTTP request directly

​Successful response

​Error handling

​Sensitive-permission API

Prerequisites

Step 1: Create a DingTalk app

Note

Step 2: Configure permissions

Step 3: Obtain the Access Token

Standard-permission API

Call the API to obtain the Token

Important

Parse the response

Cache and refresh

Sensitive-permission API

Apply for the API permission

Integrate the authorization suite

Step 4: Call the user details API

Standard-permission API

Option 1: Use the DingTalk SDK (recommended)

Option 2: Send an HTTP request directly

Successful response

Error handling

Sensitive-permission API