Get the list of external contact tags

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://oapi.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. - 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 -X POST "https://oapi.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

DingTalkClient client = new DefaultDingTalkClient("https://oapi.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

import dingtalk.api

req=dingtalk.api.OapiExtcontactListlabelgroupsRequest("https://oapi.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

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://oapi.dingtalk.io/topapi/extcontact/listlabelgroups");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.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

{
  "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 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.

​Request

​Query parameter

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes