通讯录 - 分支管理

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

创建分支

接口说明：创建分支。接口需要拥有对应的授权。仅组织内应用经过授权可以调用该接口。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/departments/create?app_token=APP_TOKENquery参数说明：

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

请求数据示例：

{
   "name": "基础服务部",
   "parentId": "522-5435",
   "externalId": "branch01",
   "orderNumber": 1,
   "tags" : ["xxx-tagid1", "xxx-tagid1"]
}

请求参数字段说明：|参数|类型 |必须|说明 | |-------------|----------|----------|--------------------------------------------------------------------------| | name | string | 是 | 分支名称，名称前后不允许有ASCII定义的空格（空格可以出现在中间），系统会自动清除名称前后的空格并完成部门创建。 | | parentId | string | 是 | 父节点分支ID，根分支可以用”组织ID-0“代替，例如：524288-0，创建根分支的时候需要指定组织，创建其他子分支的时候根据父分支决定组织。 | | externalId | string | 否 | 分支外部ID，组织通讯录数据源唯一标识分支的ID。创建后不可修改，组织内必须唯一 | | orderNumber | int | 否 | 在父分支中的次序值，值越小排序越靠前 | | tags | string array | 否 | 分支标签 |

返回参数字段说明：|参数 |类型|描述 | |------------|----------|----------| | department | json obj | 分支信息 | | department.id | string | 分支Id |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
   "data": {
     "department": {
           "id":"543-7654"
     }
   }
}

业务异常返回：

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

对应可能的错误码说明：

接口错误码

获取分支详情

接口说明：获取分支详情信息。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/departments/:departmentid/fetch?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数	必须	说明
departmentid	是	分支open ID，根分支使用 “xxxxx-0”格式，例如：524288-0

返回参数字段说明：|参数|类型|描述|版本依赖| |---------------------|-----|--------------------------------|------| | id | string | 分支ID |v1.0.0| | name | string | 分支名称 |v1.0.0| | externalId | string | 分支外部ID，组织通讯录数据源唯一标识分支的ID|v1.0.0| | order | float | 分支顺序，越小排在越前面 |v1.0.0| | inactiveMembers | int | 未注册人员数，包含所有子分支人员，不会按人员ID销重，一个人如果在两个不同子部门，计数为2 |v1.0.0| | normalMembers | int | 已注册人员数，包含所有子分支人员，不会按人员ID销重，一个人如果在两个不同子部门，计数为2 |v1.0.0| | frozenMembers | int | 已冻结人员数，包含所有子分支人员，不会按人员ID销重，一个人如果在两个不同子部门，计数为2 |v1.0.0| | deletedMembers | int | 已删除人员数，包含所有子分支人员，不会按人员ID销重，一个人如果在两个不同子部门，计数为2 |v1.0.0| | inactiveMembersUnique|int | 未注册人员数，包含所有子分支人员，消重后计数 |v2.11.0| | normalMembersUnique | int | 已注册人员数，包含所有子分支人员，消重后计数 |v2.11.0| | frozenMembersUnique | int | 已冻结人员数，包含所有子分支人员，消重后计数 |v2.11.0| | deletedMembersUnique| int | 已删除人员数，包含所有子分支人员，消重后计数 |v2.11.0| | hasChildren | bool | 是否有子分支 |v1.0.0| | parentId | string | 父分支ID，没有代表当前为根分支 |v1.0.0| | tags | string array | 该分支所持有的全部标签ID列表 |v1.0.0| | ancestorDepartments | obj array| 分支祖先列表，由父到根分支 |v1.0.0| | ancestorDepartments.id | string | 分支ID |v1.0.0| | ancestorDepartments.name | string | 分支名称 |v1.0.0| | extraFieldSet | map obj | 分支扩展属性，k是string类型，v是string array 类型。k为扩展字段Id，通过获取通讯录扩展字段接口获得。v是人员Id列表。目前分支扩展字段仅支持部门领导扩展字段。|v4.0.0|

返回数据示例：

业务正常返回：

{
    "errCode":0 ,
    "errMsg":"ok",
    "data": {
        "id":"524288-xxxxxdefg",
        "name":"department name",
        "externalId": "branch01",
        "order":11.3,
        "inactiveMembers":0,
        "normalMembers":100,
        "frozenMembers":0,
        "deletedMembers":0,
        "inactiveMembersUnique":0,
        "normalMembersUnique":50,
        "frozenMembersUnique":0,
        "deletedMembersUnique":0,
        "partentId":"524288-aaacdefg",
        "hasChildren": true,
        "tags":["xxxx","xxxxx"],
        "ancestorDepartments": [
            {
                "id":"524288-aaacdefg" ,
                "name":"parent department"
            },
            {
                "id":"524288-cccdefg" ,
                "name":"ancestors department"
            },
            {
                "id":"524288-dddefg" ,
                "name":"root department"
            }
        ],
        "extraFieldSet": {
            "524288-abcdefghigklmn": [
                "524288-bcdabcefghigk"
            ]
        }
    }
}

业务异常返回：

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

对应可能的错误码说明： 接口错误码

更新分支

接口说明：更新分支信息，接口需要拥有授权。仅组织内应用经过授权可以调用该接口。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/departments/:departmentid/update?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数	必须	说明
departmentid	是	分支ID

请求数据示例：

{
    "name": "基础中心",
    "orderNumber": 1,
    "tags" : ["xxx-tagid1", "xxx-tagid1"],
    "extraFieldSet":{
        "524288-fieldKeyId1": ["524288-staffOpenId1"]
    }
}

请求参数字段说明：|参数|类型 |必须|说明|版本依赖| |--------------|----------|----------|--------------------------------------------|--------| | name | string | 否 | 分支名称 |v1.0.0| | orderNumber | int | 否 | 在父分支中的次序值，值越小排序越靠前 |v1.0.0| | tags | string array | 否 | 分支标签，必须获取后整体更新，不支持增量更新 |v1.0.0| | extraFieldSet| map obj | 否 | 分支扩展属性，k是string类型，v是string array 类型。k为扩展字段ID，通过获取通讯录扩展字段接口获得。v是人员ID列表。目前分支扩展字段仅支持部门领导扩展字段。 |v4.0.0|

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明：

接口错误码

删除分支

接口说明：删除分支。仅组织内应用经过授权可以调用该接口。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/departments/:departmentid/delete?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数	必须	说明
departmentid	是	分支 ID

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明：

接口错误码

获取子分支列表

接口说明：获取子分支列表，只获取一层。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/departments/:departmentid/children/fetch?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数	必须	说明
departmentid	是	父分支ID，根分支使用 “xxxx-0”，例如：524288-0

返回参数字段说明：|参数 |类型|描述 | |----------------------|---|----------------| | departments | obj array | 子分支列表| | departments.id |string | 分支ID | | departments.name |string | 分支名称 | | departments.externalId |string | 分支外部ID | | departments.membersCount|int | 分支成员人数 | | departments.ancestorDepartments | obj array | 分支祖先列表，从前到后的顺序是从父分支到根分支 | | departments.ancestorDepartments.id | string | 分支ID | | departments.ancestorDepartments.name | string | 分支名称 |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
  "data":{
    "departments": [
        {
            "id":  "524288-abcdefg",
            "name": "child_department_1",           
            "externalId": "branch00",
            "hasChildren": true,
            "membersCount":100,
            "ancestorDepartments": [
                {
                    "id":"524288-aaacdefg",
                    "name":"parent department",
                },
                {
                    "id":"524288-cccdefg",
                    "name":"ancestors department",
                },
                {
                    "id":"524288-dddefg",
                    "name":"root department",
                }
            ]
        },
        {
            "id":  "524288-abcdefg",
            "name": "child_department_2",
            "hasChildren": false,
            "membersCount":10
            "ancestorDepartments": [
                {
                    "id":"524288-aaacdefg",
                    "name":"parent department",
                },
                {
                    "id":"524288-cccdefg",
                    "name":"ancestors department",
                },
                {
                    "id":"524288-dddefg",
                    "name":"root department",
                }
            ]
        }
    ]
  }
}

业务异常返回：

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

对应可能的错误码说明： 接口错误码

获取分支成员列表

接口说明：根据分支ID 获取分支成员列表，目前只返回当前分支下的成员，不含子分支的成员。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/departments/:departmentid/staffs/fetch?app_token=APP_TOKEN&page=PAGE_OFFSET&page_size=PAGE_SIZEquery参数说明：

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

param 参数说明：

参数	必须	说明
departmentid	是	父分支ID，根分支使用 “xxxxx-0”格式，例如：524288-0

返回参数字段说明：|参数|类型|描述 | |---------------------|----------|----------------------------------------------------------| | hasMore | bool | 时候还有下一页 | | total | int | 总数，并非某次请求返回的数量 | | staffs | obj array| 分支成员列表 | | staffs.id | string | 人员的openId |
| staffs.name | string | 人员名字 |
| staffs.externalId | string | 人员外部ID, 组织通讯录数据源标识人员的ID | | staffs.mobilePhone | json obj | 手机号 |
| staffs.mobilePhone.countryCode| string | 国家码 | | staffs.mobilePhone.number | string | 手机号 |
| staffs.email | string | 邮箱号 |
| staffs.orgId | int | 组织ID |
| staffs.orgName | string | 组织名字 |
| staffs.parentId | string | 所在分支ID |
| staffs.avatarId | string | 头像的openId |
| staffs.status | int | 成员状态 INACTIVE = 0;NORMAL = 1;FROZEN = 2;DELETED = 3; |
| staffs.ancestorDepartments | obj array | 分支祖先路径信息，由根到父分支 | | staffs.ancestorDepartments.id | string | 分支ID | | staffs.ancestorDepartments.name | string | 分支名称 |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
  "data":{
    "hasMore": false,
    "total":1000,
    "staffs": [
        {
            "id":"524288-abcdefg",
            "name":"zhang san",
            "externalId": "zhangsan",
            "mobilePhone": {
                "countryCode":"86",
                "number":"18280338510"
            },
            "email":"abc@test.com",
            "orgId":524288,
            "orgName":"lanxin",
            "parentId":"524288-aabbccas",
            "avatarId":"524288-adjkjd",
            "status":1,
            "ancestorDepartments": [
            {
               "id":"524288-aabbccas" ,
               "name":"parent department"
            },
            {
               "id":"524288-bbbbbbkjkjl" ,
               "name":"ancestors department"
            },
            {
               "id":"524288-ccccbbkjkjl" ,
               "name":"root department"
            }]
        }     
    ]
  }
}

业务异常返回：

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

对应可能的错误码说明： 接口错误码

添加分支成员

接口说明：为指定分支添加成员。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/departments/:departmentid/staffs/:staffid/create?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数	必须	说明
departmentid	是	分支ID
staffid	是	人员ID

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明： 接口错误码

删除分支成员

接口说明：删除分支成员。仅组织内应用经过授权可以调用该接口。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/departments/:departmentid/staffs/:staffid/delete?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数	必须	说明
departmentid	是	分支ID
staffid	是	人员ID

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明：

接口错误码

移动分支

接口说明：移动分支，修改分支的父分支ID。接口需要拥有对应的授权，仅组织内应用经过授权可以调用该接口。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/departments/parent/update?app_token=APP_TOKENquery参数说明：

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

请求数据示例：

{
    "departmentId":"524288-aaaabbbb",
    "newParentId":"524288-dddddeeeee"
}

请求参数字段说明：|参数|类型|必须|说明 | |----------------|----------|------|--------------------------| | departmentId | string | 是 | 被移动分支的分支ID | | newParentId | string | 是 | 分支移动后新的父分支ID，将被移动的分支ID移动到该分支ID下。应用数据授权范围需要有该分支的权限 |

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明：

接口错误码

💬 即时通讯

🤝 业务协同

📦 AI产品

📦 其他产品

openplatform

通讯录 - 分支管理

创建分支

获取分支详情

更新分支

删除分支

获取子分支列表

获取分支成员列表

添加分支成员

删除分支成员

移动分支