Skip to main content
Call this API to add an external contact to your organization.

​
Request

Basic informationDetail
HTTP URLhttps://oapi.dingtalk.io/topapi/extcontact/create
HTTP MethodPOST
Supported app typeappType-Internal app
Required permissionspermission-qyapi_ext_write-Write permission for external contacts

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYes6d1bxxxxThe app credential used to call this API. Obtain it through the API for getting the access_token of an internal app.

​
Request body

NameTypeRequiredExampleDescription
contactOpenExtContactYesThe external contact information.
titleStringNoDevelopment EngineerThe job title.
label_idsNumber[]Yes[1561077317,1561077310]The tag list. Call the Get the list of external contact tags API to query tag information. Refer to How to customize tag groups for an organization to add custom tags. A maximum of 20 label IDs can be passed per call.
share_dept_idsNumber[]No[1,2,3]The IDs of departments to share with. Call the Get the list of sub-department IDs API to obtain them. A maximum of 20 department IDs can be passed per call.
addressStringNoBeijingThe address.
remarkStringNoManager WangThe alias.
follower_user_idStringYesmanager4220The user ID of the owner. Use the Query users by phone number API to obtain the user ID. A maximum of 20 user IDs can be passed per call.
nameStringYesZhang xxThe name of the external contact.
state_codeStringYes86The country code of the phone number.
company_nameStringNoDingTalkThe company name of the external contact.
share_user_idsString[]No[“023420013644”]The list of user IDs of employees to share with. Use the Query users by phone number API to obtain user IDs. A maximum of 20 user IDs can be passed per call.
mobileStringYes130xxxx8888The phone number of the external contact.

​
Request example

curl -X POST "https://oapi.dingtalk.io/topapi/extcontact/create" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=d5f0efxxxx9fa9e1' \
-d 'contact=null'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/extcontact/create");
OapiExtcontactCreateRequest req = new OapiExtcontactCreateRequest();
OapiExtcontactCreateRequest.OpenExtContact contact = new OapiExtcontactCreateRequest.OpenExtContact();
contact.setTitle("Development Engineer");
contact.setLabelIds(Arrays.asList(1561077317L,1561077310L));
contact.setShareDeptIds(Arrays.asList(1L,2L,3L));
contact.setFollowerUserId("manager4220");
contact.setName("Zhang xx");
contact.setStateCode("86");
contact.setCompanyName("DingTalk");
contact.setShareUserIds(Arrays.asList("023420013644"));
contact.setMobile("130xxxx8888");
req.setContact(contact);
OapiExtcontactCreateResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiExtcontactCreateRequest("https://oapi.dingtalk.io/topapi/extcontact/create")

req.contact=""
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 OapiExtcontactCreateRequest;
$contact = new OpenExtContact;
$contact->title="Development Engineer";
$contact->label_ids="[1,2,3]";
$contact->share_dept_ids="[1,2,3]";
$contact->address="Address content";
$contact->remark="Remark content";
$contact->follower_user_id="023420013645";
$contact->name="John";
$contact->state_code="86";
$contact->company_name="DingTalk";
$contact->share_user_ids="[\"023420013644\"]";
$contact->mobile="13088888888";
$req->setContact($contact);
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/extcontact/create");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/extcontact/create");
OapiExtcontactCreateRequest req = new OapiExtcontactCreateRequest();
OapiExtcontactCreateRequest.OpenExtContactDomain obj1 = new OapiExtcontactCreateRequest.OpenExtContactDomain();
obj1.Title = "Development Engineer";
obj1.LabelIds = new long[] { 1,2,3 };
obj1.ShareDeptIds = new long[] { 1,2,3 };
obj1.Address = "Address content";
obj1.Remark = "Remark content";
obj1.FollowerUserId = "023420013645";
obj1.Name = "John";
obj1.StateCode = "86";
obj1.CompanyName = "DingTalk";
obj1.ShareUserIds = ""023420013644"";
obj1.Mobile = "13088888888";
req.Contact_ = obj1;
OapiExtcontactCreateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
useridString123420013632The user ID of the external contact.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
request_idString6idz5ss49kkjThe request ID.

​
Response example

{
  "errcode":0,
  "userid":"011250026469774889",
  "request_id":"6idz5ss49kkj"
}

​
Error codes

If an error is returned when you call this API, see the Global error codes document for a solution based on the error message.
Error code (errcode)Error message (errmsg)Solution
33009Invalid tokenGrantTypeCheck whether the access_token is valid.
40036The parameter is empty.Check whether all required parameters above are provided.
60103Invalid phone numberCheck whether the phone number is correct.
60204An external contact tag is required.Provide a value for label_ids.
60205The external contact feature is not enabled.Enable the external contact feature after obtaining the user’s authorization letter.
43007Authorization requiredCheck whether the access_token has the required permissions.
60112Invalid user nameCheck whether the user name is correct.
22005The external contact already exists.Check whether the phone number of the external contact is correct.
-1The system is busy.Try again later.