openplatform

首页 / 开放平台 / 服务端 API / 服务端 API 概览

通讯录 - 标签管理

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

创建标签分组

接口说明：创建标签分组。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/taggroups/create?app_token=APP_TOKENquery参数说明：

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

请求数据示例：

{
    "orgId": "524288",
    "tagGroupType": "TAG_TYPE",
    "tagGroupCategory": 1,
    "tagGroupName": "TAG_GROUP_NAME"
}
参数 类型 必须 描述
orgId string 是 组织ID
tagGroupName string 是 标签分组名称（名称需要组织内唯一，不可重复，建议使用：应用开发商名称+应用名称+标签分组名称）
tagGroupCategory int 是 标签类别。1：用于staff，2：用于department
tagGroupType string 否 标签组类型，用于分类检索, 非必填。通过这个字段应用可以方便的管理自己所创建的标签分组，是个自定义字符串，建议使用应用的域名再加个uuid保证唯一性

返回参数字段说明：

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
        "tagGroupId": "TAG_GROUP_ID"
    }
}

业务异常返回：

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

对应可能的错误码说明：

接口错误码

获取标签分组详情

接口说明：获取标签分组详情。请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/taggroups/:tag_group_id/fetch?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数 必须 说明
tag_group_id 是

返回参数字段说明：|参数|类型|说明 | |------------------|--------------|---------------------------------------------| | tagGroupName | string | 标签组名称 | | tagGroupType | string | 标签组类型（用于索引） | | tagGroupCategory | int | 标签分类。1：staff分类，2：department分类 | | tags | obj array | 标签列表。 | | tags.tagId | string | 标签Id | | tags.tagName | string | 标签名称 |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
        "tagGroupName": "name",
        "tagGroupType": "GROUP_TYPE",
        "tagGroupCategory": 1,
        "tags": [{
            "tagId": "524288-xxxxxx",
            "tagName": "标签名称"
        }]
    }
}

业务异常返回：

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

对应可能的错误码说明：

接口错误码

获取标签分组列表

接口说明：获取标签分组列表。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/taggroups/fetch?app_token=APP_TOKENquery参数说明：

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

请求数据示例：

{
    "orgId": "524288",
    "tagGroupType": "TYPE",
    "categoryList": [1, 2]
}
参数 类型 必须 描述
orgId string 是 组织ID
tagGroupType string 否 标签组类型索引
categoryList int array 否 标签组分类。1：人员标签，2：分支标签

返回参数字段说明：|参数|类型|说明 | |------------------|--------------|---------------------------------------------| | tagGroupIds | string array | 标签分组ID列表 |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
        "tagGroupIds": ["524288-xxxxxxxxxx", "524288-xxxxxxxxxxx"]
    }
}

业务异常返回：

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

对应可能的错误码说明：

接口错误码

删除标签分组

接口说明：删除标签分组。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/taggroups/:tag_group_id/delete?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数 必须 说明
tag_group_id 是 标签组ID

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明：

接口错误码

修改标签分组

接口说明：修改标签分组。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/taggroups/:tag_group_id/update?app_token=APP_TOKENquery参数说明：

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

param 参数说明：

参数 必须 说明
tag_group_id 是 标签组的ID

请求数据示例：

{
    "tagGroupName": "TAG_GROUP_NAME"
}
参数 类型 必须 说明
tagGroupName string 是 标签组的名字

返回参数字段说明：

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明：

接口错误码

创建标签

接口说明：创建标签。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/tags/create?app_token=APP_TOKENquery参数说明：

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

请求数据示例：

{
    "orgId": "1234",
    "tagGroupId": "TAG_GROUP_ID",
    "tagName": "TAG_NAME"
}
参数 类型 必须 描述
orgId string 是 组织ID
tagGroupId string 是 标签分组
tagName string 是 标签名称（名称需要组织内唯一，不可重复，建议使用：应用开发商名称+应用名称+标签名称）

返回参数字段说明：|参数|类型|说明 | |------------------|--------------|---------------------------------------------| | tagId | string | 标签ID |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
        "tagId": "TAG_ID"
    }
}

业务异常返回：

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

对应可能的错误码说明：

接口错误码

获取标签详情

接口说明：获取标签详情。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/tags/meta/fetch?app_token=APP_TOKENquery参数说明：

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

请求数据示例：

{
    "tagIds": ["524288-xxxxxxxx", "524288-xxxxx"]
}
参数 类型 必须 描述
tagIds string array 是

返回参数字段说明：|参数|类型|描述 | |----------|----------|----------| | tagMetaList | obj array| 标签详情数据对象列表 | | tagMetaList.tagId | string | 标签ID | | tagMetaList.tagName | string | 标签名称 |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
        "tagMetaList": [{
            "tagId": "524288-xxxxxxx",
            "tagName": "name"
        }, {
            "tagId": "524288-xxxxxxxxx",
            "tagName": "name"
        }]
    }
}

业务异常返回：

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

对应可能的错误码说明：

接口错误码

修改标签

接口说明：修改标签。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/tags/:tagid/update?app_token=APP_TOKENquery参数说明：

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

param参数说明：

参数 必须 说明
tagid 是 标签的ID

请求数据示例：

{
    "tagName": "TAG_NAME"
}
参数 类型 必须 描述
tagName string 是 标签名称（名称需要组织内唯一，不可重复，建议使用：应用开发商名称+应用名称+标签名称）

返回参数字段说明：

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明：

接口错误码

删除标签

接口说明：删除标签。请求方式：POST (HTTPS)，Content-Type: application/json请求地址：https://apigw-example.domain/v1/tags/:tagid/delete?app_token=APP_TOKENquery参数说明：

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

param参数说明：|参数|必须|说明 | |----------|----------|----------| | tagid | 是 | 标签的ID |

返回参数字段说明：

返回数据示例：

业务正常返回：

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

业务异常返回：

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

对应可能的错误码说明：

接口错误码