钉钉开发文档

外部联系人管理

更新时间: 2019-6-12

获取外部联系人标签列表

企业使用此接口可获取企业外部联系人标签列表,例如这个外部联系人是公司的客户,那么标签可能就是客户。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/extcontact/listlabelgroups?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
size Number 必须 20 分页大小,最大100
offset Number 必须 0 偏移位置

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/extcontact/listlabelgroups");
OapiExtcontactListlabelgroupsRequest request = new OapiExtcontactListlabelgroupsRequest();
request.setOffset(0L);
request.setSize(20L);
OapiExtcontactListlabelgroupsResponse response = client.execute(request, accessToken);

返回结果

{
    "results":[
        {
                "name":"类型",
                "color":-15220075,
                "labels":[
                    {
                            "name":"客户",
                            "id":1026002
                    }
                ]
        }
    ],
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
results 标签组列表
└ name 标签组名字
└ color 标签组颜色
└ labels 标签列表
└ name 标签名字
└ id 标签id

获取外部联系人列表

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/extcontact/list?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
size Number 必须 20 分页大小,最大100
offset Number 必须 0 偏移位置

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/extcontact/list");
OapiExtcontactListRequest request = new OapiExtcontactListRequest();
request.setOffset(0L);
request.setSize(20L);
OapiExtcontactListResponse response = client.execute(request, accessToken);

返回结果

{
    "results":[
        {
                "title":"开发工程师",
                "share_dept_ids":[]
                "label_ids":[1,2,3],
                "remark":"备注内容",
                "address":"地址内容",
                "name":"张三",
                "follower_user_id":"userid2",
                "state_code":"86",
                "company_name":"钉钉",
                "share_user_ids":["userid3"],
                "mobile":"1xxxxxxxxxx",
                "userid":"userid1"
        }
    ],
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
results 外部联系人列表
└ title 职位
└ share_dept_ids 共享部门ID列表
└ label_ids 标签
└ remark 备注
└ address 地址
└ name 姓名
└ follower_user_id 负责人UserID
└ state_code 国家码
└ company_name 公司名
└ share_user_ids 共享员工UserID列表
└ mobile 手机号
└ userid 外部联系人UserID

获取外部联系人详情

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/extcontact/get?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
user_id String 必须 manager1 用户id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/extcontact/get");
OapiExtcontactGetRequest request = new OapiExtcontactGetRequest();
request.setUserId("userId1");
OapiExtcontactGetResponse response = client.execute(request, token);

返回结果

{
    "result":
        {
                "title":"开发工程师",
                "share_dept_ids":[]
                "label_ids":[1,2,3],
                "remark":"备注内容",
                "address":"地址内容",
                "name":"张三",
                "follower_user_id":"userid2",
                "state_code":"86",
                "company_name":"钉钉",
                "share_user_ids":["userid3"],
                "mobile":"1xxxxxxxxxx",
                "userid":"userid1"
        },
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
result 外部联系人
└ title 职位
└ share_dept_ids 共享部门ID列表
└ label_ids 标签
└ remark 备注
└ address 地址
└ name 姓名
└ follower_user_id 负责人UserID
└ state_code 国家码
└ company_name 公司名
└ share_user_ids 共享员工UserID列表
└ mobile 手机号
└ userid 外部联系人UserID

添加外部联系人

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/extcontact/create?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
contact OpenExtContact 必须 外部联系人信息
└ title String 可选 开发工程师 职位
└ label_ids Number [] 必须 [1,2,3] 标签列表
└ share_dept_ids Number [] 可选 [1,2,3] 共享给的部门ID
└ address String 可选 地址内容 地址
└ remark String 可选 备注内容 备注
└ follower_user_id String 必须 023420013645 负责人userId
└ name String 必须 张三 名称
└ state_code String 必须 86 手机号国家码
└ company_name String 可选 钉钉 企业名
└ share_user_ids String[] 可选 ["023420013644"] 共享给的员工userId列表
└ mobile String 必须 13088888888 手机号

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/extcontact/create");
OapiExtcontactCreateRequest request = new OapiExtcontactCreateRequest();
OapiExtcontactCreateRequest.OpenExtContact openExtContact = new OapiExtcontactCreateRequest.OpenExtContact();
openExtContact.setTitle("Title");
openExtContact.setLabelIds(Arrays.asList(304413077L, 304413084L));
openExtContact.setShareDeptIds(Arrays.asList(64849382L, 59170032L));
openExtContact.setAddress("地址");
openExtContact.setRemark("备注");
openExtContact.setFollowerUserId("manager3861");
openExtContact.setName("姓名");
openExtContact.setStateCode("86");
openExtContact.setCompanyName("企业名称");
openExtContact.setShareUserIds(Arrays.asList("manager3861","042340888792"));
openExtContact.setMobile("1xxxxxxxxxx");
request.setContact(openExtContact);
OapiExtcontactCreateResponse response = client.execute(request, accessToken);

返回结果

{
    "userid":"userid1",
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 新外部联系人的userId

更新外部联系人

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/extcontact/update?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
contact OpenExtContact 必须 外部联系人信息
└ user_id String 必须 123420013632 该外部联系人的userId
└ title String 可选 开发工程师 职位
└ label_ids Number [] 必须 [1,2,3] 标签列表
└ share_dept_ids Number [] 可选 [1,2,3] 共享给的部门ID
└ address String 可选 地址内容 地址
└ remark String 可选 备注内容 备注
└ follower_user_id String 必须 023420013645 负责人userId
└ name String 必须 张三 名称
└ company_name String 可选 钉钉 企业名
└ share_user_ids String[] 可选 ["023420013644"] 共享给的员工userId列表

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/extcontact/update");
OapiExtcontactUpdateRequest request = new OapiExtcontactUpdateRequest();
OapiExtcontactUpdateRequest.OpenExtContact openExtContact = new OapiExtcontactUpdateRequest.OpenExtContact();
openExtContact.setUserId("userid1");
openExtContact.setTitle("Title1");
openExtContact.setLabelIds(Arrays.asList(304413077L));
openExtContact.setShareDeptIds(Arrays.asList(64849382L));
openExtContact.setAddress("地址1");
openExtContact.setRemark("备注1");
openExtContact.setFollowerUserId("manager3861");
openExtContact.setName("姓名1");
openExtContact.setCompanyName("企业名称1");
openExtContact.setShareUserIds(Arrays.asList("042340888792"));
request.setContact(openExtContact);
OapiExtcontactUpdateResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode":0,
    "errmsg":"ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

删除外部联系人

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/topapi/extcontact/delete?access_token=ACCESS_TOKEN
参数说明

名称 类型 是否必须 示例值 描述
user_id String 必须 manager1 用户id

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/topapi/extcontact/delete");
OapiExtcontactDeleteRequest request = new OapiExtcontactDeleteRequest();
request.setUserId("userId1");
OapiExtcontactDeleteResponse response = client.execute(request, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!