创建用户

调用该接口向通讯录创建一个用户（该动作可以理解为员工入职）。成功创建用户后，系统会以短信或邮件的形式向用户发送邀请，用户在同意邀请后方可访问企业或团队。

注意事项

• 创建用户时，所操作的所有部门均需要在当前应用的通讯录权限范围内，才能成功创建。如果需要在根部门下创建用户，则应用必须有全员权限。关于通讯录权限范围的具体说明可参见权限范围资源介绍。
• 发送请求后获取到的响应数据受接口的字段权限要求影响，接口只返回有权限的数据，因此你在调用前需要为应用申请必要的接口权限和字段权限。如何申请 API 权限可参见申请 API 权限。

使用限制

• 未认证企业的人数上限为 100。
• 已认证企业的人数上限在不同飞书版本里不相同，具体参考版本对比。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/contact/v3/users
HTTP Method	POST
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	contact:contact 更新通讯录
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.base:readonly 获取用户基本信息 contact:user.department:readonly 获取用户组织架构信息 contact:user.dotted_line_leader_info.read 查看成员的虚线上级 ID contact:user.employee:readonly 获取用户受雇信息 contact:user.employee_number:read 查看成员工号 contact:user.gender:readonly 获取用户性别 contact:user.email:readonly 获取用户邮箱信息 contact:user.job_level:readonly 查询用户职级 contact:user.employee_id:readonly 获取用户 user ID contact:user.phone:readonly 获取用户手机号 contact:user.user_geo 查看成员数据驻留地 contact:user.job_family:readonly 查询用户所属的工作序列 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

查询参数

名称	类型	必填	描述
user_id_type	string	否	用户 ID 类型 示例值：open_id 可选值有： - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？ 默认值：open_id 当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_type	string	否	此次调用中的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。 示例值：open_department_id 可选值有： - department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。 - open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。 默认值：open_department_id
client_token	string	否	用于幂等判断是否为同一请求，避免重复创建。请参考参数示例值，传入自定义的 client_token。 默认值：空，表示不进行幂等判断 示例值：abcd-12345-e6f

请求体

名称	类型	必填	描述
user_id	string	否	自定义用户的 user_id。长度不能超过 64 字符。 user_id 是用户在当前租户内的唯一标识，自定义时请确保唯一性。 默认值：空，表示由系统随机生成一个 user_id。 示例值："3e3cf96b"
name	string	是	用户名。长度不能超过 255 字符。 示例值："张三" 数据校验规则： - 最小长度：1 字符
en_name	string	否	英文名。长度不能超过 255 字符。 默认值：空 示例值："San Zhang"
nickname	string	否	别名。长度不能超过 255 字符。 默认值：空 示例值："Alex Zhang"
email	string	否	邮箱。 注意： - 当设置非中国大陆的手机号时，必须同时设置邮箱。 - 在当前租户下，邮箱不可重复。 默认值：空 示例值："zhangsan@gmail.com"
mobile	string	是	手机号。 注意： - 在当前租户下，手机号不可重复。 - 未认证企业仅支持添加中国大陆手机号；通过飞书认证的企业允许添加海外手机号。 - 国际电话区号的前缀中，必须包含加号 +。 取值示例： - 中国大陆手机号：13011111111 或 +8613011111111 - 非中国大陆手机号：+41446681800 示例值："13011111111"
mobile_visible	boolean	否	手机号码是否对其他员工可见。 可选值有： - true：可见。 - false：不可见。不可见时，企业内的员工将无法查看该用户的手机号码。 默认值：true 示例值：false
gender	int	否	性别。 默认值：0 示例值：1 可选值有： - 0: 保密 - 1: 男 - 2: 女 - 3: 其他
avatar_key	string	否	头像的文件 Key。你可以通过上传图片接口，上传并获取头像文件 Key，上传时图片类型需要选择 用于设置头像 默认值：空 示例值："2500c7a9-5fff-4d9a-a2de-3d59614ae28g"
department_ids	string\[\]	是	用户所属部门的 ID 列表。 - 一个用户可属于多个部门，最多可设置 50 个部门。 - 部门 ID 类型与查询参数 department_id_type 保持一致。 - 你可以调用搜索部门接口，通过部门名称关键词获取对应的部门 ID。 示例值：["od-4e6ac4d14bcd5071a37a39de902c714111111"]
leader_user_id	string	否	用户的直接主管的用户 ID，ID 类型与查询参数 user_id_type 保持一致。用户 ID 获取方式可参见如何获取不同的用户 ID。 默认值：空 示例值："ou_7dab8a3d3cdcc9da365777c7ad535d62"
city	string	否	工作城市。字符长度上限为 100。 说明： - 你可以调用获取租户工作城市列表接口获取当前租户内已有的工作城市名称。 - 如果你传入的工作城市名称不存在，则系统会自动生成该工作城市。工作城市的枚举值数量上限为 10,000。 默认值：空 示例值："杭州"
country	string	否	国家或地区 Code 缩写。具体写入格式参考 国家/地区 Code 参照表。 默认值：空 示例值："CN"
work_station	string	否	工位。字符长度上限为 255。 默认值：空 示例值："北楼-H34"
join_time	int	否	入职时间。秒级时间戳格式，表示从 1970 年 1 月 1 日开始所经过的秒数。如果不传入该参数，则默认填充当前请求时的时间。创建用户传入 0 时，入职时间是1970-01-01。 示例值：2147483647
employee_no	string	否	工号。字符长度上限为 255。 注意：同一租户下，用户工号不能重复。 默认值：空 示例值："1"
employee_type	int	是	员工类型。 可选值有： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问 该参数支持读取自定义的员工类型的 int 值。你可通过获取人员类型接口获取到该租户的自定义员工类型的编号值（enum_value）。 示例值：1
orders	user_order\[\]	否	用户排序信息列表。该参数用于标记通讯录下组织架构的人员顺序，人员可能存在多个部门中，且有不同的排序。
└ department_id	string	否	排序信息对应的部门 ID。表示用户所在的、且需要排序的部门。 注意： - 部门 ID 类型与查询参数 department_id_type 保持一致。 - 该参数所传入的部门 ID 必须在用户所属的部门 ID 列表（department_ids 参数）内。 - 如果不传值，系统默认会将 department_ids 参数内的部门 ID，依次传入 order 的 department_id 参数。 示例值："od-4e6ac4d14bcd5071a37a39de902c7141"
└ user_order	int	否	用户在其直属部门内的排序。数值越大，排序越靠前。 注意：该参数为 int 类型，取值时不能超出 int 的最大值。 默认值：0 示例值：100
└ department_order	int	否	用户所属的多个部门之间的排序。数值越大，排序越靠前。 注意：该参数为 int 类型，取值时不能超出 int 的最大值。 默认值：0 示例值：100
└ is_primary_dept	boolean	否	标识是否为用户的唯一主部门，主部门为用户所属部门中排序第一的部门（department_order 最大）。 可选值有： - true：是 - false：否 默认值：如果当前的 department_id 是 department_ids 中传入的第一个数据，则默认值为 true，否则为 false。 示例值：true
custom_attrs	user_custom_attr\[\]	否	自定义字段。设置参数前建议你先了解自定义字段资源介绍。 默认值：空。如果没有设置自定义字段，则无需传入值。 注意事项：当企业管理员在管理后台配置了自定义字段，且开启了 允许开放平台 API 调用 功能后，该字段才会生效。
└ type	string	否	自定义字段类型。 可选值有： - TEXT：文本 - HREF：网页 - ENUMERATION：枚举 - PICTURE_ENUM：图片 - GENERIC_USER：用户 示例值："TEXT"
└ id	string	否	自定义字段 ID。你可以调用获取企业自定义用户字段接口获取自定义字段对应的字段 ID。 说明：如果设置了自定义字段类型参数（type），则该参数必填。 示例值："DemoId"
└ value	user_custom_attr_value	否	自定义字段取值。
└ text	string	否	- 自定义字段类型为 TEXT 时，该参数必填，用于定义字段值。 - 自定义字段类型为 HREF 时，该参数必填，用于定义网页标题。 长度不能超过 100 字符。 示例值："DemoText"
└ url	string	否	自定义字段类型为 HREF 时，该参数必填，用于定义默认 URL。例如，手机端跳转小程序，PC端跳转网页。 注意：请以 http:// 或 https:// 开头。 示例值："http://www.fs.cn"
└ pc_url	string	否	自定义字段类型为 HREF 时，该参数用于定义 PC 端 URL。 注意：请以 http:// 或 https:// 开头。 示例值："http://www.fs.cn"
└ option_id	string	否	自定义字段类型为 ENUMERATION 或 PICTURE_ENUM 时，该参数用于定义选项 ID。 你可以调用获取企业自定义用户字段接口获取自定义字段相应的选项 ID。 示例值："edcvfrtg"
└ generic_user	custom_attr_generic_user	否	自定义字段类型为 GENERIC_USER 时，该参数用于定义引用人员。
└ id	string	是	引用人员的用户 ID。 - ID 类型与查询参数 user_id_type 保持一致。 - 如何获取用户 ID 可参见如何获取不同的用户 ID。 示例值："9b2fabg5"
└ type	int	是	用户类型。 可选值有： 1：用户 说明：目前仅支持取值 1，表示用户。 示例值：1
enterprise_email	string	否	企业邮箱。 注意事项：企业管理员在管理后台启用飞书邮箱服务后，才会生效该参数。如果设置企业邮箱失败，请联系企业管理员确认是否在管理后台启用了相应的企业邮箱域名。 默认值：空 示例值："demo@mail.com"
job_title	string	否	职务名称。字符数量上限为 255。 - 你可以调用获取租户职务列表接口获取相应的职务名称。 - 如果传入的职务名称不存在，则系统会自动创建并使用该名称。职务枚举值数量上限为 10,000。 - 如果传入空格字符串，则意味着清空职务。 默认值：空 示例值："xxxxx"
geo	string	否	数据驻留地。 注意事项：需联系服务台技术支持开通使用。 默认值：空 示例值："cn"
job_level_id	string	否	职级 ID。你可以调用获取租户职级列表接口查询相应的职级 ID。 默认值：空 示例值："mga5oa8ayjlp9rb"
job_family_id	string	否	序列 ID。你可以调用获取租户序列列表接口查询相应的序列 ID。 默认值：空 示例值："mga5oa8ayjlp9rb"
subscription_ids	string\[\]	否	分配给用户的席位 ID 列表。 注意事项： - 该字段需要应用已开通 分配用户席位 权限。 - 如果你购买了席位，则创建用户时必须为用户分配席位 ID，否则用户将无法登录企业飞书。更多信息可参见管理员分配席位。 - 你可通过获取企业席位信息接口，获取到当前租户的可用席位 ID。 默认值：空 示例值：["23213213213123123"]
dotted_line_leader_user_ids	string\[\]	否	虚线上级的用户 ID 列表。 - ID 类型与查询参数 user_id_type 保持一致。 - 如何获取用户 ID 可参见如何获取不同的用户 ID。 默认值：空 示例值：["ou_7dab8a3d3cdcc9da365777c7ad535d62"]

请求体示例

{
    "user_id": "3e3cf96b",
    "name": "张三",
    "en_name": "San Zhang",
    "nickname": "Alex Zhang",
    "email": "zhangsan@gmail.com",
    "mobile": "13011111111",
    "mobile_visible": false,
    "gender": 1,
    "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
    "department_ids": [
        "od-4e6ac4d14bcd5071a37a39de902c714111111"
    ],
    "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
    "city": "杭州",
    "country": "CN",
    "work_station": "北楼-H34",
    "join_time": 2147483647,
    "employee_no": "1",
    "employee_type": 1,
    "orders": [
        {
            "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
            "user_order": 100,
            "department_order": 100,
            "is_primary_dept": true
        }
    ],
    "custom_attrs": [
        {
            "type": "TEXT",
            "id": "DemoId",
            "value": {
                "text": "DemoText",
                "url": "http://www.fs.cn",
                "pc_url": "http://www.fs.cn",
                "option_id": "edcvfrtg",
                "generic_user": {
                    "id": "9b2fabg5",
                    "type": 1
                }
            }
        }
    ],
    "enterprise_email": "demo@mail.com",
    "job_title": "xxxxx",
    "geo": "cn",
    "job_level_id": "mga5oa8ayjlp9rb",
    "job_family_id": "mga5oa8ayjlp9rb",
    "subscription_ids": [
        "23213213213123123"
    ],
    "dotted_line_leader_user_ids": [
        "ou_7dab8a3d3cdcc9da365777c7ad535d62"
    ]
}

Go 请求示例

import (
	"context"

	"github.com/larksuite/oapi-sdk-go/v3"
	"github.com/larksuite/oapi-sdk-go/v3/service/contact/v3"
)

func main() {
	// 创建 Client
	client := lark.NewClient("appID", "appSecret")

	// 创建请求对象
	req := larkcontact.NewCreateUserReqBuilder().
		UserIdType(`open_id`).
		User(larkcontact.NewUserBuilder().
			Name(`张三`).
			Mobile(`13011111111`).
			DepartmentIds([]string{`od-4e6ac4d14bcd5071a37a39de902c7141`}).
			EmployeeType(1).
			Build()).
		Build()

	// 发起请求
	resp, err := client.Contact.User.Create(context.Background(), req)
}

Java 请求示例

import com.lark.oapi.Client;
import com.lark.oapi.core.request.RequestOptions;
import com.lark.oapi.service.contact.v3.model.CreateUserReq;
import com.lark.oapi.service.contact.v3.model.CreateUserResp;
import com.lark.oapi.service.contact.v3.model.User;

public class Main {
    public static void main(String arg[]) throws Exception {
        // 构建client
        Client client = Client.newBuilder("appId", "appSecret").build();

        // 创建请求对象
        CreateUserReq req = CreateUserReq.newBuilder()
                .userIdType("open_id")
                .user(User.newBuilder()
                        .name("张三")
                        .mobile("13011111111")
                        .departmentIds(new String[]{"od-4e6ac4d14bcd5071a37a39de902c7141"})
                        .employeeType(1)
                        .build())
                .build();

        // 发起请求
        CreateUserResp resp = client.contact().user().create(req, RequestOptions.newBuilder().build());
    }
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ user	user	用户信息
└ union_id	string	用户的 union_id，是应用开发商发布的不同应用中同一用户的标识。不同用户 ID 的说明参见 用户相关的 ID 概念。
└ user_id	string	用户的 user_id，租户内用户的唯一标识。不同用户 ID 的说明参见 用户相关的 ID 概念。 字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
└ open_id	string	用户的 open_id，应用内用户的唯一标识。不同用户 ID 的说明参见 用户相关的 ID 概念。
└ name	string	用户名。 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ en_name	string	英文名。 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ nickname	string	别名。 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ email	string	邮箱。 字段权限要求： contact:user.email:readonly 获取用户邮箱信息
└ mobile	string	手机号。 字段权限要求： contact:user.phone:readonly 获取用户手机号
└ mobile_visible	boolean	手机号码是否可见。 可能值有： - true：可见。 - false：不可见。不可见时，企业内的员工将无法查看该用户的手机号码。
└ gender	int	性别。 可选值有： - 0: 保密 - 1: 男 - 2: 女 - 3: 其他 字段权限要求（满足任一）： contact:user.gender:readonly 获取用户性别 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ avatar_key	string	头像的文件 Key。
└ avatar	avatar_info	用户头像信息。 字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ avatar_72	string	72*72 像素头像链接。
└ avatar_240	string	240*240 像素头像链接。
└ avatar_640	string	640*640 像素头像链接。
└ avatar_origin	string	原始头像链接。
└ status	user_status	用户状态。通过 is_frozen、is_resigned、is_activated、is_exited 布尔值类型参数进行展示。 用户状态的转关逻辑可参见用户资源介绍。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ is_frozen	boolean	是否为暂停状态。 可能值有： - true：是 - false：否
└ is_resigned	boolean	是否为离职状态。 可能值有： - true：是 - false：否
└ is_activated	boolean	是否为激活状态。 可能值有： - true：是 - false：否
└ is_exited	boolean	是否为主动退出状态。主动退出一段时间后用户状态会自动转为已离职。 可能值有： - true：是 - false：否
└ is_unjoin	boolean	是否为未加入状态，需要用户自主确认才能加入企业或团队。 可能值有： - true：是 - false：否
└ department_ids	string\[\]	用户所属部门的 ID 列表，一个用户可属于多个部门。ID 值的类型与查询参数中的 department_id_type 一致。 字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ leader_user_id	string	用户的直接主管的用户ID。ID 值的类型与查询参数中的user_id_type 一致。 字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ city	string	工作城市。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ country	string	国家或地区 Code 缩写，具体格式参考 国家/地区 Code 参照表。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ work_station	string	工位。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ join_time	int	入职时间。秒级时间戳格式，表示从 1970 年 1 月 1 日开始所经过的秒数。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ is_tenant_manager	boolean	用户是否为租户超级管理员。 可能值有： - true：是 - false：否 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ employee_no	string	工号。 字段权限要求（满足任一）： contact:user.employee_number:read 查看成员工号 contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ employee_type	int	员工类型。 可能值有： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问 同时支持自定义员工类型的 int 值。你可通过获取人员类型接口获取到当前租户内自定义员工类型的名称。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ orders	user_order\[\]	用户排序信息。用于标记通讯录下组织架构的人员顺序，人员可能存在多个部门中，且有不同的排序。 字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ department_id	string	排序信息对应的部门 ID，表示用户所在的、且需要排序的部门。ID 值的类型与查询参数中的 department_id_type 一致。
└ user_order	int	用户在其直属部门内的排序。数值越大，排序越靠前。
└ department_order	int	用户所属的多个部门间的排序。数值越大，排序越靠前。
└ is_primary_dept	boolean	标识是否为用户的唯一主部门。主部门为用户所属部门中排序第一的部门(department_order 最大)。 可能值有： - true：是 - false：否
└ custom_attrs	user_custom_attr\[\]	自定义字段。 注意事项：当企业管理员在管理后台配置了自定义字段，且开启了 允许开放平台 API 调用 功能后，该字段才会生效。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ type	string	自定义字段类型。 可能值有： - TEXT：文本 - HREF：网页 - ENUMERATION：枚举 - PICTURE_ENUM：图片 - GENERIC_USER：用户
└ id	string	自定义字段 ID。
└ value	user_custom_attr_value	自定义字段取值。
└ text	string	- 字段类型为 TEXT 时，该参数返回定义的字段值。 - 字段类型为 HREF 时，该参数返回定义的网页标题。
└ url	string	字段类型为 HREF 时，该参数返回定义的默认 URL。
└ pc_url	string	字段类型为 HREF 时，该参数返回定义的 PC 端 URL。
└ option_id	string	字段类型为 ENUMERATION 或 PICTURE_ENUM 时，该参数返回定义的选项 ID。
└ option_value	string	枚举类型中选项的选项值。
└ name	string	图片类型中图片选项的名称。
└ picture_url	string	图片类型中图片选项的链接。
└ generic_user	custom_attr_generic_user	字段类型为 GENERIC_USER 时，该参数返回定义的引用人员信息。
└ id	string	引用人员的用户 ID。ID 类型与查询参数 user_id_type 的取值一致。
└ type	int	用户类型。目前固定为 1，表示用户类型。
└ enterprise_email	string	企业邮箱。 注意事项：企业管理员在管理后台启用飞书邮箱服务后，才会生效该参数。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ job_title	string	职务。 字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
└ is_frozen	boolean	是否为暂停状态的用户。 可能值有： - true：是 - false：否
└ geo	string	数据驻留地。 字段权限要求： contact:user.user_geo 查看成员数据驻留地
└ job_level_id	string	职级 ID。 字段权限要求： contact:user.job_level:readonly 查询用户职级
└ job_family_id	string	序列 ID。 字段权限要求： contact:user.job_family:readonly 查询用户所属的工作序列
└ dotted_line_leader_user_ids	string\[\]	虚线上级的用户 ID 列表。ID 类型与查询参数 user_id_type 的取值保持一致。 字段权限要求： contact:user.dotted_line_leader_info.read 查看成员的虚线上级 ID

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "user": {
            "union_id": "on_94a1ee5551019f18cd73d9f111898cf2",
            "user_id": "3e3cf96b",
            "open_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
            "name": "张三",
            "en_name": "San Zhang",
            "nickname": "Alex Zhang",
            "email": "zhangsan@gmail.com",
            "mobile": "13011111111",
            "mobile_visible": false,
            "gender": 1,
            "avatar_key": "2500c7a9-5fff-4d9a-a2de-3d59614ae28g",
            "avatar": {
                "avatar_72": "https://foo.icon.com/xxxx",
                "avatar_240": "https://foo.icon.com/xxxx",
                "avatar_640": "https://foo.icon.com/xxxx",
                "avatar_origin": "https://foo.icon.com/xxxx"
            },
            "status": {
                "is_frozen": false,
                "is_resigned": false,
                "is_activated": true,
                "is_exited": false,
                "is_unjoin": false
            },
            "department_ids": [
                "od-4e6ac4d14bcd5071a37a39de902c7141"
            ],
            "leader_user_id": "ou_7dab8a3d3cdcc9da365777c7ad535d62",
            "city": "杭州",
            "country": "CN",
            "work_station": "北楼-H34",
            "join_time": 2147483647,
            "is_tenant_manager": false,
            "employee_no": "1",
            "employee_type": 1,
            "orders": [
                {
                    "department_id": "od-4e6ac4d14bcd5071a37a39de902c7141",
                    "user_order": 100,
                    "department_order": 100,
                    "is_primary_dept": true
                }
            ],
            "custom_attrs": [
                {
                    "type": "TEXT",
                    "id": "DemoId",
                    "value": {
                        "text": "DemoText",
                        "url": "http://www.fs.cn",
                        "pc_url": "http://www.fs.cn",
                        "option_id": "edcvfrtg",
                        "option_value": "option",
                        "name": "name",
                        "picture_url": "https://xxxxxxxxxxxxxxxxxx",
                        "generic_user": {
                            "id": "9b2fabg5",
                            "type": 1
                        }
                    }
                }
            ],
            "enterprise_email": "demo@mail.com",
            "job_title": "xxxxx",
            "is_frozen": false,
            "geo": "cn",
            "job_level_id": "mga5oa8ayjlp9rb",
            "job_family_id": "mga5oa8ayjlp9rb",
            "dotted_line_leader_user_ids": [
                "ou_7dab8a3d3cdcc9da365777c7ad535d62"
            ]
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	40001	param error	参数错误，请对照接口文档修改输入参数后重试。
400	40003	internal error	内部错误。您可以获取请求的 X-Request-Id，并联系技术支持协助排查。
403	40004	no dept authority error	应用没有部门权限，检查该部门是否在应用的通讯录权限范围内。你可以登录开发者后台 ，在应用详情页的 开发配置 > 权限管理 > 数据权限 功能页查看 通讯录权限范围 内是否有相应部门，如果没有则需要在 通讯录权限范围 内添加上部门，并发布应用使配置生效。具体操作参考配置应用数据权限。 注意：如果通讯录权限范围设置的是 与应用的可用范围一致，则你需要在应用发布阶段（点击 应用发布 > 版本管理与发布 > 创建版本 后的 版本详情 页面内）配置应用的可用范围，并发布应用使配置生效。具体操作参考配置应用可用范围。
400	40021	no a same request error	非同一请求。两次请求如果传入了相同的 client_token，则当传入的其他参数取值不相同时，会报该错误。你需要根据实际场景选择是否传入 client_token 参数。
400	41001	mobile has already exist error	手机号已存在。你需要修改传入的手机号，确保租户内唯一。如何通过手机号查询用户信息，可参见通过手机号或邮箱获取用户 ID。
400	41002	email has already exist error	邮箱已存在。你需要修改传入的邮箱，确保租户内唯一。如何通过邮箱查询用户信息，可参见通过手机号或邮箱获取用户 ID。
409	41003	user account conflict error	用户的联系方式属于两个不同的飞书账号，导致添加失败。建议换用其它手机号或邮箱创建用户，或是先注销手机号或邮箱对应的用户帐号，然后再尝试创建。注销流程参见注销账号。如果问题仍未解决，请咨询技术支持。
400	41004	mobile is invalid error	手机号不合法。你需要参考接口文档提供的手机号参数描述，传入正确可用的手机号格式。
400	41005	email is invalid error	邮箱不合法。你需要参考接口文档提供的邮箱参数描述，传入正确可用的邮箱。
400	41006	no user name error	没有设置用户名称。请求时必须传入 name 参数。
400	41007	exceed uncertain tenant seat limit error	未认证租户的成员数目超过系统限制，无法创建用户。你需要清理租户内的无效成员或者扩容租户的成员数量限制。详情咨询技术支持。
400	41008	exceed bill seat limit error	租户的成员数目超过系统限制，无法创建用户。你需要清理租户内的无效成员或者扩容租户的成员数量限制。详情咨询技术支持。
400	41009	no email or mobile error	无邮箱或手机号。请求时，邮箱和手机号不能都为空。
400	41010	no mobile error	无手机号。请求时必须传入 mobile 参数。
400	41011	user id already exist error	user_id 重复。user_id 是用户在企业内的唯一ID，传入时如果重复可尝试更换其他自定义的 user_id。
400	41012	user id invalid error	用户 ID 无效。请参考接口文档提供的 user_id 参数说明，传入正确的 user_id 值。
400	41013	exceed user id update limit error	用户 ID 更新次数超过限制。
400	41014	user name sensitive error	传入的 name 中包含敏感信息。如有疑问，请联系技术支持。
400	41015	idp type invalid error	登录类型无效。
400	41016	department has too many users error	部门内的用户数量过多。当前设置的用户所属部门中存量用户数量达到上限，建议你修改用户的所属部门。
400	41017	department is required error	部门信息不能为空。请求时必须传入 department_ids 参数。
400	41018	position info is invalid error	岗位信息无效。
400	41019	position department is invalid error	岗位部门无效。
400	41020	position code has already exist error	岗位code无效。
400	41021	position multiple main count error	一个用户至多只能有设置一个主岗。
400	41022	user tenant not match error	用户租户不匹配。你需要检查是否使用其他企业的凭证访问了当前企业的资源。
400	41025	order department invalid error	排序信息中的部门无效。请求中，用户排序信息的部门 ID，必须是用户所属部门的部门 ID 之一。
504	41027	create account failed error	创建用户失败。请稍后重试，如果仍然失败请咨询技术支持。
405	41028	user multi department need upgrade visibility error	企业管理后台的权限规则未升级，不支持多部门。你需要登录管理后台，在 安全 > 成员权限 > 组织架构可见范围 页面内，根据页面提示提升权限规则。
400	41029	create or update user multi department error	当前企业不支持用户同时加入多个部门，如有疑问，请咨询技术支持。
400	41030	set leader to oneself error	不能将直属上级设置为自己。你需要将传入的直属上级参数值修改为用户实际对应的直属上级用户 ID，如无直属上级，则无需设置。
504	41031	position feature not enable error	当前企业不支持设置用户岗位信息，如有疑问，请咨询技术支持。
504	41032	user multi department feature not enable error	当前企业不支持用户同时加入多个部门，如有疑问，请咨询技术支持。
400	41033	user in too many departments error	用户所属部门过多。设置的用户所属部门（department_ids）数量不能超过 50 个。
400	41034	email prefix already exist error	邮箱前缀（@符号前的内容）已存在。更换为其他邮箱前缀后重试。
400	41035	email prefix is invalid error	邮箱前缀（@符号前的内容）不合法。请检查拼写是否有误。
400	41036	avatar key is invalid error	头像的文件 Key 无效。你可以重新调用上传图片接口，将头像文件上传后获取相应的 Key。
400	41037	avatar key is sensitive error	头像的文件 Key存在敏感信息。你可以重新调用上传图片接口，将头像文件上传后获取相应的 Key。
400	41038	gender is invalid error	性别参数不合法。你需要参考性别参数描述，传入正确的枚举值。
400	41040	user name is null error	用户名不能为空。请求时必须传入 name 参数。
400	41041	department id is not assigned error	未分配部门 ID。请求时必须传入用户所属部门 ID 列表参数（department_ids）
400	41042	join time is invalid error	用户加入时间不能为空。
400	41043	employee id is invalid error	无效的 user id。 user_id 的取值长度不能超过 64 个字符。
400	41044	Custom attribute is not set error	自定义字段属性设置有误。设置用户自定义字段时，必须指明设定的字段ID，字段 ID 可以通过获取企业自定义用户字段接口查询。
400	41045	Custom attribute id is not exist error	自定义字段 ID 不存在。你可以调用获取企业自定义用户字段接口，获取正确的字段 ID。
400	41046	Custom attribute value is not set error	自定义字段值设置有误。设置自定义字段时，需要传入相应的 value 字段。
400	41047	Custom attribute href text is null error	HREF 类型自定义字段的 text 属性为空。如果你设置了 HREF 类型的自定义字段，则 text 字段为必填字段。
400	41048	Custom attribute href url is null error	HREF 类型自定义字段的 url 属性为空。如果你设置了 HREF 类型的自定义字段，则 url 字段为必填字段。
400	41051	user id info not provide error	用户ID没有填写。
400	41052	user resign acceptor is invalid error	用户辞职审批人无效。
409	41053	user has already exist error	用户已存在。
400	41054	need send email but not set mail	需发送邮件但未设置邮箱。请求时请传入邮箱参数（email）。
400	41055	need send sms but not set mobile	需要发送手机短信单位设置手机号。请求时请传入手机号参数（mobile）。
400	41059	invalid employee type error	员工类型设置错误。员工类型的可选值有： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问 同时支持读取自定义的员工类型的 int 值。你可通过获取人员类型接口获取到该租户的自定义员工类型的编号值（enum_value）。
400	41060	inactive employee type error	员工类型在企业内未激活。你可以调用获取人员类型接口获取员工类型的使用状态（enum_status），仅可选择已激活的类型。
400	41063	job_title length exceed 100 character	设置的职务字符长度超过了 100 个字符。你需要减少设置的职务字符长度。
400	41068	Number of email aliases exceeds the upper limit	企业邮箱账户已经达到上限。请咨询企业管理员企业邮箱配额情况。
400	41069	Business email is in the recycle bin	企业邮箱处于回收站内，此时无法被使用。如需使用该企业邮箱，则需要先释放邮箱（在企业邮箱回收站内永久删除该邮箱），然后再使用。详情参见[员工离职后企业邮箱还能继续使用吗](https://www.feishu.cn/hc/zh-CN/articles/715885646166-管理员转移离职成员的邮件#tabs0
400	41070	name length exceed 255 character	用户名长度超过 255 个字符。你需要减少设置的用户名字符长度。
400	41071	en_name length exceed 255 character	用户英文名长度超过 255 个字符。你需要减少设置的用户英文名字符长度。
400	41072	nickname length exceed 255 character	用户别名长度超过 255 个字符。你需要减少设置的用户别名字符长度。
400	44001	business email domain not available error	企业无对应的企业邮域名。企业管理员必须在管理后台开通企业邮箱后，才可以在创建用户时设置企业邮箱地址。
400	44004	this user has been joined too many tenants recently	用户加入团队过于频繁，请 24 小时后重试。
400	44006	name length exceed 255 character	用户名超过 255 个字符。你需要减少设置的用户名字符长度。
400	44007	en_name length exceed 255 character	用户英文名超过 255 个字符。你需要减少设置的用户英文名字符长度。
400	44008	nickname length exceed 255 character	用户别名超过 255 个字符。你需要减少设置的用户别名字符长度。
400	44009	this tenant has been create too many users recently	团队添加成员过于频繁。一个手机号码或者一个邮箱，一天只能加入三个租户。
400	44012	Adding user has been intercepted. Contact Feishu Customer Service	添加成员失败，详情咨询技术支持。
400	44013	User enterprise Email password is not valid	输入的用户企业邮箱密码不合法，请修改后重试。
400	44016	can not set enterprise email password	设置企业邮箱密码失败，请确认是否有对应的权限。
400	44018	lark not support +86 mobile	Lark 不支持使用 +86 前缀的手机号。请修改后重试。
400	44019	feishu only support +86 mobile	未认证企业仅支持添加中国大陆 +86 手机号，添加非 +86 手机号请先完成飞书认证，完成认证后次日可添加。
400	44020	mobile and email need together exist	已认证企业，添加非 +86 手机号成员时必须同时添加邮箱。
400	44021	leader is resigned	直接主管或者虚线上级已离职，无法使用。请更换为正确可用的负责人后重试。
400	44022	leaderID is Invalid	直接主管或者虚线上级无效。请更换为正确可用的负责人后重试。
400	44023	exceed feature contact seat limit	创建的用户数量超出通讯录资源上限。如果需要使用更多用户数量，请升级飞书版本。了解更多参见版本对比。
400	44024	User enterprise email has already been registered as a member's account	企业邮箱已注册。
400	44038	req set user geo not find in geo list	您设置的数据驻留地（geo） 不在系统支持的 geo 列表中。
400	44039	not set geo name auth	没有设置数据驻留地（geo）的权限。
400	44040	tenant not open mg not set geo name	当前租户未开通多个数据驻留地功能，不能设置 geo 字段。如有疑问可咨询技术支持。
400	44044	invalid job level id	职级 ID 无效。你可以调用获取租户职级列表接口查询相应的职级 ID。
400	44045	invalid job family id	序列 ID 无效。你可以调用获取租户序列列表接口查询相应的序列 ID。
400	44046	user license subscription id must not empty in multi-license tenant	多许可证租户内创建用户时，必须指定席位 ID 参数。你可以调用获取企业席位信息接口接口查询席位详情，然后选择使用正确可用的席位 ID。
400	44047	license subscription id exceed limit	设置的席位 ID 已超过上限，请更换席位 ID。你可以调用获取企业席位信息接口接口查询席位详情，然后选择使用正确可用的席位 ID。
400	44048	user license subscription id invalid	请确认传入的席位 ID 正确有效。你可以调用获取企业席位信息接口接口查询席位详情，然后选择使用正确可用的席位 ID。
403	44050	not set subscription ids auth	未开通 分配用户席位 权限。你需要在 开发者后台 > 应用详情页 > 权限管理 > API 权限 内申请 分配用户席位 权限，并确保权限生效。
400	44051	employee_no already existed	员工工号重复，请修改后重试。
400	44054	create user success and create city fail	创建用户成功，创建工作城市字段失败。 可能原因： 1. 枚举值数量超过上限。工作城市枚举值数量上限均为 10,000。 2. 传入的值不合法。单个工作城市字符数量上限为 100。传入的内容也需要确保有效、无敏感信息。 3. 枚举值未启用。你可以调用获取租户工作城市列表接口，获取状态为已启用的工作城市信息。 如问题仍未解决请咨询技术支持。
400	44055	create user success and create job title fail	创建用户成功，创建职务字段失败。 可能原因： 1. 枚举值数量超过上限。职务的枚举值数量上限均为 10,000。 2. 传入的值不合法。单个职务的字符上限为 255。传入的内容也需要确保有效、无敏感信息。 3. 枚举值未启用。你可以调用获取租户职务列表，获取状态为已启用的职务信息。 如问题仍未解决请咨询技术支持。
400	44056	create user success and create city and job title fail	创建用户成功，创建工作城市、职务字段失败。 可能原因： 1. 枚举值数量超过上限。工作城市、职务的枚举值数量上限均为 10,000。 2. 传入的值不合法。单个工作城市字符数量上限为 100；单个职务的字符上限为 255。传入的内容也需要确保有效、无敏感信息。 3. 枚举值未启用。你可以调用获取租户工作城市列表接口，获取状态为已启用的工作城市信息。你可以调用获取租户职务列表，获取状态为已启用的职务信息。 如问题仍未解决请咨询技术支持。
400	44060	mg asset exceed time	数据驻留服务已到期。
400	44061	mg asset exceed quota	数据驻留服务无可分配席位。
400	41410	user primary dept must be the first department in the order	主部门必须为用户所属部门中排序第一的部门。请求时，is_primary_dept 为 true 的部门，department_order 取值必须为排序列表（orders）中的最大值。

更多错误码信息，参见通用错误码。