Get the external contact list - DingTalk Help Center

Call this API to get the external contact list of an organization.

Request

Basic information
HTTP URL	https://oapi.dingtalk.io/topapi/extcontact/list
HTTP Method	POST
Supported app types	appType-Internal appappType-Third-party enterprise app
Required permissions	permission-qyapi_ext_read-Read permission for external contacts

Query parameter

Name	Type	Required	Example	Description
access_token	String	Yes	6d1bxxxx	The app credential used to call this API. - For an internal app, obtain it by calling the API for getting the access_token of an internal app. - For a third-party enterprise app, obtain it by calling the API for getting the access_token of a third-party enterprise.

Request body

Name	Type	Required	Example	Description
size	Number	No	20	Supports paginated queries. This parameter takes effect only when set together with the offset parameter. It indicates the page size, with a maximum of 100.
offset	Number	No	0	Supports paginated queries. This parameter takes effect only when set together with the size parameter. It indicates the offset, starting from 0.

Request example

curl -X POST "https://oapi.dingtalk.io/topapi/extcontact/list" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=b5039xxxx8bcc' \
-d 'offset=0' \
-d 'size=20'

Java

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/extcontact/list");
OapiExtcontactListRequest req = new OapiExtcontactListRequest();
req.setSize(20L);
req.setOffset(0L);
OapiExtcontactListResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());

Python

import dingtalk.api

req=dingtalk.api.OapiExtcontactListRequest("https://oapi.dingtalk.io/topapi/extcontact/list")

req.offset=0
req.size=20
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 OapiExtcontactListRequest;
$req->setOffset("0");
$req->setSize("20");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/extcontact/list");

IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/extcontact/list");
OapiExtcontactListRequest req = new OapiExtcontactListRequest();
req.Offset = 0L;
req.Size = 20L;
OapiExtcontactListResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

Name	Type	Example	Description
results	OpenExtContact[]		The query result.
title	String	Development Engineer	The job title.
share_dept_ids	Number[]	1,2,3	The list of shared department IDs.
label_ids	Number[]	1,2,3	The list of external contact tags.
remark	String	Alias content	The alias.
address	String	Address content	The address.
name	String	Zhang San	The name.
follower_user_id	String	6767531692	The userid of the owner.
state_code	String	86	The country code.
company_name	String	DingTalk	The company name.
share_user_ids	String[]	042059613752	The list of userids of employees with whom the contact is shared.
mobile	String	13088888888	The mobile phone number. Note This parameter is not returned for third-party enterprise apps.
userid	String	0123456789	The userid of the external contact.
email	String	1@1.com	The mail address.
errcode	Number	0	The return code.
errmsg	String	ok	The description of the return code.
request_id	String	439eqp31da45	The request ID.

Response body example

{
  "errcode": 0,
  "results": [
    {
      "address": "Beijing",
      "company_name": "DingTalk",
      "email": "zhang@example.com",
      "follower_user_id": "manager4220",
      "label_ids": [
        1517
      ],
      "mobile": "1360054xxxx",
      "name": "Manager Wang",
      "remark": "Technical Lead",
      "share_dept_ids": [
        42536
      ],
      "share_user_ids": [
        "0423752"
      ],
      "state_code": "86",
      "title": "CFO",
      "userid": "01129774889"
    }
  ],
  "request_id": "439eqp31da45"
}

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.
40069	Invalid size	Adjust the page size.
40068	Invalid offset	Adjust the offset.
400001	System error	Try again later.

​Request

​Query parameter

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes