> ## 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 list of external contact tags

> Call this API to get the list of external contact tags of an organization, such as customer tags, used to classify and manage external contacts.

Call this API to get the tags of external contacts in your organization. Use this API to retrieve the list of external contact tags. For example, if an external contact is a customer of the company, the tag may be "Customer".

## Request

| **Basic information** |                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| HTTP URL              | [https://api.dingtalk.io/topapi/extcontact/listlabelgroups](https://api.dingtalk.io/topapi/extcontact/listlabelgroups) |
| HTTP Method           | POST                                                                                                                   |
| Supported app types   | appType-Internal app appType-Third-party enterprise app                                                                |
| Required permissions  | permission-qyapi\_ext\_read-Read permission for external contacts of the organization                                  |

### Query parameter

| Name          | Type   | Required | Example  | Description                                                                                                                                                                                                                                                                                                      |
| ------------- | ------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| access\_token | String | Yes      | bE74xxxx | 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 body

| Name   | Type   | Required | Example | Description                                                                                                                                        |
| ------ | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| size   | Number | No       | 20      | Supports pagination. Takes effect only when set together with the offset parameter. This parameter indicates the page size, with a maximum of 100. |
| offset | Number | No       | 0       | Supports pagination. Takes effect only when set together with the size parameter. This parameter indicates the offset, which starts from 0.        |

### Request example

```curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.dingtalk.io/topapi/extcontact/listlabelgroups" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=e6eaxxxxa401' \
-d 'offset=0' \
-d 'size=20'
```

Java

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/extcontact/listlabelgroups");
OapiExtcontactListlabelgroupsRequest req = new OapiExtcontactListlabelgroupsRequest();
req.setSize(20L);
req.setOffset(0L);
OapiExtcontactListlabelgroupsResponse 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.OapiExtcontactListlabelgroupsRequest("https://api.dingtalk.io/topapi/extcontact/listlabelgroups")

req.size=20
req.offset=0
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_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiExtcontactListlabelgroupsRequest;
$req->setSize("20");
$req->setOffset("0");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/extcontact/listlabelgroups");
```

C#

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/extcontact/listlabelgroups");
OapiExtcontactListlabelgroupsRequest req = new OapiExtcontactListlabelgroupsRequest();
req.Size = 20L;
req.Offset = 0L;
OapiExtcontactListlabelgroupsResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
```

## Response

### Response body

| Name        | Type              | Example      | Description                 |
| ----------- | ----------------- | ------------ | --------------------------- |
| results     | OpenLabelGroup\[] |              | The query results.          |
| name        | String            | Type         | The name of the tag group.  |
| color       | Number            | -15220075    | The color of the tag group. |
| labels      | OpenLabel\[]      |              | The list of tags.           |
| name        | String            | Customer     | The name of the tag.        |
| id          | Number            | 1026002      | The tag ID.                 |
| errcode     | Number            | 0            | The return code.            |
| request\_id | String            | 8n3mksu5hqzy | The request ID.             |

### Response body example

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "errcode":0,
  "results":[
    {
      "color":-15220075,
      "name":"Type",
      "labels":[
        {
          "name":"Customer",
          "id":1561077310
        },
        {
          "name":"Channel partner",
          "id":1561077311
        },
        {
          "name":"Supplier",
          "id":1561077312
        },
        {
          "name":"Partner",
          "id":1561077313
        },
        {
          "name":"Interviewee",
          "id":1561077314
        },
        {
          "name":"Other type",
          "id":1561077315
        }
      ]
    },
    {
      "color":-11687445,
      "name":"Level",
      "labels":[
        {
          "name":"General",
          "id":1561077317
        },
        {
          "name":"Important",
          "id":1561077318
        },
        {
          "name":"Core",
          "id":1561077319
        }
      ]
    },
    {
      "color":-543394,
      "name":"Status",
      "labels":[
        {
          "name":"Potential",
          "id":1561077321
        },
        {
          "name":"Interested",
          "id":1561077322
        },
        {
          "name":"In negotiation",
          "id":1561077323
        },
        {
          "name":"Closed deal",
          "id":1561077324
        },
        {
          "name":"Lost",
          "id":1561077325
        }
                        ]
                },
                {
                        "color":-543394,
                        "name":"Recruitment status",
                        "labels":[
                                {
                                        "name":"To be invited",
                                        "id":1561077327
                                },
                                {
                                        "name":"To be interviewed",
                                        "id":1561077328
                                },
                                {
                                        "name":"First-round interview",
                                        "id":1561077329
                                },
                                {
                                        "name":"Second-round interview",
                                        "id":1561077330
                                },
                                {
                                        "name":"Onboarded",
                                        "id":1561077331
                                }
                        ]
                }
        ],
        "request_id":"51jof1jt5f4t"
}
```

### Error codes

If an error is returned when you call this API, find the solution in the [global error codes](/open/development/server-api-error-codes-1) document based on the error message.

| Error code (errcode) | Error message (errmsg) | Solution                                    |
| -------------------- | ---------------------- | ------------------------------------------- |
| 33009                | Invalid tokenGrantType | Check whether the access\_token is correct. |
| 400043               | Invalid orgId          | Check whether the access\_token is correct. |
| 41101                | Invalid size           | Check whether the page size is valid.       |
| 40068                | Invalid offset         | Adjust the offset.                          |
| -1                   | System busy            | Try again later.                            |