> ## 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. # Add an external contact > Call this API to add an external contact to the enterprise Contacts, passing contact details in the request and receiving the identifier of the new external contact in the response. Call this API to add an external contact to your organization. ## Request | **Basic information** | Detail | | --------------------- | ---------------------------------------------------------------------------------------------------- | | HTTP URL | [https://api.dingtalk.io/topapi/extcontact/create](https://api.dingtalk.io/topapi/extcontact/create) | | HTTP Method | POST | | Supported app type | appType-Internal app | | Required permissions | permission-qyapi\_ext\_write-Write permission for external contacts | ### Query parameters | Name | Type | Required | Example | Description | | ------------- | ------ | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | access\_token | String | Yes | 6d1bxxxx | The app credential used to call this API. Obtain it through the API for getting the [access\_token of an internal app](/open/development/obtain-orgapp-token). | ### Request body | Name | Type | Required | Example | Description | | ------------------ | -------------- | -------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contact | OpenExtContact | Yes | | The external contact information. | | title | String | No | Development Engineer | The job title. | | label\_ids | Number\[] | Yes | \[1561077317,1561077310] | The tag list. Call the [Get the list of external contact tags](/open/development/obtains-a-list-of-external-contact-tags) API to query tag information. Refer to [How to customize tag groups for an organization](https://tms.dingtalk.io/markets/dingtalk/biaoqianzu) to add custom tags. A maximum of 20 label IDs can be passed per call. | | share\_dept\_ids | Number\[] | No | \[1,2,3] | The IDs of departments to share with. Call the [Get the list of sub-department IDs](/open/development/obtain-the-list-of-sub-department-ids) API to obtain them. A maximum of 20 department IDs can be passed per call. | | address | String | No | Beijing | The address. | | remark | String | No | Manager Wang | The alias. | | follower\_user\_id | String | Yes | manager4220 | The user ID of the owner. Use the [Query users by phone number](/open/development/query-users-by-phone-number) API to obtain the user ID. A maximum of 20 user IDs can be passed per call. | | name | String | Yes | Zhang xx | The name of the external contact. | | state\_code | String | Yes | 86 | The country code of the phone number. | | company\_name | String | No | DingTalk | The company name of the external contact. | | share\_user\_ids | String\[] | No | \["023420013644"] | The list of user IDs of employees to share with. Use the [Query users by phone number](/open/development/query-users-by-phone-number) API to obtain user IDs. A maximum of 20 user IDs can be passed per call. | | mobile | String | Yes | 130xxxx8888 | The phone number of the external contact. | ### Request example ```curl theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.dingtalk.io/topapi/extcontact/create" \ -H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \ -d 'access_token=d5f0efxxxx9fa9e1' \ -d 'contact=null' ``` Java ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} DingTalkClient client = new DefaultDingTalkClient("https://api.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 ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import dingtalk.api req=dingtalk.api.OapiExtcontactCreateRequest("https://api.dingtalk.io/topapi/extcontact/create") req.contact="" 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 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://api.dingtalk.io/topapi/extcontact/create"); ``` C# ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} IDingTalkClient client = new DefaultDingTalkClient("https://api.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 | Name | Type | Example | Description | | ----------- | ------ | ------------ | ------------------------------------ | | userid | String | 123420013632 | The user ID of the external contact. | | errcode | Number | 0 | The return code. | | errmsg | String | ok | The description of the return code. | | request\_id | String | 6idz5ss49kkj | The request ID. | ### Response example ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "errcode":0, "userid":"011250026469774889", "request_id":"6idz5ss49kkj" } ``` ### Error codes If an error is returned when you call this API, see the [Global error codes](/open/development/server-api-error-codes-1) document for a solution based on the error message. | Error code (errcode) | Error message (errmsg) | Solution | | -------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------ | | 33009 | Invalid tokenGrantType | Check whether the access\_token is valid. | | 40036 | The parameter is empty. | Check whether all required parameters above are provided. | | 60103 | Invalid phone number | Check whether the phone number is correct. | | 60204 | An external contact tag is required. | Provide a value for label\_ids. | | 60205 | The external contact feature is not enabled. | Enable the external contact feature after obtaining the user's authorization letter. | | 43007 | Authorization required | Check whether the access\_token has the required permissions. | | 60112 | Invalid user name | Check whether the user name is correct. | | 22005 | The external contact already exists. | Check whether the phone number of the external contact is correct. | | -1 | The system is busy. | Try again later. |