飞书开放平台 Server API 文档

主题

修改用户部分信息 ​

调用该接口更新通讯录中指定用户的信息，包括名称、邮箱、手机号、所属部门以及自定义字段等信息。

注意事项 ​

  • 发送请求时，未传递的参数不会更新。
  • 并发操作冻结用户时，因事务冲突会遇到概率性的接口调用失败。因此，请尝试降低请求速率或改为串行执行。
  • 更新 department_ids、is_frozen 时，限制调用频率为 1 QPS。
  • user_access_token 只允许修改这三个字段'name'、'en_name'、'avatar_key'。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/contact/v3/users/:user_id
HTTP MethodPATCH
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可contact:contact 更新通讯录 contact:user.base 更新用户基本信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 directory:employee.base.email:read 查看员工工作邮箱 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.job_level:readonly 查询用户职级 contact:user.employee_id:readonly 获取用户 user ID contact:user.phone:readonly 获取用户手机号 contact:user.email:readonly 获取用户邮箱信息 contact:user.job_family:readonly 查询用户所属的工作序列 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录

请求头 ​

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

路径参数 ​

名称类型描述
user_idstring用户 ID，ID 类型需要与查询参数中的 user_id_type 类型保持一致。
示例值："ou_7dab8a3d3cdcc9da365777c7ad535d62"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 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_typestring否此次调用中使用的部门 ID 类型。关于部门 ID 的详细介绍，可参见部门 ID 说明。
示例值：open_department_id
可选值有：
- department_id: 支持用户自定义配置的部门 ID。自定义配置时可复用已删除的 department_id，因此在未删除的部门范围内 department_id 具有唯一性。 - open_department_id: 由系统自动生成的部门 ID，ID 前缀固定为 od-，在租户内全局唯一。
默认值：open_department_id

请求体 ​

名称类型必填描述
namestring否用户名。长度不能超过 255 字符。
示例值："张三"
数据校验规则：
- 最小长度：1 字符
en_namestring否英文名。长度不能超过 255 字符。
示例值："San Zhang"
nicknamestring否别名。长度不能超过 255 字符。
示例值："Alex Zhang"
emailstring否邮箱。
注意： - 当设置非中国大陆的手机号时，必须同时设置邮箱。 - 在当前租户下，邮箱不可重复。
示例值："zhangsan@gmail.com"
mobilestring否手机号。
注意： - 在当前租户下，手机号不可重复。 - 未认证企业仅支持添加中国大陆手机号；通过飞书认证的企业允许添加海外手机号。 - 国际电话区号的前缀中，必须包含加号 +。
取值示例：
- 中国大陆手机号：13011111111 或 +8613011111111 - 非中国大陆手机号：+41446681800
示例值："13011111111"
mobile_visibleboolean否手机号码是否可见。
可选值有：
- true：可见。 - false：不可见。不可见时，企业内的员工将无法查看该用户的手机号码。
示例值：false
genderint否性别。
示例值：1
可选值有：
- 0: 保密 - 1: 男 - 2: 女 - 3: 其他
avatar_keystring否头像的文件 Key。你可以通过上传图片接口，上传并获取头像文件 Key，上传时图片类型需要选择 用于设置头像
示例值："2500c7a9-5fff-4d9a-a2de-3d59614ae28g"
department_idsstring\[\]否用户所属部门的 ID 列表。
- 一个用户可属于多个部门。最多可归属 50 个部门。 - 部门 ID 类型与查询参数 department_id_type 的取值保持一致。 - 你可以调用搜索部门接口，通过部门名称关键词获取对应的部门 ID。
示例值：["od-4e6ac4d14bcd5071a37a39de902c7141"]
leader_user_idstring否用户的直接主管的用户 ID，ID 类型与查询参数 user_id_type 的取值保持一致。用户 ID 获取方式可参见如何获取不同的用户 ID。
示例值："ou_7dab8a3d3cdcc9da365777c7ad535d62"
citystring否工作城市。字符长度上限为 100。
- 调用获取租户工作城市列表获取当前租户内已有的工作城市列表。 - 如果你传入的工作城市名称不存在，则系统会自动生成该工作城市。工作城市的枚举值数量上限为 10,000。
示例值："杭州"
countrystring否国家或地区 Code 缩写。具体写入格式参考 国家/地区 Code 参照表。
示例值："CN"
work_stationstring否工位。字符长度上限为 255。
示例值："北楼-H34"
join_timeint否入职时间。秒级时间戳格式，表示从 1970 年 1 月 1 日开始所经过的秒数。 修改用户信息传入 0 时，入职时间则会置空。

示例值：2147483647
employee_nostring否工号。字符长度上限为 255。
示例值："1"
employee_typeint否员工类型。
可选值有： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问
该参数支持读取自定义的员工类型的 int 值。你可通过获取人员类型接口获取到该租户的自定义员工类型的编号值（enum_value）。
示例值：1
ordersuser_order\[\]否用户排序信息。该参数用于标记通讯录下组织架构的人员顺序，人员可能存在多个部门中，且有不同的排序。
  └ department_idstring否排序信息对应的部门 ID。表示用户所在的、且需要排序的部门。
注意：
- 部门 ID 类型与查询参数 department_id_type 的取值保持一致。 - 该参数所传入的部门 ID 必须在用户所属的部门 ID 列表（department_ids 参数）内。
示例值："od-4e6ac4d14bcd5071a37a39de902c7141"
  └ user_orderint否用户在其直属部门内的排序，数值越大，排序越靠前。
注意：该参数为 int 类型，取值时不能超出 int 的最大值。
示例值：100
  └ department_orderint否用户所属的多个部门间的排序，数值越大，排序越靠前。
注意：该参数为 int 类型，取值时不能超出 int 的最大值。
示例值：100
  └ is_primary_deptboolean否标识是否为用户的唯一主部门，主部门为用户所属部门中排序第一的部门（department_order 最大）。
可选值有：
- true：是 - false：否
示例值：true
custom_attrsuser_custom_attr\[\]否自定义字段。设置参数前建议你先了解自定义字段资源介绍。
注意事项：当企业管理员在管理后台配置了自定义字段，且开启了 允许开放平台 API 调用 功能后，该字段才会生效。
  └ typestring否自定义字段类型。
可选值有： - TEXT：文本 - HREF：网页 - ENUMERATION：枚举 - PICTURE_ENUM：图片 - GENERIC_USER：用户
示例值："TEXT"
  └ idstring否自定义字段 ID。
示例值："DemoId"
  └ valueuser_custom_attr_value否自定义字段取值。
    └ textstring否- 字段类型为 TEXT 时，该参数定义字段值，必填。 - 字段类型为 HREF 时，该参数定义网页标题，必填。
长度不能超过 100 字符。
示例值："DemoText"
    └ urlstring否字段类型为 HREF 时，该参数定义默认 URL。例如，手机端跳转小程序，PC端跳转网页。
示例值："http://www.fs.cn"
    └ pc_urlstring否字段类型为 HREF 时，该参数定义 PC 端 URL。
示例值："http://www.fs.cn"
    └ option_idstring否字段类型为 ENUMERATION 或 PICTURE_ENUM 时，该参数定义选项 ID。
示例值："edcvfrtg"
    └ generic_usercustom_attr_generic_user否字段类型为 GENERIC_USER 时，该参数定义引用人员。
      └ idstring是引用人员的用户 ID。
- 自定义字段涉及的人员 ID，仅支持传入user_id格式的标识，该限制不受查询参数中user_id_type的取值影响。
- 如何获取用户 ID 可参见如何获取不同的用户 ID。
示例值："9b2fabg5"
      └ typeint是用户类型。
可选值有： 1：用户
说明：目前仅支持取值 1，表示用户。
示例值：1
enterprise_emailstring否企业邮箱。 注意事项：企业管理员在管理后台启用飞书邮箱服务后，才会生效该参数。如果设置企业邮箱失败，请联系企业管理员确认是否在管理后台启用了相应的企业邮箱域名。
示例值："demo@mail.com"
job_titlestring否职务名称。字符数量上限为 255。
- 你可以调用获取租户职务列表接口获取相应的租户名称。 - 如果传入的职务名称不存在，则系统会自动创建并使用该名称。职务枚举值数量上限为 10,000。 - 如果传入空格字符串，则意味着清空职务。
示例值："xxxxx"
is_frozenboolean否是否是暂停状态的用户。
可选值有： - true：是 - false：否
示例值：false
job_level_idstring否职级 ID。你可以调用获取租户职级列表接口查询相应的职级 ID。
示例值："mga5oa8ayjlp9rb"
job_family_idstring否序列 ID。你可以调用获取租户序列列表接口查询相应的序列 ID。
示例值："mga5oa8ayjlpzjq"
subscription_idsstring\[\]否分配给用户的席位 ID 列表。
注意事项： - 该字段需开通 分配用户席位 权限。 - 你可通过获取企业席位信息接口，获取到当前租户的可用席位 ID。
示例值：["23213213213123123"]
dotted_line_leader_user_idsstring\[\]否虚线上级的用户 ID 列表。
- ID 类型与查询参数 user_id_type 的取值保持一致。
- 如何获取用户 ID 可参见如何获取不同的用户 ID。
示例值：["ou_7dab8a3d3cdcc9da365777c7ad535d62"]

请求体示例 ​

json
{
    "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-4e6ac4d14bcd5071a37a39de902c7141"
    ],
    "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",
    "is_frozen": false,
    "job_level_id": "mga5oa8ayjlp9rb",
    "job_family_id": "mga5oa8ayjlpzjq",
    "subscription_ids": [
        "23213213213123123"
    ],
    "dotted_line_leader_user_ids": [
        "ou_7dab8a3d3cdcc9da365777c7ad535d62"
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ useruser用户信息
    └ union_idstring用户的 union_id，是应用开发商发布的不同应用中同一用户的标识。不同用户 ID 的说明参见 用户相关的 ID 概念。
    └ user_idstring用户的 user_id，租户内用户的唯一标识。不同用户 ID 的说明参见 用户相关的 ID 概念。
字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
    └ open_idstring用户的 open_id，应用内用户的唯一标识。不同用户 ID 的说明参见 用户相关的 ID 概念。
    └ namestring用户名。
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ en_namestring英文名。
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ nicknamestring别名。
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ emailstring邮箱。
字段权限要求（满足任一）： directory:employee.base.email:read 查看员工工作邮箱 contact:user.email:readonly 获取用户邮箱信息
    └ mobilestring手机号。
字段权限要求： contact:user.phone:readonly 获取用户手机号
    └ mobile_visibleboolean手机号码是否可见。
可能值有：
- true：可见。 - false：不可见。不可见时，企业内的员工将无法查看该用户的手机号码。
    └ genderint性别。
可选值有：
- 0: 保密 - 1: 男 - 2: 女 - 3: 其他
字段权限要求（满足任一）： contact:user.gender:readonly 获取用户性别 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ avataravatar_info用户头像信息。
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ avatar_72string72*72 像素头像链接。
      └ avatar_240string240*240 像素头像链接。
      └ avatar_640string640*640 像素头像链接。
      └ avatar_originstring原始头像链接。
    └ statususer_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_frozenboolean是否为暂停状态。
可能值有：
- true：是 - false：否
      └ is_resignedboolean是否为离职状态。
可能值有：
- true：是 - false：否
      └ is_activatedboolean是否为激活状态。
可能值有：
- true：是 - false：否
      └ is_exitedboolean是否为主动退出状态。主动退出一段时间后用户状态会自动转为已离职。
可能值有：
- true：是 - false：否
      └ is_unjoinboolean是否为未加入状态，需要用户自主确认才能加入企业或团队。
可能值有：
- true：是 - false：否
    └ department_idsstring\[\]用户所属部门的 ID 列表，一个用户可属于多个部门。ID 值的类型与查询参数中的 department_id_type 的取值保持一致。
字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ leader_user_idstring用户的直接主管的用户ID。ID 值的类型与查询参数中的user_id_type 的取值保持一致。
字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ citystring工作城市。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ countrystring国家或地区 Code 缩写，具体格式参考 国家/地区 Code 参照表。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ work_stationstring工位。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ join_timeint入职时间。秒级时间戳格式，表示从 1970 年 1 月 1 日开始所经过的秒数。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ is_tenant_managerboolean用户是否为租户超级管理员。
可能值有： - true：是 - false：否
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ employee_nostring工号。
字段权限要求（满足任一）： contact:user.employee_number:read 查看成员工号 contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ employee_typeint员工类型。
可能值有：
- 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问
同时支持自定义员工类型的 int 值。你可通过获取人员类型接口获取到当前租户内自定义员工类型的名称。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ ordersuser_order\[\]用户排序信息。用于标记通讯录下组织架构的人员顺序，人员可能存在多个部门中，且有不同的排序。
字段权限要求（满足任一）： contact:user.department:readonly 获取用户组织架构信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ department_idstring排序信息对应的部门 ID，表示用户所在的、且需要排序的部门。ID 值的类型与查询参数中的 department_id_type 的取值保持一致。
      └ user_orderint用户在其直属部门内的排序。数值越大，排序越靠前。
      └ department_orderint用户所属的多个部门间的排序。数值越大，排序越靠前。
      └ is_primary_deptboolean标识是否为用户的唯一主部门。主部门为用户所属部门中排序第一的部门(department_order 最大)。
可能值有： - true：是 - false：否
    └ custom_attrsuser_custom_attr\[\]自定义字段。
注意事项：当企业管理员在管理后台配置了自定义字段，且开启了 允许开放平台 API 调用 功能后，该字段才会生效。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
      └ typestring自定义字段类型。
可能值有： - TEXT：文本 - HREF：网页 - ENUMERATION：枚举 - PICTURE_ENUM：图片 - GENERIC_USER：用户
      └ idstring自定义字段 ID。
      └ valueuser_custom_attr_value自定义字段取值。
        └ textstring- 字段类型为 TEXT 时，该参数返回定义的字段值。 - 字段类型为 HREF 时，该参数返回定义的网页标题。
        └ urlstring字段类型为 HREF 时，该参数返回定义的默认 URL。
        └ pc_urlstring字段类型为 HREF 时，该参数返回定义的 PC 端 URL。
        └ option_idstring字段类型为 ENUMERATION 或 PICTURE_ENUM 时，该参数返回定义的选项 ID。
        └ option_valuestring枚举类型中选项的选项值。
        └ namestring图片类型中图片选项的名称。
        └ picture_urlstring图片类型中图片选项的链接。
        └ generic_usercustom_attr_generic_user字段类型为 GENERIC_USER 时，该参数返回定义的引用人员。
          └ idstring引用人员的 user_id。ID 类型与查询参数 user_id_type 的取值保持一致。
          └ typeint用户类型。目前固定为 1，表示用户类型。
    └ enterprise_emailstring企业邮箱。 注意事项：企业管理员在管理后台启用飞书邮箱服务后，才会生效该参数。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ job_titlestring职务。
字段权限要求（满足任一）： contact:user.employee:readonly 获取用户受雇信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ is_frozenboolean是否为暂停状态的用户。
可能值有： - true：是 - false：否
    └ job_level_idstring职级 ID。
字段权限要求： contact:user.job_level:readonly 查询用户职级
    └ job_family_idstring序列 ID。
字段权限要求： contact:user.job_family:readonly 查询用户所属的工作序列
    └ dotted_line_leader_user_idsstring\[\]虚线上级的用户 ID。ID 类型与查询参数 user_id_type 的取值保持一致。
字段权限要求： contact:user.dotted_line_leader_info.read 查看成员的虚线上级 ID

响应体示例 ​

json
{
    "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": {
                "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,
            "job_level_id": "mga5oa8ayjlp9rb",
            "job_family_id": "mga5oa8ayjlpzjq",
            "dotted_line_leader_user_ids": [
                "ou_7dab8a3d3cdcc9da365777c7ad535d62"
            ]
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
40040001param error参数错误，请对照接口文档修改输入参数后重试。
40041001mobile has already exist error手机号已存在。你需要修改传入的手机号，确保租户内唯一。如何通过手机号查询用户信息，可参见通过手机号或邮箱获取用户 ID。
40041002email has already exist error邮箱已存在。你需要修改传入的邮箱，确保租户内唯一。如何通过邮箱查询用户信息，可参见通过手机号或邮箱获取用户 ID。
40941003user account conflict error用户的联系方式属于两个不同的飞书账号，导致添加失败。建议换用其它手机号或邮箱创建用户，或是先注销手机号或邮箱对应的用户帐号，然后再尝试创建。注销流程参见注销账号。如果问题仍未解决，请咨询技术支持。
40041004mobile is invalid error手机号不合法。你需要参考接口文档提供的手机号参数描述，传入正确可用的手机号格式。
40041005email is invalid error邮箱不合法。你需要参考接口文档提供的邮箱参数描述，传入正确可用的邮箱。
40041006no user name error没有设置用户名称。请求时必须传入 name 参数。
40041009no email or mobile error电子邮箱和手机号不能都为空。
40041010no mobile error手机号不能为空。
40041011user id already exist erroruser_id 重复。user_id 是用户在企业内的唯一ID，传入时如果重复可尝试更换其他自定义的 user_id。
40041014user name sensitive error传入的 name 中包含敏感信息。如有疑问，请联系技术支持。
40041016department has too many users error部门内的用户数量过多。用户所属部门中的用户数量不能超过 500，建议你修改用户的所属部门。
40041017department is required error部门信息不能为空。
40041018position info is invalid error岗位信息无效。
40041019position department is invalid error岗位部门无效。
40041020position code has already exist error岗位code无效。
40041021position multiple main count error一个用户至多只能有设置一个主岗。
40041022user tenant not match error用户租户不匹配。你需要检查是否使用其他企业的凭证访问了当前企业的资源。
40041023update department conflict position department error用户的岗位部门必须与用户的部门一致，更新用户部门需要同时更新相应的岗位部门，否则阻断更新操作。
40041024update position department conflict department error用户的岗位部门必须与用户的部门一致，用户的新岗位部门也必须是用户的部门之一，否则阻断更新操作。
40041025order department invalid error排序信息中的部门无效。请求中，用户排序信息的部门 ID，必须是用户所属部门的部门 ID 之一。
40541028user multi department need upgrade visibility error企业管理后台的权限规则未升级，不支持多部门。你需要登录管理后台，在 安全 > 成员权限 > 组织架构可见范围 页面内，根据页面提示提升权限规则。
40041029create or update user multi department error当前企业不支持用户同时加入多个部门，如有疑问，请咨询技术支持。
40041030set leader to oneself error不能将直属上级设置为自己。你需要将传入的直属上级参数值修改为用户实际对应的直属上级用户 ID，如无直属上级，则无需设置。
50441031position feature not enable error当前企业不支持设置用户岗位信息，如有疑问，请咨询技术支持。
50441032user multi department feature not enable error当前企业不支持用户同时加入多个部门，如有疑问，请咨询技术支持。
40041033user in too many departments error用户所属部门过多。设置的用户所属部门（department_ids）数量不能超过 50 个。
40041034email prefix already exist error邮箱前缀（@符号前的内容）已存在。更换为其他邮箱前缀后重试。
40041035email prefix is invalid error邮箱前缀（@符号前的内容）不合法。请检查拼写是否有误。
40041036avatar key is invalid error头像的文件 Key 无效。你可以重新调用上传图片接口，将头像文件上传后获取相应的 Key。
40041037avatar key is sensitive error头像的文件 Key存在敏感信息。你可以重新调用上传图片接口，将头像文件上传后获取相应的 Key。
40041038gender is invalid error性别参数不合法。你需要参考性别参数描述，传入正确的枚举值。
40041040user name is null error用户名不能为空。请求时必须传入 name 参数。
40041041department id is not assigned error未分配部门 ID。请求时必须传入用户所属部门 ID 列表参数（department_ids）
40041042join time is invalid error用户加入时间不能为空。
40041043employee id is invalid error无效的 user id。 user_id 的取值长度不能超过 64 个字符。
40041044Custom attribute is not set error自定义字段属性设置有误。设置用户自定义字段时，必须指明设定的字段ID，字段 ID 可以通过获取企业自定义用户字段接口查询。
40041045Custom attribute id is not exist error自定义字段 ID 不存在。你可以调用获取企业自定义用户字段接口，获取正确的字段 ID。
40041046Custom attribute value is not set error自定义字段值设置有误。设置自定义字段时，需要传入相应的 value 字段。
40041047Custom attribute href text is null errorHREF 类型自定义字段的 text 属性为空。如果你设置了 HREF 类型的自定义字段，则 text 字段为必填字段。
40041048Custom attribute href url is null errorHREF 类型自定义字段的 url 属性为空。如果你设置了 HREF 类型的自定义字段，则 url 字段为必填字段。
40041050no user authority error无用户权限。需将当前操作的用户添加到应用或用户的权限范围内。根据调用 API 的身份不同，解决方案也不同，具体说明如下： - 使用 tenant_access_token 调用 API 当前操作的用户需要添加在应用的通讯录权限范围内。通讯录权限范围定义了应用在调用通讯录 API 时可获取的部门、用户的数据范围。应用无法访问不在通讯录权限范围内的数据。 由开发者登录开发者后台，在应用详情页的 开发配置 > 权限管理 > 数据权限 页面内，配置 通讯录权限范围，添加指定用户。 image.png 已发布的应用企业管理员可在管理后台 > 工作台 > 应用管理 页面，修改应用的通讯录权限范围。 image.png - 使用 user_access_token 调用 API 当你使用用户身份调用通讯录 API 时，可操作的权限范围不受应用的通讯录权限范围影响，而是受当前用户的组织架构可见范围影响，该范围限制了用户在企业内可见的组织架构数据范围。 由企业管理员在管理后台 > 安全 > 成员权限 页面中，点击 组织架构可见范围 进行管理。 image.png 完整介绍参见权限范围资源介绍。
40041051user id info not provide error用户ID没有填写。
40340004no dept authority error无部门权限。当前操作的部门需在应用的通讯录权限范围内。通讯录权限范围的介绍与设置方式，参见权限范围资源介绍。
40341056no field authority error没有字段权限。你需要参考接口文档的字段权限要求，为应用依次开通这些字段权限。
40041057invalid employee type error员工类型设置错误。员工类型的可选值有： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问 同时支持读取自定义的员工类型的 int 值。你可通过获取人员类型接口获取到该租户的自定义员工类型的编号值（enum_value）。
40041059invalid employee type error员工类型设置错误。员工类型的可选值有： - 1：正式员工 - 2：实习生 - 3：外包 - 4：劳务 - 5：顾问 同时支持读取自定义的员工类型的 int 值。你可通过获取人员类型接口获取到该租户的自定义员工类型的编号值（enum_value）。
40041060inactive employee type error员工类型在企业内未激活。你可以调用获取人员类型接口获取员工类型的使用状态（enum_status），仅可选择已激活的类型。
40041063job_title length exceed 100 character设置的职务字符长度超过了 100 个字符。你需要减少设置的职务字符长度。
40042008tenant id is invalid error请检查请求租户是否为合法租户。
40041068Number of email aliases exceeds the upper limit企业邮箱账户已经达到上限。请咨询企业管理员企业邮箱配额情况。
40041069Business email is in the recycle bin企业邮箱处于回收站内，此时无法被使用。如需使用该企业邮箱，则需要先释放邮箱（在企业邮箱回收站内永久删除该邮箱），然后再使用。详情参见[员工离职后企业邮箱还能继续使用吗](https://www.feishu.cn/hc/zh-CN/articles/715885646166-管理员转移离职成员的邮件#tabs0
40041070name length exceed 255 character用户名长度超过 255 个字符。你需要减少设置的用户名字符长度。
40041071en_name length exceed 255 character用户英文名长度超过 255 个字符。你需要减少设置的用户英文名字符长度。
40041072nickname length exceed 255 character用户别名长度超过 255 个字符。你需要减少设置的用户别名字符长度。
40044001business email domain not available error企业无对应的企业邮域名。企业管理员必须在管理后台开通企业邮箱后，才可以在创建用户时设置企业邮箱地址。
40044002update order must update department together修改用户部门排序（order）时，请求必须同时带上用户所属部门 ID 列表（department_ids）。此外，用户排序中设置的部门 ID，必须包含在用户所属部门 ID 列表中。
40044003avatarkey and description cannot be empty when update resigned user更新离职用户时，头像 Key 和信息不能为空。
40044006name length exceed 255 character用户名长度超过 255 个字符。你需要减少设置的用户名字符长度。
40044007en_name length exceed 255 character用户英文名长度超过 255 个字符。你需要减少设置的用户英文名字符长度。
40044008nickname length exceed 255 character用户别名长度超过 255 个字符。你需要减少设置的用户别名字符长度。
40044010unJoined user not allow to update不允许更新未加入状态的用户信息。
40044011exited user not allow to update禁止更新主动退出状态的用户信息。
40042006user has resigned error用户已经离职，无法更新信息。
40044013User enterprise Email password is not valid用户的企业邮箱密码无效。
40044014Can not update inactive user email when email equal enterprise当用户邮箱为企业邮箱时，无法更新。
40044015can not update password when user already have password已有用户密码时无法更新密码。
40044016can not set enterprise email password无法设置企业邮箱密码。
40044017Suite_Admin_Common_UnableToEditUpper传入的内容被风险控制，你需要检查内容是否合法。
40044018lark not support +86 mobileLark 不支持使用 +86 前缀的手机号。请修改后重试。
40044019feishu only support +86 mobile未认证企业仅支持添加中国大陆 +86 手机号，添加非 +86 手机号请先完成飞书认证，完成认证后次日可添加。
40044020mobile and email need together exist已认证企业，添加非 +86 手机号成员时必须同时添加邮箱。
40044024User enterprise email has already been registered as a member's account企业邮箱已注册。
40044025update user lock error,wait some seconds and retry并发更新User受限，请等待一段时间重试。
40044035departmentID is invaild部门 ID 是无效的。你可以调用搜索部门接口，通过部门名称关键词获取对应的部门 ID。
40044036freeze tenant founder is forbidden不允许将租户创建者的状态跟改为冻结。
40044038req set user geo not find in geo list您设置的数据驻留地（geo） 不在系统支持的 geo 列表中。
40044041anonymize user info is not allowed to update已匿名的用户信息不允许更新。
40044044invalid job level id职级 ID 无效。你可以调用获取租户职级列表接口查询相应的职级 ID。
40044045invalid job family id序列 ID 无效。你可以调用获取租户序列列表接口查询相应的序列 ID。
40044046user license subscription id must not empty in multi-license tenant多许可证租户内创建用户时，必须指定席位 ID 参数。你可以调用获取企业席位信息接口接口查询席位详情，然后选择使用正确可用的席位 ID。
40044047license subscription id exceed limit设置的席位 ID 已超过上限，请更换席位 ID。你可以调用获取企业席位信息接口接口查询席位详情，然后选择使用正确可用的席位 ID。
40044048user license subscription id invalid请确认传入的席位 ID 正确有效。你可以调用获取企业席位信息接口接口查询席位详情，然后选择使用正确可用的席位 ID。
40044049license subscription update fail更新席位信息失败，请重试。
40344050not set subscription ids auth未开通 分配用户席位 权限。你需要在 开发者后台 > 应用详情页 > 权限管理 > API 权限 内申请 分配用户席位 权限，并确保权限生效。
40044051employee_no already existed员工工号重复，请修改后重试。
40044052Unable to edit members because your current plan has expired飞书版本过期，无法编辑用户。因版本过期导致的租户人数超过版本上限，需要减少租户人数或者升级版本。关于飞书版本的介绍可参见版本对比。
40044053Unable to edit data from external data sources无法编辑来自外部数据源的数据。
40044057update user success and create city fail更新成功但创建工作城市失败。 可能原因： 1. 枚举值数量超过上限。工作城市的枚举值数量上限为 10,000。 2. 传入的值不合法。单个工作城市字符数量上限为 100，且需要传入真实有效的城市名称。 3. 传入的工作城市未启用。你可以调用获取租户工作城市列表接口，获取状态为已启用的工作城市。 如问题仍未解决请咨询技术支持。
40044058update user success and create job title fail更新成功但创建职务失败。 可能原因： 1. 枚举值数量超过上限。职务枚举值上限为 10,000。 2. 传入的值不合法。单个职务的字符上限为 255。 3. 传入的职务未启用。你可以调用获取租户职务列表接口，获取状态为已启用的职务。 如问题仍未解决请咨询技术支持。
40044059update user success and create city and job title fail更新成功但创建工作城市、职务失败。 可能原因： 1. 枚举值数量超过上限。工作城市、职务的枚举值数量上限均为 10,000。 2. 传入的值不合法。单个工作城市字符数量上限为 100；单个职务的字符上限为 255。传入的内容也需要确保有效、无敏感信息。 3. 枚举值未启用。你可以调用获取租户工作城市列表接口，获取状态为已启用的工作城市信息。你可以调用获取租户职务列表，获取状态为已启用的职务信息。 如问题仍未解决请咨询技术支持。
40041410user primary dept must be the first department in the order主部门必须为用户所属部门中排序第一的部门。请求时，is_primary_dept 为 true 的部门，department_order 取值必须为排序列表（orders）中的最大值。

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

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有