联系人接口 (Users)

1. 获取联系人列表

GET /users.json

参数	类型	必填	默认值	说明
page	int	否	1	页码，最小 1
per_page	int	否	100	每页条数，最大 100
deStat	int	否	0	0=排除已删除(status≠3，含离职)，1=包含全部状态
open_type	string	否	-	开放平台类型，如 `wechat`
app_id	string	否	-	开放平台 app_id
open_id	string	否	-	开放平台 open_id
created_start	string	否	-	创建时间范围起始，格式 Y-m-d
created_end	string	否	-	创建时间范围结束，格式 Y-m-d
created_order	string	否	-	按创建时间排序，ASC 或 DESC
updated_start	string	否	-	更新时间范围起始，格式 Y-m-d
updated_end	string	否	-	更新时间范围结束，格式 Y-m-d
updated_order	string	否	-	按更新时间排序，ASC 或 DESC

注：传入 open_type + app_id + open_id 时走微信绑定查询逻辑，返回匹配的单个联系人。

响应示例:

{
  "users": [
    {
      "cId": "6892477",
      "name": "响应联系人B",
      "mobile": "13800998800",
      "email": "",
      "fixnumber": "",
      "position": "经理",
      "QQ": "",
      "note": "",
      "companyId": "1346525",
      "supportId": "0",
      "multiServiceList": "",
      "default": "",
      "service_groupid": "0",
      "createDT": "2026-08-17 17:24:34",
      "updateDT": "",
      "tableName": "",
      "uniqueId": "",
      "state": "1",
      "custom_fields": [{"key": "field_4", "value": "否"}]
    }
  ],
  "count": "1",
  "previous_page": null,
  "next_page": "https://xxx/api/v1/users.json?per_page=50&page=2"
}

2. 搜索联系人

GET /users/search.json

参数	类型	必填	默认值	说明
query	string	是	-	搜索条件，空格分隔多个条件
page	int	否	1	页码
per_page	int	否	100	每页条数
deStat	int	否	0	0(默认)=仅在职(status=1)，1=返回全部状态(含离职2/删除3)
sort_by	string	否	-	createDT / updateDT
sort_order	string	否	desc	asc / desc

query 语法（空格分隔）:

格式	示例	说明
`field:value`	`realName:张三`	模糊匹配
`field:value`	`mobile:13800138000`	模糊匹配
`field:value`	`email:test@qq.com`	精确匹配
`field:value`	`companyId:123`	精确匹配
`field:value1,value2`	`realName:张三,李四`	多值 OR 查询
`createDT:2024-01-01`	-	日期等于（当天范围）
`createDT>=2024-01-01`	-	日期大于等于
`value`	`张三`	纯文本，模糊搜索 realName 和 mobile

可搜索系统字段: realName(模糊), mobile(模糊), email(精确), position(精确), QQ(精确), note(精确), companyId(精确), supportId(精确), authAccount(精确), authaccount(精确), createDT(日期), updateDT(日期)

自定义字段: 任意自定义字段名，下拉型(datatype=1)精确匹配，其他类型模糊匹配

响应示例:

{
  "results": [
    {
      "cId": "6892476",
      "name": "响应示例联系人",
      "mobile": "13800998877",
      "companyId": "1346524",
      "state": "1",
      "createDT": "2026-08-17 17:24:00",
      "updateDT": "",
      "custom_fields": [{"key": "field_4", "value": "否"}],
      "url": "https://xxx/api/v1/users/6892476.json"
    }
  ],
  "count": "1",
  "previous_page": null,
  "next_page": "https://xxx/api/v1/users/search.json?per_page=20&page=1&"
}

3. 批量获取联系人

GET /users/show_many.json

参数	类型	必填	说明
ids	string	是	联系人 ID，逗号分隔

响应示例:

{
  "users": [
    {
      "cId": "123",
      "name": "联系人A",
      "mobile": "13800138000",
      "companyId": "100",
      "state": "1",
      "createDT": "2024-01-01 10:00:00",
      "custom_fields": [{"key": "field_4", "value": "否"}]
    },
    {
      "cId": "456",
      "name": "联系人B",
      "mobile": "13900139000",
      "companyId": "100",
      "state": "1",
      "createDT": "2024-02-01 10:00:00",
      "custom_fields": [{"key": "field_4", "value": "否"}]
    }
  ]
}

4. 获取单个联系人

GET /users/{id}.json

参数	类型	必填	默认值	说明
deStat	int	否	0	0=排除已删除(status≠3，含离职)，1=包含全部状态

响应示例:

{
  "user": {
    "cId": "6892477",
    "name": "响应联系人B",
    "mobile": "13800998800",
    "email": "",
    "fixnumber": "",
    "position": "经理",
    "QQ": "",
    "note": "",
    "companyId": "1346525",
    "supportId": "0",
    "multiServiceList": "",
    "default": "",
    "service_groupid": "",
    "createDT": "2026-08-17 17:24:34",
    "updateDT": "",
    "createrId": "176853",
    "tableName": "",
    "uniqueId": "",
    "state": "1",
    "custom_fields": [{"key": "field_4", "value": "否"}]
  }
}

5. 创建联系人

POST /users.json
Content-Type: application/json

{
  "user": {
    "name": "string (联系人姓名, 最大50字符)",
    "mobile": "string (手机号, 纯数字最大11位, 与fixnumber二选一)",
    "fixnumber": "string (座机号, 数字和()-字符, 与mobile二选一)",
    "email": "string (邮箱, 需合法格式)",
    "position": "string (职位, 最大20字符)",
    "QQ": "string (QQ号, 纯数字, 最大20字符)",
    "note": "string (备注, 最大120字符)",
    "companyId": "int (所属公司ID, 正整数, 公司必须存在)",
    "supportId": "int (负责客服ID, 正整数)",
    "multiServiceList": "string (多客服ID列表, 逗号分隔)",
    "service_groupid": "string (受理客服组ID列表, 逗号分隔)",
    "default": "int (0或1, 是否设为默认联系人)",
    "uniqueId": "string (9位数字ID)",
    "source": "int (来源, 默认9)",
    "custom_fields": [
      {"key": "字段名", "value": "字段值"},
      {"key": "authaccount", "value": "第三方对接账号"}
    ],
    "userGroup": "string (客户分组ID, 逗号分隔, 仅2C模式)",
    "tableName": "string (标签名, 逗号分隔)"
  }
}

参数	类型	必填	说明
user.name	string	否	联系人姓名，最大 50 字符
user.mobile	string	条件必填	手机号，纯数字最大 11 位。无 authAccount 时与 fixnumber 二选一必填
user.fixnumber	string	条件必填	座机号，数字和 `()-` 字符。无 authAccount 时与 mobile 二选一必填
user.email	string	否	邮箱，需合法格式
user.position	string	否	职位，最大 20 字符
user.QQ	string	否	QQ 号，纯数字，最大 20 字符
user.note	string	否	备注，最大 120 字符
user.companyId	int	否	所属公司 ID，正整数，必须存在
user.supportId	int	否	负责客服 ID，正整数
user.multiServiceList	string	否	多客服 ID 列表，逗号分隔
user.service_groupid	string	否	受理客服组 ID 列表，逗号分隔
user.default	int	否	0 或 1，设为公司默认联系人
user.uniqueId	string	否	9 位数字客户 ID
user.source	int	否	来源标识，默认 9
user.custom_fields	array	否	自定义字段，`[{key, value}]` 格式
user.userGroup	string	否	客户分组 ID，逗号分隔（仅 2C 模式）
user.tableName	string	否	标签名，逗号分隔

重要：
authAccount 通过 custom_fields 传入，key 为 authaccount。传了 authAccount 则 mobile/fixnumber 不再必填。
同一公司下同一手机号不能重复创建。

响应示例:

{
  "user": {
    "cId": "6892477",
    "name": "响应联系人B",
    "mobile": "13800998800",
    "email": "",
    "fixnumber": "",
    "position": "经理",
    "QQ": "",
    "note": "",
    "status": "1",
    "companyId": "1346525",
    "supportId": "0",
    "multiServiceList": "",
    "default": "",
    "service_groupid": "",
    "createDT": "2026-08-17 17:24:34",
    "updateDT": "",
    "tableName": "",
    "custom_fields": [{"key": "field_4", "value": "否"}]
  }
}

6. 更新联系人

PUT /users/{id}.json
Content-Type: application/json

参数同创建，全部可选。额外参数：

参数	类型	必填	说明
user.state	int	否	状态：1=在职，2=离职，3=删除
user.default	int	否	0 或 1，设为公司默认联系人（设为1时自动取消其他默认）

响应示例: 同创建联系人，返回更新后的联系人完整对象（{"user": {...}}）。

7. 删除单个联系人

DELETE /users/{id}.json

响应示例:

{
  "user": {
    "cId": "6892477",
    "name": "响应联系人B",
    "mobile": "13800998800",
    "companyId": "1346525",
    "state": "1",
    "createDT": "2026-08-17 17:24:34",
    "custom_fields": [{"key": "field_4", "value": "否"}]
  }
}

8. 批量删除联系人

DELETE /users/destroy_many.json

参数	类型	必填	说明
ids	string	是	联系人 ID，逗号分隔

响应示例:

{
  "users": [
    {"cId": "123", "name": "联系人A", "mobile": "13800138000"},
    {"cId": "456", "name": "联系人B", "mobile": "13900139000"}
  ]
}

联系人管理

联系人接口 (Users)#

1. 获取联系人列表#

2. 搜索联系人#

3. 批量获取联系人#

4. 获取单个联系人#

5. 创建联系人#

6. 更新联系人#

7. 删除单个联系人#

8. 批量删除联系人#

联系人接口 (Users)

1. 获取联系人列表

2. 搜索联系人

3. 批量获取联系人

4. 获取单个联系人

5. 创建联系人

6. 更新联系人

7. 删除单个联系人

8. 批量删除联系人