服务端 API/历史版本（不推荐）/通讯录/异步批量接口/批量新增用户
# 批量新增用户
该接口用于向通讯录中批量新增多个用户。
**注意事项**：调用该接口需要具有待添加用户所在部门的通讯录授权范围。
应用商店应用无权限调用此接口。
调用该接口需要申请 `更新通讯录` 以及 `以应用身份访问通讯录` 权限。
## 请求
基本 |
---|---
HTTP URL | https://open.larksuite.com/open-apis/contact/v2/user/batch_add
HTTP Method | POST
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 更新通讯录
以应用身份访问通讯录（历史版本）
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：获取与使用access_token](https://open.larksuite.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 请求体
参数 | 类型 | 必填 / 选填 | 说明
-- | -- | -- | --
users | array | 必填 | 所有待新增用户的集合。
∟name | string | 必填 | 用户名。
∟departments | array | 必填 | 待新增用户所属部门，目前仅支持单个用户所属单个部门。
需要应用的通讯录权限范围包含该部门。
∟user_id | string | 选填 | 用户企业内唯一标识。只能在创建用户时指定，不支持更新。
不指定时由平台自动生成。
自定义唯一标识不区分大小写，长度为 1 ~ 64 个字符。只能由数字、字母和“_”、“-”、“@”、“.”四种特殊字符组成，且第一个字符必须是数字或字母。
∟email | string | 选填 | 用户邮箱。
∟mobile | string | 必填 | 用户手机号。
∟mobile_visible | bool | 选填 | 手机号码可见性，true 为可见，false 为不可见，目前默认为 true。
不可见时，企业内其他员工将无法在客户端内查看该员工的手机号码。
∟city | string | 选填 | 用户所在城市。
∟country | string | 选填 | 用户所在国家。
字段值请参考国际标准化组织 [ISO 3166-1 标准](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) 中的二位代码。
∟gender | int | 选填 | 性别，1：男，2：女。
∟employee_type | int | 选填 | 员工类型，1：正式员工，2：实习生，3：外包，4：劳务，5：顾问。
∟join_time | int | 选填 | 入职时间，以秒为单位的 Unix 时间戳。
∟leader_user_id
∟leader_open_id | string | 选填 | 直属上级用户 ID，支持通过 user_id 或 open_id 进行设置。
请求同时传递两个字段时只使用 leader_user_id，忽略 leader_open_id。
∟employee_no | string | 选填 | 员工工号。
∟custom_attrs | array | 选填 | 自定义用户属性。
该字段仅当企业管理员在企业管理后台开启了“允许开放平台 API 调用”时有效。
传入的每个自定义用户属性需要包含平台生成的属性 ID 和要设置的属性对应类型的值。
当企业管理后台未开启“允许开放平台 API 调用”时，或者传入的属性 ID 不存在 / 非法时，会忽略该条属性的设置信息。
∟id | string | 必填 | 自定义属性 ID。
∟value | object | 必填 | 自定义属性值。
∟text | string | 选填 | 当自定义属性类型为 text 时，传入此字段，表示属性的文字值。
∟url | string | 选填 | 当自定义属性类型为 href 时，传入此字段，表示属性的 URL 值。
∟pc_url | string | 选填 | 当自定义属性类型为 href 时，传入此字段，表示属性的 PC 端 URL 值。
∟work_station | string | 选填 | 员工工位。
need_send_notification | bool | 选填 | 是否对本次新增的所有用户发送邀请通知，默认为 false，不发送通知。
该字段为 true 时， 用户添加成功后会向对应的邮箱或手机发送邀请通知。
### 请求体示例
```json
{
"users": [
{
"name": "张三",
"departments": [
"od-234355343342acdbef33"
],
"user_id": "id_zhangsan",
"email": "zhangsan@gmail.com",
"mobile": "+8613822235671",
"mobile_visible": false,
"city": "北京",
"country": "CN",
"gender": 1,
"employee_type": 1,
"join_time": 1534222800,
"leader_open_id": "ou_3454556545acdb12324",
"leader_user_id": "2ab56f23",
"employee_no": "323463",
"custom_attrs": [
{
"id": "C-6702376000044400907",
"value": {
"url": "http://www.feishu.cn/",
"pc_url": "http://www.feishu.cn/pc"
}
}
],
"work_station": "Poly, F6-123"
},
{
"name": "李四",
"departments": [
"od-234355343342acdbef33"
],
"user_id": "id_lisi",
"mobile": "+8613822235672",
"leader_user_id": "id_zhangsan"
}
],
"need_send_notification": false
}
```
## 响应
### 响应体
参数 | 说明
-- | --
code | 返回码，非 0 表示失败。
msg | 对返回码的文本描述。
data | -
∟task_id | 生成的异步任务 ID，参见 [查询批量任务执行状态](https://open.larksuite.com/document/ukTMukTMukTM/uUDOwUjL1gDM14SN4ATN) 接口。
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"task_id": "123456784b68a7c89abcdef092dc09ea"
}
}
```
### 错误码
具体可参考：[服务端错误码说明](https://open.larksuite.com/document/ukTMukTMukTM/ugjM14COyUjL4ITN)