Get the Contacts permission scope

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 URL	https://oapi.dingtalk.io/auth/scopes
HTTP Method	GET
Supported app types	appType-Internal app, appType-Third-party enterprise app
Permission requirements	permission-qyapi_base-The basic permission required to call enterprise APIs

Query parameters

Name	Type	Required	Example	Description
access_token	String	Yes	6ed1bxxx	The 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");

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

Name	Type	Example	Description
auth_org_scopes	AuthOrgScopes		Authorization information.
authed_user	String[]	[“user1”,“user”]	The list of employee user IDs authorized to retrieve Contacts information.
authed_dept	Number[]	[1,2,3]	The list of department IDs authorized to retrieve Contacts information.
auth_user_field	String[]	[“name”,“email”]	The enterprise user fields that can be retrieved with authorization.
errmsg	String	ok	The description of the return code.
errcode	Number	0	The 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.

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Docs & files

IM

API call description

Request

Query parameters

Request example

Response

Response body

Response body example

Error codes

​API call description

​Request

​Query parameters

​Request example

​Response

​Response body

​Response body example

​Error codes

API call description

Request

Query parameters

Request example

Response

Response body

Response body example

Error codes