Skip to main content
Before calling Contacts-related APIs, you must add the Contacts API permission. Use this API to get the Contacts permission scope.

​
API call description

The API described in this topic is a legacy Server API. For details about how to call it, see Legacy APIs vs. new APIs.
For Contacts-related APIs, the admin must first apply for the corresponding API permissions in the DingTalk Developer Console and specify which Contacts scopes these APIs can access. As shown in the figure below, the access_token of the current app only has the Contacts permission for managing department A. Developers can call this API first to view the Contacts authorization scope of the app. When calling Contacts APIs, developers can only retrieve employee Contacts information within the authorized scope. Attempting to retrieve employee Contacts information outside the authorized scope returns the error The department or employee is not within the authorization scope.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/auth/scopes
HTTP MethodGET
Supported app typesappType-Internal app, appType-Third-party enterprise app
Permission requirementspermission-qyapi_base-The basic permission required to call enterprise APIs

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYes6ed1bxxxThe app credential used to call this API. - For an internal app, obtain it through the API for getting the access_token of an internal app. - For a third-party enterprise app, obtain it through the API for getting the access_token of a third-party enterprise.

​
Request example

curl -X GET "https://oapi.dingtalk.io/auth/scopes" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=2314cdxxxxbcd10713'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/auth/scopes");
OapiAuthScopesRequest req = new OapiAuthScopesRequest();
req.setHttpMethod("GET");
OapiAuthScopesResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiAuthScopesRequest("https://oapi.dingtalk.io/auth/scopes")
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_GET , DingTalkConstant::$FORMAT_JSON);
$req = new OapiAuthScopesRequest;
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/auth/scopes");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/auth/scopes");
OapiAuthScopesRequest req = new OapiAuthScopesRequest();
req.SetHttpMethod("GET");
OapiAuthScopesResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
auth_org_scopesAuthOrgScopesAuthorization information.
authed_userString[][“user1”,“user”]The list of employee user IDs authorized to retrieve Contacts information.
authed_deptNumber[][1,2,3]The list of department IDs authorized to retrieve Contacts information.
auth_user_fieldString[][“name”,“email”]The enterprise user fields that can be retrieved with authorization.
errmsgStringokThe description of the return code.
errcodeNumber0The return code.

​
Response body example

{
        "errcode":0,
        "condition_field":[],
        "auth_user_field":[
                "jobnumber",
                "isLeader",
                "name",
                "position",
                "isAdmin",
                "avatar",
                "department",
                "userid",
                "deviceId",
                "isHide"
        ],
        "auth_org_scopes":{
                "authed_user":[],
                "authed_dept":[
                        1
                ]
        },
        "errmsg":"ok"
}

​
Error codes

If an error occurs when calling this API, refer to the Global error codes document for solutions based on the error message.