目录

联系人接口


为了支持比较复杂的自定义字段类型,我们对接口进行了升级,凡是接口名称中包含“_v2”的均为新接口,不包含的仍为旧接口,新接口的增加不对旧接口的逻辑产生任何影响,可放心使用旧接口。

新接口与旧接口的区别:

  1. 新接口新增了对“高级复选框”、“级联”类型的自定义字段的支持。
  2. 新接口的请求数据或返回值中如果包含下拉列表类型的字段,则传值为选项ID,旧接口则是选项内容。

JSON格式

名称 类型 只读 必填 注释
cId int 联系人ID,系统自动生成
url varchar 该联系人的url
name varchar 姓名
mobile varchar 手机号码,创建联系人时手机号码、座机号码任填写一个即可
fixnumbervarchar 座机号码,创建联系人时手机号码、座机号码任填写一个即可
email varchar 邮件
position varchar 职位
state int 联系人状态(1-在职、2-离职、3-已删除)
QQ varchar QQ号码
note varchar 联系人备注
companyIdint 联系人所属公司ID,如果是2B模式必填,2C模式不用填
uniqueIdvarchar 联系人下的远程ID,远程客户端安装完毕后自动生成的。旧接口的返回值
uniqueIdsarray 联系人下的远程ID及ID的备注。新接口的返回值
supportIdint 负责该联系人的客服ID,系统自动生成
createrIdint 创建人id
defaulttinyint 是否是该公司的默认联系人,取值为:1-默认联系人,0-普通联系人
createDT date 创建时间,格式为:2018-02-03 00:00:00
updateDTdate 更新时间,格式为:2018-02-03 00:00:00
custom_fieldsarray 联系人自定义字段
userGroupint 联系人所属分组,2C模式下存在该字段,默认取值为0,即不属于任何分组,多个分组用,分隔
tableName varchar 标签,多个英⽂逗号隔开

JSON示例

{
  "cId": 1,
  "url": "https://www.bangwo8.com/api/v1/users_v2/1.json",
  "name": "张三",
  "mobile": "13240138429",
  "email": "234576@163.com",
  "fixnumber": "010-63701717",
  "position": "项目经理",
  "QQ": "601100987",
  "note": "这里是联系人的备注",
  "companyId": 123,
  "uniqueId": "291045895",
  "supportId": 3,
  "createDT": "2017-09-12 10:12:22",
  "updateDT": "2017-09-12 10:12:22",
  "custom_fields": [
      {
	"key": "field_1",
	"value": "4334"
      },
      {
	"key": "field_3",//复选框
	"value": "是" 
      },
      {
	"key": "field_2",//下拉列表
	"value": "下拉菜单的某一项"//选项ID
      }
      {
	"key": "field_5",//高级复选框
	"value": "232,565,454"//勾选项的ID列表,以逗号分隔
      }
      {
	"key": "field_7",//级联
	"value": [
	  {
            "level_id":"s1",//级联的第一级别的id
            "item_key":"11"//选中项的ID
          },
          {
            "level_id":"s2",//级联的第二级别的id
            "item_key":"21"
          },
          {
	    "level_id":"s3",//级联的第三级别的id
	    "item_key":"31"
          }
	]
     }
   ],
   "userGroup": 221
}   

获取联系人列表

GET /api/v1/users_v2.json

旧接口 “GET /api/v1/users.json”
获取全部数据(包含已删除数据),需在链接后拼接deStat=1,/api/v1/users_v2.json?deStat=1

查询参数

名称 必需的 类型 注释
created_start string 按创建时间筛选,开始时间,包含当天
created_end string 按创建时间筛选,结束时间,包含当天
updated_start string 按更新时间筛选,开始时间,包含当天
updated_end string 按更新时间筛选,结束时间,包含当天
created_order string 按创建时间排序,取值为:asc-升序,desc-降序
updated_order string 按更新时间排序,取值为:asc-升序,desc-降序
page int 分页获取,默认为1
per_page int 每页大小,默认为100

说明:默认按编码升序返回。时间参数(created_start、created_end、updated_start、updated_end)格式为“2012-01-01 00:00:00”。

调用者权限

所有客服

也可以使用下面的接口

/*查看服务商下某个客户的联系人*/
GET /api/v1/companies/{company_id}/users_v2.json
GET /api/v1/companies/{company_id}/users.json

调用示例

curl https://www.bangwo8.com/api/v1/users_v2.json \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
	"users": [
		{
			"cId": 1,
			"name": "张三",
			...
		},
		{
			"cId": 2,
			"name": "李四",
			...
		}
	],
        "count": 42,
        "next_page": "https://www.bangwo8.com/api/v1/users_v2.json?per_page=40&page=2",
        "previous_page": null
}

查看指定联系人信息

GET /api/v1/users/{cid}_v2.json

旧接口 “GET /api/v1/{cid}.json”

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/{cid}_v2.json \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
    "user": {
        "cId": "41451311",
        "name": "测试1",
        "mobile": "18811119637",
        "email": "",
        "fixnumber": "",
        "position": "",
        "QQ": "",
        "note": "",
        "companyId": "0",
        "supportId": "0",
        "multiServiceList": "",
        "default": "",
        "service_groupid": "0",
        "createDT": "2022-01-10 11:10:43",
        "updateDT": "2022-02-10 15:16:16",
        "tableName": "",
        "uniqueId": "",
        "custom_fields": [
            {
                "key": "field_1",
                "value": ""
            },
            {
                "key": "authaccount",
                "value": "212108284829637117"
            },
            {
                "key": "field_3",
                "value": [
                    "北京市",
                    "海淀",
                    "清华大学"
                ]
            }
        ],
        "userGroup": "0"
    }
}

获取多个联系人信息

GET GET /api/v1/users/show_many.json?ids={ids}

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/show_many.json?ids=1,2,3 \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
  "users": [
    {
      "cId": 1,
      "name": "张三",
      ...
    },
    {
      "cId": 2,
      "name": "李四",
      ...
    }
  ]
}

创建联系人

POST /api/v1/users_v2.json

旧接口“POST /api/v1/users.json”

调用者权限

所有客服

调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214"}}'

说明:可通过mobile和fixnumber属性来创建联系人。也就是说,创建联系人时,mobile、fixnumber两者其一必须有值。

若请求数据中包含“下拉列表”,则需传递选中项的ID,调用示例如下:

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"droplist_job","value":"232"}]}}'

若请求数据中包含“复选框”,则选中时传“1”,未选中传“0”,调用示例如下:

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"checkbox_married","value":"1"}]}}'

若请求数据中包含“高级复选”,则需传递所有勾选项的ID,以逗号分隔,调用示例如下:

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"advance_checkbox_hobby","value":"21,23"}]}}'

若请求数据中包含“级联”字段,调用示例如下:

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"field_3","value":["北京市","海淀","清华大学"]}]}}'

返回值示例

Status: 200 OK
Location: https://www.bangwo8.com/api/v1/users/{id}.json

{
  "user": {
    "cId":   11,
    "name": "张三",
    ...
  }
}

[注] 联系人是与手机号码一一对应,因此:
1、2B模式下,不同公司下可以有相同联系人(手机号码),同一公司下不能有相同联系人(手机号码)(即:同一个人可能出现在多个公司里,但同一个人不能在同一公司出现两次);
2、2C模式下,没有公司概念,所有联系人在一起,不能有相同联系人(手机号码)
否则通过API创建联系人时会报错:[{“errorMsg”:“The \”mobile\“ has been used”,“status”:“110017”}]

修改联系人信息

PUT /api/v1/users/{cid}.json

调用者权限

所有客服

更新系统字段调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users/123.json \
  -H "Content-Type: application/json" -X PUT -d '{"user": {"name": "张三"}}'

返回值示例

Status: 200 OK

{
  "user": {
    "cId":   11,
    "name": "张三",
    ...
  }
}

更新自定义字段调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users/123.json \
  -H "Content-Type: application/json" -X PUT -d '{"user":{"custom_fields":[{"key":"field_1","value":"123"}]}}'

返回值示例

Status: 200 OK

{
  "user": {
    "cId":   11,
    "name": "张三",
     "custom_fields": [
            {
                "key": "field_1",
                "value": "123"
            }
        ]
  }
}

搜索联系人

GET /api/v1/users/search.json

获取全部数据(包含已删除数据),需在链接后拼接deStat=1,/api/v1/users/search.json?deStat=1

调用者权限

所有客服

请求参数

名称 类型 必需的 注释
query string 搜索内容
sort_by string 按时间排序,目前支持:createDT-创建时间,updateDT-更新时间
sort_order string 按升序还是降序返回,取值为:asc-升序,desc-降序,默认为降序

query参数说明

搜索内容 返回结果
query=2444 模糊搜索,返回姓名或者手机号包含该内容的联系人
query=mobile:13240138429 搜索手机号为“13240138429”的联系人,此为精确搜索
query=userId:9516936 mobile:13240134213 搜索公司id为“9516936”且手机号码为“13240134213 ”的联系人,此为精确搜索
query=authaccount:454 返回自定义字段唯一标识为“authaccount”为454的联系人,此条件为精准查询
query=2444 createDT>2017-07-01返回姓名或者手机号包含“2444”,并且创建时间是2017年7月1日以后的联系人
query=2444 createDT>=2017-07-01 createDT<2017-08-01返回姓名或者手机号包含“2444”,并且时间是7月份的联系人

说明:
1、目前不支持搜索内容本身带有空格
2、当query参数增加了时间的过滤条件时,两个条件之间要以空格分开,比如“2444 createDT>2017-07-01”
3、时间过滤条件目前支持以下几种方式:(以createDT为例)

  * createDT<2017-09-01 //过滤创建时间为2017-09-01之前的联系人,不包含2017-09-01当天
  * createDT>2017-09-01 //过滤创建时间为2017-09-01之后的联系人,不包含2017-09-01当天 
  * createDT:2017-09-01 //过滤创建时间为2017-09-01当天的联系人 
  * createDT<=2017-09-01 //过滤创建时间为2017-09-01之前的联系人,包含2017-09-01当天 
  * createDT>=2017-09-01 //过滤创建时间为2017-09-01之后的联系人,包含2017-09-01当天

调用示例

curl "https://www.bangwo8.com/api/v1/users/search.json" \
  -G --data-urlencode "query=132 createDT>2017-07-03" \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
  "results": [
    {
      "name":   "张三",
      "createDT":  "2009-05-13 10:07:08",
      "updateDT":  "2011-07-22 11:11:12",
      "cId":  111,
      "url":       "https://www.bangwo8.com/api/v1/users/111.json"
    },
    {
      "subject":   "李四",
      "createDT":  "2010-07-13 10:07:08",
      "updateDT":  "2011-07-13 11:11:12",
      "cId":  112,
      "url":       "https://www.bangwo8.com/api/v1/users/112.json"
    },
    ...
  ],
  "next_page": "https://www.bangwo8.com/api/v1/users/search.json?query=132 createDT>2017-07-03&sort_by=createDT&sort_order=desc&page=2",
  "prev_page": null,
  "count":     100
}

删除多个联系人

DELETE /api/v1/users/destroy_many.json

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/destroy_many.json?ids=123,234 \
  -v -u {account}:{password} \
  -X DELETE

返回值示例

Status: 200 OK

{
  "users": [
    {
      "cId": 123,
      "name": "张三",
      ...
    },
    {
      "cId": 234,
      "name": "李四",
      ...
    }
  ]
}