通讯录 - 人员管理

服务端 API 更新于 2026-08-28 阅读 11

创建人员

接口说明：通过此接口，可以创建人员。仅组织内应用经过授权可以调用该接口。特别说明：目前蓝信不支持应用并发调用人员创建接口，否则会出现添加人员到部门的操作失败，应用需要保证串行化调用该接口。已支持批量人员创建接口，大量集中进行人员同步时建议使用批量接口。创建人员-批量请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/staffs/create?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段, 人员TOKEN

请求数据示例：

{
    "orgId": "xxxx",
    "name": "张三",
    "loginWays": [0],
    "loginName": "xxxx",
    "loginPassword": "xxxx",
    "mobilePhone": {
        "countryCode": "86",
        "number": "12345678902"
    },
    "smsInvitation":false,
    "emailInvitation":false,
    "sendAccountInfo":false,
    "employeeNumber": "xxxx"
    "gender": 1 ,
    "avatarId":"345678-999",
    "email": "zhangsan@test.com" ,
    "signature":"生活要精彩",
    "nationality": "汉族",
    "birthdate": "1999-09-09",
    "idNumber":"130424xxxxxxxxxxxx",
    "nativePlace":"xxxxxx",
    "duties":"组长",
    "parties":"共产党",
    "tags": ["524288-xxxxxxxxx", "524288-xxxxxxxx"]
    "externalId":"",
    "extraPhones":[
        {
         "countryCode": "86",
         "number": "13811111111"
        },
        {
         "countryCode": "86",
         "number": "13822222222"
        }
    ],
    "departments":[
        {
            "id": "12345-xxxxxxxx" ,
            "orderNumber": 0
        },
        {
            "id": "12345-xxxxxxxx" ,
            "orderNumber": 40
        }
    ],
    "introduction":{
        "introduction":"something about introduction"
        "mediaIds":["524288-xxxxxxxxxxxxx","524288-xxxxxxxxxxxxx"]
    },
    "education":[
        {
            "unit":"学校名称1",
            "description":"something about description",
            "startDate":"2014-8-12",
            "endData":"2016-8-12"
        },
        {
            "unit":"学校名称2",
            "description":"something about description",
            "startDate":"2016-8-12",
            "endData":"2019-8-12"

        }
    ],
    "career":[
        {
            "unit":"公司名称1",
            "description":"something about description",
            "startDate":"2014-8-12",
            "endData":"2016-8-12"
        },
        {
            "unit":"公司名称2",
            "description":"something about description",
            "startDate":"2016-8-12",
            "endData":"2019-8-12"
        }
    ],
    "extraFieldSet":{
        "524288-xxxxxxxxxxxx": "mail@test.net" ,
        "524288-xxxxxxxxxxxx": "xxxxx",
        "524288-xxxxxxxxxxxx": "xxxxx",
        "524288-xxxxxxxxxxxx": ""
    },
    "disablePasswordReset":false,
    "address":"北京市"
}

请求参数字段说明：|参数|类型|必须|说明 | |----------------|-------------|----------------------------|------------------------------------------------------------------| | orgId | string | 是 | 人员所在组织ID | | name | string | 是 | 人员姓名 | | loginWays | int array | 否 | 蓝信登录方式：0-手机号， 1-邮箱， 2-账密。不填时默认手机号且手机号不能为空。目前一个人只支持一种登录方式。特别说明：如果指定账密登录方式时，需要通过蓝信超级管理员在对应的组织上创建一个组织标识 |
| loginName | string | 否 | 账密登录方式的登录账号，loginWays指定账密方式登录时不能为空。创建后不可修改，组织内必须唯一。; 特别说明：如果指定登录方式为账密登录时（loginWays=2），需要通过蓝信超级管理员在对应的组织上创建一个组织标识，例如:zzbs |
| loginPassword | string | 否 | 登录方式为账密登录时，设置账户的登录密码，不能为空，为避免密码泄漏，要求原始密码使用哈希算法计算哈希值后再填充该字段，具体哈希算法需要联系组织管理员确认(算法为组织配置，例如SHA256)。|
| mobilePhone | json obj | 否 | 手机号码，loginWays指定手机号登录时不能为空，组织内必须唯一。 |
| mobilePhone.countryCode | string | 是 | 国家码 |
| mobilePhone.number | string | 是 | 手机号 |
| smsInvitation | bool | 否 |集中同步大量人员时，不建议发送邀请短信，否则会造成同步接口调用失败率升高和速度降低。是否发送短信邀请，默认短信内容为：#人员姓名#，欢迎加入#组织(企业)名称#，蓝信为企业内部指定通讯工具，请尽快下载#下载地址# 安装蓝信 | | emailInvitation | bool | 否 |集中同步大量人员时，不建议发送邀请邮件，否则会造成同步接口调用失败率升高和速度降低。是否发送邮件邀请，默认邮件内容为：#人员姓名#，欢迎加入#组织(企业)名称#，蓝信为企业内部指定通讯工具，请尽快下载#下载地址# 安装蓝信 | | sendAccountInfo | bool | 否 | 邮件或短信邀请中是否包含账户和密码信息 | | departments | obj array | 是 | 人员所在分支 | | departments.id | string | 是 | 分支ID | | departments.orderNumber| int | 否 | 人员在分支里的排序。排序不确定时可填0，服务端为忽略0值，有效值从1开始 | | employeeNumber | string | 否 | 人员号，组织内唯一，和系统已有人员号冲突时接口返回数据冲突错误 | | gender | int | 否 | 性别：0-保密， 1-男， 2-女 |
| avatarId | string | 否 | 人员在蓝信里的头像 | | email | string | 否 | 电子邮箱地址, loginWays指定邮箱登录时不能为空，组织内唯一，和系统已有邮箱地址冲突时接口返回数据冲突错误 | | signature | string | 否 | 人员个人签名 | | nationality | string | 否 | 民族 | | birthdate | string | 否 | 出生日期。格式：year-month-day | | extraPhones | obj array | 否 | 附加联系方式 | | extraPhones.countryCode | string | 是 | 国家码 | | extraPhones.number | string | 是 | 电话号码 | | introduction | json obj | 否 | 个人介绍 | | introduction.introduction | string | 否 | 个人介绍-描述 | | introduction.mediaIds | string array | 否 | 个人介绍-图片 | | education | obj array| 否 | 受教育履历 | | education.unit |string | 否 | 教育机构名称 | | education.description |string | 否 | 受教育描述 | | education.startDate | string | 否 | 开始日期，日期格式：yyyy-mm-dd | | education.endData | string | 否 | 结束日期，日期格式：yyyy-mm-dd | | career | obj array | 否 | 工作简历 | | career.unit | string | 否 | 工作单位 | | career.description | string | 否 | 工作描述 | | career.startDate | string | 否 | 开始日期，日期格式：yyyy-mm-dd | | career.endData | string | 否 | 结束日期，日期格式：yyyy-mm-dd | | idNumber | string | 否 | 身份证号 |
| nativePlace | string | 否 | 籍贯 | | duties | string | 否 | 职务 |
| parties | string | 否 | 党派 |
| extraFieldSet | map obj | 否 | k和v都是string.自定义扩展属性，k代表扩展字段ID，这个ID由蓝信管理后台预定义，应用可以通过以下接口获取获取组织预定义的人员扩展字段ID列表。 |
| tags | string array | 否 | 人员标签信息 |
| externalId | string | 否 | 人员外部ID，组织通讯录数据源唯一标识人员的ID。注意，如果是账号密码方式登录蓝信，应该使用loginName字段。如果是手机号方式登录蓝信，又想保留组织内的人员唯一ID，可以使用该externalId 字段。externalId 和 employeeNumber类似，用于组织内人员的唯一标识。创建后不可修改，组织内必须唯一。 | | disablePasswordReset | bool | 否 | 账密登录方式，首次登录时是否禁用强制修改密码。 ; 禁用 - true ; 不禁用 - false (默认) |
| address| string | 否 | 人员(办公)地址 |

返回参数字段说明：|参数|类型|描述 | |----------|---------|-----------------------| | staffId | string | 人员在组织里的staffId |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
   "data": {
     "staffId": "588-9876"
   }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

创建人员-批量

接口说明：通过此接口，可以批量创建人员。仅企业内应用经过授权可以调用该接口。特别说明：目前蓝信不支持应用并发调用人员创建接口，否则会出现添加人员到部门的操作失败，应用需要保证串行化调用该接口。单次创建人数上限32个

请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/staffs/batch/create?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段, 人员TOKEN

请求数据示例：

{
    "users":[
        {
            "orgId":"1572864",
            "name":"x01",
            "loginWays":null,
            "loginName":"",
            "loginPassword":"54f51f2e1faf3e90b9b5316c90ca15be4b97f89d92f07f92bd334407562b6460",
            "gender":1,
            "signature":"生活要精彩",
            "nationality":"汉族",
            "birthdate":"1999-09-09",
            "idNumber":"12345678912",
            "duties":"组长",
            "parties":"共产党",
            "mobilePhone":{
                "countryCode":"86",
                "number":"136888888888"
            },
            "smsInvitation":false,
            "departments":[
                {
                    "id":"1572864-qruEc2o8vvbfadgaIYY2VFpwjpP",
                    "orderNumber":100
                }
            ]
        },
        {
            "orgId":"1572864",
            "name":"x02",
            "loginWays":null,
            "loginName":"",
            "loginPassword":"54f51f2e1faf3e90b9b5316c90ca15be4b97f89d92f07f92bd334407562b6460",
            "gender":1,
            "signature":"生活要精彩",
            "nationality":"汉族",
            "birthdate":"1999-09-09",
            "idNumber":"12345678912",
            "duties":"组长",
            "parties":"共产党",
            "mobilePhone":{
                "countryCode":"86",
                "number":"136888888888"
            },
            "smsInvitation":false,
            "departments":[
                {
                    "id":"1572864-qruEc2o8vvbfadgaIYY2VFpwjpP",
                    "orderNumber":100
                }
            ]
        }
    ]
}

请求参数字段说明：|参数|类型|必须|说明 | |----------------|-------------|----------------------------|---------------------- -----------------| | users | obj array | 是 | 待新增用户集合，单次新增用户上限32个 | | orgId | string | 是 | 人员所在组织Id | | name | string | 是 | 人员姓名 | | loginWays | int array | 否 | 蓝信登录方式：0-手机号， 1-邮箱， 2-账密。不填时默认手机号且手机号不能为空。目前一个人只支持一种登录方式。特别说明：如果指定账密登录方式时，需要通过蓝信超级管理员在对应的组织上创建一个组织标识 |
| loginName | string | 否 | 账密登录方式的登录账号，loginWays指定账密方式登录时不能为空。创建后不可修改，组织内必须唯一。; 特别说明：如果指定登录方式为账密登录时（loginWays=2），需要通过蓝信超级管理员在对应的组织上创建一个组织标识，例如:zzbs |
| loginPassword | string | 否 | 登录方式为账密登录时，设置账户的登录密码，不能为空，为避免密码泄漏，要求原始密码使用哈希算法计算哈希值后再填充该字段，具体哈希算法需要联系组织管理员确认(算法为组织配置，例如SHA256)。|
| mobilePhone | json obj | 否 | 手机号码，loginWays指定手机号登录时不能为空，组织内必须唯一。 |
| mobilePhone.countryCode | string | 是 | 国家码 |
| mobilePhone.number | string | 是 | 手机号 |
| smsInvitation | bool | 否 |集中同步大量人员时，不建议发送邀请短信，否则会造成同步接口调用失败率升高和速度降低。是否发送短信邀请，默认短信内容为：#人员姓名#，欢迎加入#组织(企业)名称#，蓝信为企业内部指定通讯工具，请尽快下载#下载地址# 安装蓝信 | | emailInvitation | bool | 否 |集中同步大量人员时，不建议发送邀请邮件，否则会造成同步接口调用失败率升高和速度降低。是否发送邮件邀请，默认邮件内容为：#人员姓名#，欢迎加入#组织(企业)名称#，蓝信为企业内部指定通讯工具，请尽快下载#下载地址# 安装蓝信 | | sendAccountInfo | bool | 否 | 邮件或短信邀请中是否包含账户和密码信息 | | departments | obj array | 是 | 人员所在分支 | | departments.id | string | 是 | 分支Id | | departments.orderNumber| int | 否 | 人员在分支里的排序。排序不确定时可填0，服务端为忽略0值，有效值从1开始 | | employeeNumber | string | 否 | 人员号，组织内唯一，和系统已有人员号冲突时接口返回数据冲突错误 | | gender | int | 否 | 性别：0-保密， 1-男， 2-女 |
| avatarId | string | 否 | 人员在蓝信里的头像 | | email | string | 否 | 电子邮箱地址, loginWays指定邮箱登录时不能为空，组织内唯一，和系统已有邮箱地址冲突时接口返回数据冲突错误 | | signature | string | 否 | 人员个人签名 | | nationality | string | 否 | 民族 | | birthdate | string | 否 | 出生日期。格式：year-month-day | | extraPhones | obj array | 否 | 附加联系方式 | | extraPhones.countryCode | string | 是 | 国家码 | | extraPhones.number | string | 是 | 电话号码 | | introduction | json obj | 否 | 个人介绍 | | introduction.introduction | string | 否 | 个人介绍-描述 | | introduction.mediaIds | string array | 否 | 个人介绍-图片 | | education | obj array| 否 | 受教育履历 | | education.unit |string | 否 | 教育机构名称 | | education.description |string | 否 | 受教育描述 | | education.startDate | string | 否 | 开始日期，日期格式：yyyy-mm-dd | | education.endData | string | 否 | 结束日期，日期格式：yyyy-mm-dd | | career | obj array | 否 | 工作简历 | | career.unit | string | 否 | 工作单位 | | career.description | string | 否 | 工作描述 | | career.startDate | string | 否 | 开始日期，日期格式：yyyy-mm-dd | | career.endData | string | 否 | 结束日期，日期格式：yyyy-mm-dd | | idNumber | string | 否 | 身份证号 |
| nativePlace | string | 否 | 籍贯 | | duties | string | 否 | 职务 |
| parties | string | 否 | 党派 |
| extraFieldSet | map obj | 否 | k和v都是string.自定义扩展属性，k代表扩展字段ID，这个ID由蓝信管理后台预定义，应用可以通过以下接口获取获取组织预定义的人员扩展字段ID列表。 |
| tags | string array | 否 | 人员标签信息 |
| externalId | string | 否 | 人员外部ID，组织通讯录数据源唯一标识人员的ID。注意，如果是账号密码方式登录蓝信，应该使用loginName字段。如果是手机号方式登录蓝信，又想保留组织内的人员唯一ID，可以使用该externalId 字段。externalId 和 employeeNumber类似，用于组织内人员的唯一标识。创建后不可修改，组织内必须唯一。 | | disablePasswordReset | bool | 否 | 账密登录方式，首次登录时是否禁用强制修改密码。 ; 禁用 - true ; 不禁用 - false (默认) |
| address| string | 否 | 人员(办公)地址 |

返回参数字段说明：|参数|类型|描述 | |----------|---------|--------------| | list | obj array | 人员创建状态返回值 | | list.errCode | int | 错误码 | | list.errMsg | string | 错误描述 | | list.staffId | string | 人员ID |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
   "data": {
      "list": [
            {
                "errCode": 10000,
                "errMsg": "内部错误",
                "staffid": ""
            },{
                "errCode": 0,
                "errMsg": "ok",
                "staffid": "8182980-111111xxjkdkdd"
            }
        ]
   }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取人员基本信息

接口说明：可以获人员的基本信息。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/staffs/:staffid/fetch?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	应用访问 TOKEN
user_token	否	非必填字段，人员TOKEN

param 参数说明：

参数	必须	说明
staffid	是	人员 ID

返回参数字段说明：|参数|类型|描述 |
|-------------|-----------|----------------------------------------------------------| | orgId | string | 人员组织ID |
| name | string | 人员姓名 |
| orgName | string | 人员组织名 |
| gender | int | 性别（可选值：0-保密；1-男；2-女；） |
| signature | string | 签名 |
| avatarUrl | string | 人员头像下载地址,一小时有效 |
| avatarId | string | 人员头像资源ID |
| status | int | 成员状态：0-未激活；1-已激活；2-已冻结；3-已删除；5-待删除； |
| departments | json obj | 所在分支信息 | | departments.id | string | 分支ID | | departments.name | string | 分支名称 | | departments.orderNumber | int | 分支在父分支的排序信息 |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
        "orgId": "788",
        "orgName":"组织名称",
        "name": "张三",
        "gender": 1,
        "signature": "生活是美好的",
        "avatarUrl": "http://路径",
        "avatarId":"788-3456",
        "status":  1,
        "departments": [                     
           {
             "id": "788-3145728",
             "name": "核心服务组"
             "orderNumber": 10
           }
        ]
    }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取人员详细信息

接口说明：通过此接口，可以获取人员详细信息。需要组织授权或者个人授权。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/staffs/:staffid/infor/fetch?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段，人员TOKEN

param 参数说明：

参数	必须	说明
staffid	是

返回参数字段说明：|参数|类型|描述 | | -------------- | ----------- | ------------------------------------------------------------ | | name | string | 人员姓名 | | signature | string | 人员个人签名 |
| avatarId | string | 人员在蓝信里的头像ID |
| avatarUrl | string | 人员在蓝信里的头像（url），一小时有效 |
| status | int | 成员状态：0-未激活；1-已激活；2-已冻结；3-已删除；5-待删除 | | departments | obj array| 人员所在分支列表 | | departments.id | string | 分支ID | | departments.name | string | 分支名称 | | departments.orderNumber | int | 人员在分支里的排序 | | departments.order | float | 人员在分支里的排序-旧版本字段，不建议使用 | | tags | string array | 人员标签信息 |
| gender | int | 性别：0-保密；1-男；2-女； |
| orgId | string | 人员所在组织ID |
| orgName | string | 人员所在的组织名称 |
| loginName | string | 特别说明：如果添加的用户使用手机号登录蓝信，则不能填充该字段。添加用户登录蓝信如果使用账户密码方式，该字段为登录蓝信时的账户名，创建后不可修改，组织内必须唯一。返回值包含组织标识。| | employeeNumber | string | 人员号 |
| email | string | 电子邮箱地址 |
| nationality | string | 民族 |
| birthdate | string | 出生日期 |
| mobilePhone | json obj | 手机号码，组织内必须唯一。若成员已激活蓝信，则需成员自行修改（此情况下该参数被忽略，但不会报错） | | mobilePhone.countryCode | string | 国家码 | | mobilePhone.number | string | 手机号 | | extraPhones | obj array | 附加联系方式 | | extraPhones.countryCode | string | 国家码 | | extraPhones.number | string | 电话号码 | | introduction | json obj | 个人介绍 | | introduction.introduction | string | 个人介绍-描述 | | introduction.mediaIds | string array | 个人介绍-图片 | | education | obj array| 受教育履历 | | education.unit |string | 教育机构名称 | | education.description |string | 受教育描述 | | education.startDate | string | 开始日期，日期格式：yyyy-mm-dd | | education.endData | string | 结束日期，日期格式：yyyy-mm-dd | | career | obj array | 工作简历 | | career.unit | string | 工作单位 | | career.description | string | 工作描述 | | career.startDate | string | 开始日期，日期格式：yyyy-mm-dd | | career.endData | string | 结束日期，日期格式：yyyy-mm-dd | | idNumber | string | 身份证号 |
| nativePlace | string | 籍贯 |
| duties | string | 职务 |
| parties | string | 党派 |
| loginWays | int array | 蓝信登录方式：0-手机号；1-邮箱；2-账密； | | address | string | 人员(办公)地址 | | externalId | string | 人员外部ID，组织通讯录数据源唯一标识人员的ID |
| extraFieldSet | map obj | k和v都是string，自定义扩展属性，k代表扩展字段id。 |

返回数据示例：

业务正常返回：

{
    "orgId":"524288-xxxxxxxx",
    "orgName": "测试组织",
    "name": "张三",
    "loginName": "xxxx",
    "employeeNumber": "xxxx"
    "gender": 1 ,
    "avatarId":"345678-xxxxxxx",
    "avatarUrl":"https://...",
    "email": "zhangsan@test.com" ,
    "signature":"生活要精彩",
    "nationality": "汉族",
    "birthdate": "1999-09-09",
    "idNumber":"130424xxxxxxxxxxxx",
    "nativePlace":"xxxxxx",
    "duties":"组长",
    "parties":"共产党",
    "tags": ["524288-xxxxxxxxx", "524288-xxxxxxxx"],
    "status":1,
    "mobilePhone": {
        "countryCode": "86",
        "number": "12345678902"
    },
    "extraPhones":[
        {
         "countryCode": "86",
         "number": "13811111111"
        },
        {
         "countryCode": "86",
         "number": "13822222222"
        }
    ],
    "departments":[
        {
            "id": "12345-xxxxxxxx" ,
            "name":"分支1",
            "orderNumber": 10,
            "order": 10
        },
        {
            "id": "12345-xxxxxxxx" ,
            "name":"分支2",
            "orderNumber": 40,
            "order": 40
        }
    ],
    "introduction":{
        "introduction":"something about introduction"
        "mediaIds":["524288-xxxxxxxxxxxxx","524288-xxxxxxxxxxxxx"]
    },
    "education":[
        {
            "unit":"学校名称1",
            "description":"something about description",
            "startDate":"2014-8-12",
            "endData":"2016-8-12"
        },
        {
            "unit":"学校名称2",
            "description":"something about description",
            "startDate":"2016-8-12",
            "endData":"2019-8-12"

        }
    ],
    "career":[
        {
            "unit":"公司名称1",
            "description":"something about description",
            "startDate":"2014-8-12",
            "endData":"2016-8-12"
        },
        {
            "unit":"公司名称2",
            "description":"something about description",
            "startDate":"2016-8-12",
            "endData":"2019-8-12"
        }
    ],
    "extraFieldSet":{
        "524288-xxxxxxxxxxxx": "mail@test.net" ,
        "524288-xxxxxxxxxxxx": "xxxxx",
        "524288-xxxxxxxxxxxx": "xxxxx",
        "524288-xxxxxxxxxxxx": ""
    },
    "loginWays":[0],
    "address": "人员(办公)地址",
    "externalId":"A0001"
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

更新人员

接口说明：通过此接口，可以更新人员信息。仅组织内应用经过授权可以调用该接口。特别说明：如果涉及人员的部门信息更新，目前蓝信不支持应用并发调用人员更新接口，否则会出现更新人员部门的操作失败，应用需要保证串行化调用该接口。已支持批量人员更新接口，大量集中进行人员同步时建议使用批量接口。更新人员-批量请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/staffs/:staffid/update?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段，人员TOKEN

param 参数说明：

参数	必须	说明
staffid	是	人员ID

请求数据示例：

{
    "name": "张三",
    "loginName": "xxxx",
    "employeeNumber": "xxxx",
    "gender": 1 ,
    "avatarId":"345678-999",
    "email": "zhangsan@test.com" ,
    "signature":"生活要精彩",
    "nationality": "汉族",
    "birthdate": "1999-09-09",
    "status":1,
    "mobilePhone": {
        "countryCode": "86",
        "number": "12345678902"
    },
    "extraPhones":[
        {
         "countryCode": "86",
         "number": "13811111111"
        },
        {
         "countryCode": "86",
         "number": "13822222222"
        }
    ],
    "departments":[
        {
            "id": "12345-xxxxxxxx" ,
            "orderNumber": 0
        },
        {
            "id": "12345-xxxxxxxx" ,
            "orderNumber": 40
        }
    ],
    "idNumber":"130424xxxxxxxxxxxx",
    "nativePlace":"xxxxxx",
    "duties":"组长",
    "parties":"共产党",
    "extraFieldSet":{
        "524288-xxxxxxxxxxxx": "mail@test.net" ,
        "524288-xxxxxxxxxxxx": "xxxxx",
        "524288-xxxxxxxxxxxx": "xxxxx",
        "524288-xxxxxxxxxxxx": ""
    },
    "tags": ["12345-xxxxxxxxx","12345-xxxxxxx"],
    "address":"北京市",
    "externalId": ""
}

请求参数字段说明：|参数|类型|必须|说明 |
|----------------|-------------|----------------------------------|---------------------------------------------------| | departments | obj array | 是 | 人员所在分支 | | departments.id | string | 是 | 分支Id | | departments.orderNumber| int | 否 | 人员在分支里的排序。排序不确定时可填0，服务端为忽略0值，有效值从1开始 | | name | string | 否 | 人员姓名 |
| loginName | string | 否 | 人员使用人员名登录蓝信时的人员名，也称staffId。可由组织在创建时指定，并代表一定含义比如工号，创建后不可修改，组织内必须唯一。 |
| employeeNumber | string | 否 | 人员号 |
| gender | int | 否 | 性别：0-保密， 1-男， 2-女 |
| avatarId | string | 否 | 人员在蓝信里的头像 |
| email | string | 否 | 电子邮箱地址 |
| signature | string | 否 | 签名 |
| nationality | string | 否 | 民族 |
| birthdate | string | 否 | 出生日期。格式：yyyy-mm-dd |
| status | int | 否 | 成员状态, 更新时允许值：NORMAL= 1, 已注册; FROZEN = 2, 冻结 |
| mobilePhone | json obj | 否 | 手机号码，组织内必须唯一。若人员已激活蓝信，且登录方式为手机号，则需人员自行修改（此情况下接口返回“人员登录唯一键值不允许修改”错误） |
| mobilePhone.countryCode | string | 是 | 国家码 |
| mobilePhone.number | string | 是 | 手机号 |
| extraPhones | obj array | 否 | 附加联系方式 | | extraPhones.countryCode | string | 是 | 国家码 | | extraPhones.number | string | 是 | 电话号码 | | introduction | json obj | 否 | 个人介绍 | | introduction.introduction | string | 否 | 个人介绍-描述 | | introduction.mediaIds | string array | 否 | 个人介绍-图片 | | education | obj array| 否 | 受教育履历 | | education.unit |string | 否 | 教育机构名称 | | education.description |string | 否 | 受教育描述 | | education.startDate | string | 否 | 开始日期，日期格式：yyyy-mm-dd | | education.endData | string | 否 | 结束日期，日期格式：yyyy-mm-dd | | career | obj array | 否 | 工作简历 | | career.unit | string | 否 | 工作单位 | | career.description | string | 否 | 工作描述 | | career.startDate | string | 否 | 开始日期，日期格式：yyyy-mm-dd | | career.endData | string | 否 | 结束日期，日期格式：yyyy-mm-dd |
| idNumber | string | 否 | 身份证号 |
| nativePlace | string | 否 | 籍贯 |
| duties | string | 否 | 职务 |
| parties | string | 否 | 党派 |
| extraFieldSet | map obj | 否 | 自定义扩展属性，k和v都是string，k代表扩展字段ID。所有扩展字段是一个整体，更新时需要整体更新。 |
| tags | string array| 否 | 人员标签信息，不填该字段时不修改人员标签，填空数组时会将人员标签全部删除。 |
| address | string | 否 | 人员(办公)地址 | | externalId | string | 否 | 人员外部ID，组织通讯录数据源唯一标识人员的ID。注意，如果是账号密码方式登录蓝信，应该使用loginName字段。如果是手机号方式登录蓝信，又想保留组织内的人员唯一ID，可以使用该externalId 字段。externalId 和 employeeNumber类似，用于组织内人员的唯一标识。创建后不可修改，组织内必须唯一。|

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

更新人员-批量

接口说明：通过此接口，可以批量更新人员信息。仅企业内应用经过授权可以调用该接口特别说明：如果涉及人员的部门信息更新，目前蓝信不支持应用并发调用人员更新接口，否则会出现更新人员部门的操作失败，应用需要保证串行化调用该接口。单次更新人数上限32个

请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/staffs/batch/update?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段, 人员TOKEN

请求数据示例：

{
    "users":[
        {
            "staffId":"54288-ghejkddnds6782ncjjd",
            "name":"李四",
            "loginName":"xxxx",
            "employeeNumber":"xxxx",
            "gender":1,
            "avatarId":"345678-999",
            "email":"zhangsan@a.com",
            "signature":"生活要精彩",
            "nationality":"汉族",
            "birthdate":"1999-09-09",
            "status":1,
            "mobilePhone":{
                "countryCode":"86",
                "number":"12345678902"
            },
            "extraPhones":[
                {
                    "countryCode":"86",
                    "number":"13811111111"
                },
                {
                    "countryCode":"86",
                    "number":"13822222222"
                }
            ],
            "departments":[
                {
                    "id":"12345-xxxxxxxx",
                    "orderNumber":0
                },
                {
                    "id":"12345-xxxxxxxx",
                    "orderNumber":40
                }
            ],
            "idNumber":"130424xxxxxxxxxxxx",
            "nativePlace":"xxxxxx",
            "duties":"组长",
            "parties":"共产党",
            "extraFieldSet":{
                "524288-xxxxxxxxxxxx":""
            },
            "tags":[
                "12345-xxxxxxxxx",
                "12345-xxxxxxx"
            ],
            "address":"北京市朝阳区酒仙桥",
            "externalId": ""
        },
        {
            "staffId":"54288-ghejkddneeeds6782ncjjd",
            "name":"张三",
            "loginName":"xxxx",
            "employeeNumber":"xxxx",
            "gender":1,
            "avatarId":"345678-999",
            "email":"zhangsan@a.com",
            "signature":"生活要精彩",
            "nationality":"汉族",
            "birthdate":"1999-09-09",
            "status":1,
            "mobilePhone":{
                "countryCode":"86",
                "number":"12345678902"
            },
            "extraPhones":[
                {
                    "countryCode":"86",
                    "number":"13811111111"
                },
                {
                    "countryCode":"86",
                    "number":"13822222222"
                }
            ],
            "departments":[
                {
                    "id":"12345-xxxxxxxx",
                    "orderNumber":0
                },
                {
                    "id":"12345-xxxxxxxx",
                    "orderNumber":40
                }
            ],
            "idNumber":"130424xxxxxxxxxxxx",
            "nativePlace":"xxxxxx",
            "duties":"组长",
            "parties":"共产党",
            "extraFieldSet":{
                "524288-xxxxxxxxxxxx":""
            },
            "tags":[
                "12345-xxxxxxxxx",
                "12345-xxxxxxx"
            ],
            "address":"北京市朝阳区酒仙桥",
            "externalId": ""
        }
    ]
}

请求参数字段说明：|参数|类型|必须|说明 | |----------------|-------------|-----------------------------|---------------------------------| | users | array | 是 | 待更新用户集合，**单次更新用户上限32个 |
| staffId | string | 是 | 员工唯一ID，通过创建接口返回 |
| departments | obj array | 是 | 人员所在分支 | | departments.id | string | 是 | 分支ID | | departments.orderNumber| int | 否 | 人员在分支里的排序。排序不确定时可填0，服务端为忽略0值，有效值从1开始 | | name | string | 否 | 人员姓名 |
| loginName | string | 否 | 人员使用人员名登录蓝信时的人员名，也称staffId。可由组织在创建时指定，并代表一定含义比如工号，创建后不可修改，组织内必须唯一。 |
| employeeNumber | string | 否 | 人员号 |
| gender | int | 否 | 性别：0-保密， 1-男， 2-女 |
| avatarId | string | 否 | 人员在蓝信里的头像 |
| email | string | 否 | 电子邮箱地址 |
| signature | string | 否 | 签名 |
| nationality | string | 否 | 民族 |
| birthdate | string | 否 | 出生日期。格式：yyyy-mm-dd |
| status | int | 否 | 成员状态, 更新时允许值：NORMAL= 1, 已注册; FROZEN = 2, 冻结 |
| mobilePhone | json obj | 否 | 手机号码，组织内必须唯一。若人员已激活蓝信，且登录方式为手机号，则需人员自行修改（此情况下接口返回“人员登录唯一键值不允许修改”错误） |
| mobilePhone.countryCode | string | 是 | 国家码 |
| mobilePhone.number | string | 是 | 手机号 |
| extraPhones | obj array | 否 | 附加联系方式 | | extraPhones.countryCode | string | 是 | 国家码 | | extraPhones.number | string | 是 | 电话号码 | | introduction | json obj | 否 | 个人介绍 | | introduction.introduction | string | 否 | 个人介绍-描述 | | introduction.mediaIds | string array | 否 | 个人介绍-图片 | | education | obj array| 否 | 受教育履历 | | education.unit |string | 否 | 教育机构名称 | | education.description |string | 否 | 受教育描述 | | education.startDate | string | 否 | 开始日期，日期格式：yyyy-mm-dd | | education.endData | string | 否 | 结束日期，日期格式：yyyy-mm-dd | | career | obj array | 否 | 工作简历 | | career.unit | string | 否 | 工作单位 | | career.description | string | 否 | 工作描述 | | career.startDate | string | 否 | 开始日期，日期格式：yyyy-mm-dd | | career.endData | string | 否 | 结束日期，日期格式：yyyy-mm-dd |
| idNumber | string | 否 | 身份证号 |
| nativePlace | string | 否 | 籍贯 |
| duties | string | 否 | 职务 |
| parties | string | 否 | 党派 |
| extraFieldSet | map obj | 否 | 自定义扩展属性，k和v都是string，k代表扩展字段ID。所有扩展字段是一个整体，更新时需要整体更新。 |
| tags | string array | 否 | 人员标签信息，不填该字段时不修改人员标签，填空数组时会将人员标签全部删除。 |
| address | string | 否 | 人员(办公)地址 | | externalId | string | 否 | 人员外部ID，组织通讯录数据源唯一标识人员的ID。注意，如果是账号密码方式登录蓝信，应该使用loginName字段。如果是手机号方式登录蓝信，又想保留组织内的人员唯一ID，可以使用该externalId 字段。externalId 和 employeeNumber类似，用于组织内人员的唯一标识。创建后不可修改，组织内必须唯一。|

返回数据示例：

业务正常返回：

{
    "errCode":0,
    "errMsg":"ok",
    "data":{
        "infos":[
            {
                "errCode":0,
                "errMsg":"ok"
            },
            {
                "errCode":500,
                "errMsg":"更新失败"
            }
        ]
    }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

删除人员

接口说明：删除人员，仅组织内应用经过授权可以调用该接口。特别说明：目前蓝信不支持应用并发调用人员删除接口，否则会出现从部门中删除人员操作失败，应用需要保证串行化调用该接口

请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/staffs/:staffid/delete?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段，人员TOKEN

param 参数说明：

参数	必须	说明
staffid	是	人员openId

业务正常返回： 返回数据示例：

{
  "errCode":0 ,
  "errMsg":"ok"
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

搜索人员

接口说明：根据姓名、手机号等信息搜索人员，一般用于选人控件快速定位人员。V2版本搜索人员接口支持按分支限定搜索范围，在指定的分支范围内搜索人员。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v2/staffs/search?app_token=APP_ACCESS_TOKEN&user_token=USER_TOKEN&user_id=USER_ID&page=PAGE&page_size=PAGE_SIZEquery参数说明：

参数	必须	说明
app_token	是	应用访问 TOKEN
user_token	否	人员访问 TOKEN，和user_id二者中必须选填一个
user_id	否	当前人员的openid，和user_token二者中必须选填一个
page	否	查询结果分页，须同page_size同时出现
page_size	否	查询一次结果返回数量，须同page同时出现，最大值为100，超过100按100处理

body参数说明：

参数	类型	必须	说明
keyword	string	是	搜索所使用的关键字
recursive	bool	否	是否递归检索，如果指定搜索范围的部门ID，决定是否需要从指定的分支做子部门递归搜索，false:只搜索指定的分支ID的直属成员，true:搜索指定的分支及其子分支成员
searchScope	json obj	否	搜索范围
searchScope.sectorIds	string array	否	搜索范围，部门的openId列表，用于限定搜索范围，根分支使用 “xxxxx-0”格式，例如：524288-0，不填该字段时在user_id或user_token指定的访问者所在的组织范围内搜索

请求数据示例：

{
    "keyword":"keyword",
    "recursive":true,
    "searchScope":{
        "sectorIds":[
            "524288-rtyuifhjkrtyuifghjkf",
            "524288-cvbnfghrtyfghjfghjk"
        ]
    }
}

返回参数字段说明：|参数 |类型|描述 | |------------|---------|--------------------| | hasMore | bool | 是否还有更多数据 | | total | int | 总数量 | | staffInfo | obj array| 返回的人员信息列表 | | staffInfo.staffId | string | 人员的ID | | staffInfo.name | string | 人员的姓名 | | staffInfo.email | string | 人员的email | | staffInfo.mobilePhone| json obj | 人员的手机号 | | staffInfo.mobilePhone.countryCode | string | 国家码 | | staffInfo.mobilePhone.number | string | 手机号 |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data":{
        "hasMore": false,
        "total":1000,
        "staffInfo": [
            {
                "staffId": "524288-yvuPH2Jg7A7HgKAgfv2YJaI1bB",
                "name": "NAME",
                "email": "xxxxx@test.com",
                "mobilePhone":{
                    "countryCode": "86,"
                    "number": "18123456789"
                }
            }
        ]
    }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取人员分支祖先列表

接口说明：获取某个人员所在的所有分支的祖先列表。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/staffs/:staffid/departmentancestors/fetch?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段，人员TOKEN

param 参数说明：

参数	必须	说明
staffid	是	人员openId

返回参数字段说明：|参数 |类型|描述 | |---------------------|------------------------|------------------------| | data | obj array | 人员所在多个分支的祖先分支列表 | | ancestorDepartments | obj array |人员所在某个分支的祖先分支列表，从前到后的顺序是父分支到根分支 | | ancestorDepartments.departmentId | string |分支Id | | ancestorDepartments.name | string |分支名称 | | ancestorDepartments.externalId | string |部门数据源Id |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": [{
            "ancestorDepartments": [{
                    "departmentId": "123-xxxsxxxx",
                    "name": "department name",
                    "externalId": ""
                },
                {
                    "departmentId": "123-xxxxxx",
                    "name": "partent department",
                    "externalId": ""
                },
                {
                    "departmentId": "123-xxxxx",
                    "name": "root department",
                    "externalId": ""
                }
            ]

        },
        {
            "ancestorDepartments": [{
                    "departmentId": "123-xxxxxx",
                    "name": "department name",
                    "externalId": ""
                },
                {
                    "departmentId": "123-xxxxxx",
                    "name": "root department",
                    "externalId": ""
                }
            ]

        },
        {
            "ancestorDepartments": [{
                "departmentId": "123-xxxxxx",
                "name": "root department"
            }]

        }
    ]
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

通过唯一标识获取人员ID

接口说明：通过人员的几种唯一标识获取人员的ID，目前支持根据手机号，邮箱地址，人员号获取人员ID。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v2/staffs/id_mapping/fetch?app_token=APP_TOKEN&org_id=ORG_ID&id_type=ID_TYPE&id_value=ID_VALUEquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段，人员TOKEN
org_id	是	查询人员所在的组织ID
id_type	是	通过某个ID的内置类型查询人员staffId，目前支持以下几种查询类型（枚举）：; employ_id – 人员编号（一般是HR系统的人员唯一编号） ; mobile – 手机号, 对应id_value格式为xx-137xxxxxx, 示例：86-13723129089 ; mail –邮箱地址 ; login –账密方式登录蓝信时的人员登录账户名 ; external_id –人员数据源外部唯一ID
id_value	是	id_type 对应的值：人员编号，手机号，邮箱地址，登录账户名(需要携带组织标识使用@连接,例如：zzbs@zhangsan)，人员外部ID

返回参数字段说明：|参数|类型|描述 | |----------|---------|-------------| | staffId | string |人员staffId |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
        "staffId": "524288-akdjflajdj"
    }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

通过标签获取人员的ID列表

接口说明：在组织内，通过指定标签过滤规则来筛选目标人员。 EMC管理后台和开放平台接口都提供关于标签的创建、修改、删除、给人员添加标签等功能，开发人员可以调用开放平台接口获取到已创建的所有标签分组，然后根据指定的分组ID再获取到该分组下的所有标签。; 参见接口：获取标签分组列表, 获取标签分组详情请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/tags/staffids/fetch?app_token=APP_TOKEN&page=PAGE_OFFSET&page_size=PAGE_SIZEquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段, 人员TOKEN
page	否	支持分页，起始页码从1开始。默认值为1
page_size	否	每页显示个数，默认值是1000，最大值是100000。

body 参数说明：

参数	类型	必须	说明
orgId	string	是	组织ID
tagFilters	filter array	是	过滤器。多个过滤器之间是“与”操作的关系。目前仅支持一个过滤器
tagFilters.tags	string array	是	tag数组。数组内的tag之间是“或”操作的关系。目前仅支持一个tag

请求参数示例：

{
    "orgId": "524288",
    "tagFilters": [
        {
            "tags": [
                "524288-xxxxxxxx",
            ]
        }
    ]
}

返回参数字段说明：|参数|类型|描述 | |----------|----------|--------------------------------| | hasMore | bool | 标识是否还有下一页 | | total | int | 总个数。并非某次返回结果的个数 | | staffs | obj array| 人员的ID列表 | | staffs.id| string | 人员ID |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
  "data":{
    "hasMore": false,
    "total":1000,
    "staffs": [
        {
            "id":"524288-abcdefg"
        }     
    ]
  }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取通讯录扩展字段ID列表

接口说明：获取组织内通讯录的扩展字段ID列表。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/org/:orgid/extrafieldids/fetch?app_token=APP_TOKEN&page=PAGE_OFFSET&page_size=PAGE_SIZEquery参数说明：

参数	必须	说明
app_token	是	应用访问TOKEN
user_token	否	非必填字段，人员TOKEN
page	否	支持分页，起始页码从1开始。默认值为1
page_size	否	每页显示个数，默认值是1000，最大值是100000。

param 参数说明：

参数	必须	说明
orgid	是	组织ID

返回参数字段说明：|参数|类型|描述 |版本依赖| |----------|----------|-------------------------------------------------------------------|-----| | hasMore | bool | 标识是否还有数据 |v1.0.0| | total | int | 总记录数。不是某一次返回的记录数 |v1.0.0| | extraFieldIds | obj array | 组织通讯录扩展字段对象列表 |v1.0.0| | extraFieldIds.id | string | 扩展字段ID |v1.0.0| | extraFieldIds.name | string | 字段名称 |v1.0.0| | extraFieldIds.category | int | 扩展字段业务类型, 0：未定义，1：人员属性，2：分支成员属性，3：分支属性 |v1.0.0| | extraFieldIds.type | string | 扩展字段数据类型, “staff”, "group", "groupMember","account","org", "sector","article","text", "phone","url","mail","date","image","path"|v2.12.0|

返回数据示例：

业务正常返回：


{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
        "hasMore":true,
        "total":1000,
        "extraFieldIds":[
            {
                "id":"524288-xxxxxxxxxxx",
                "name": "fieldName1",
                "category": 1,
                "type": "staff"
            },
            {
                "id":"524288-xxxxxxxxxxx",
                "name": "fieldName2",
                "category": 1,
                "type": "date"
            }
        ]
    }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

💬 即时通讯

🤝 业务协同

📦 AI产品

📦 其他产品

openplatform

通讯录 - 人员管理

创建人员

创建人员-批量

获取人员基本信息

获取人员详细信息

更新人员

更新人员-批量

删除人员

搜索人员

获取人员分支祖先列表

通过唯一标识获取人员ID

通过标签获取人员的ID列表

获取通讯录扩展字段ID列表