> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get the Contacts permission scope

> Call this API to get the Contacts permission scope granted to an app, required before calling Contacts-related APIs.

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

## API call description

<Warning>
  The API described in this topic is a legacy Server API. For details about how to call it, see Legacy APIs vs. new APIs.
</Warning>

For Contacts-related APIs, the admin must first apply for the corresponding API permissions in the [DingTalk Developer Console](https://open-dev.dingtalk.io/#/index) 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](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](/open/development/obtain-orgapp-token). - For a third-party enterprise app, obtain it through the API for getting the access\_token of a third-party enterprise. |

### Request example

```curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
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#

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
        "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](/open/development/server-api-error-codes-1) document for solutions based on the error message.