客户信息

客户模型

DM Hub为客户内置一些比较通用的客户属性,这些属性的名称和类型如下表所示:

属性 界面显示名称 类型 说明
id 客户ID Long 只读字段
displayName 显示名 String 只读字段。如果name不为空,等于name的值,否则等于nickName的值
name 姓名 String
img 用户头像 String 头像地址URL
gender 性别 Integer 0和空代表未知,1代表男,2代表女
mobile 手机号码 String 如果开启全球手机号码,全球手机号码上传格式:[加号][国家代码][一个空格][手机号码] (注:国家代码首位不可为0) 范例: + 86 15300830723
mobileVerified 手机号码是否验证 Boolean 值为true或false
email 邮箱 String
emailVerified 邮箱是否验证 Boolean 值为true或false
birthday 生日 String 格式为: "2019-11-19"
wechat 微信号 String
nickName 微信昵称 String
country 国家 String
province 省份 String
city 城市 String
county 区/县 String
homeAddress 家庭地址 String 最长512个字符
officeAddress 公司地址 String 最长512个字符
qq QQ String
stage 当前阶段 String
dateJoin 创建时间 String 格式为:“2017-06-01T12:12:12Z” 为UTC时间 对于微信粉丝,这个字段记录其关注微信的时间。
source 初始来源 String
contentName 初始来源内容 String
company 公司 String
title 职位 String
industry 公司行业 String
employeeNumber 公司员工数 Integer
annualRevenue 公司年收入 BigDecimal
website 公司网站 String
telephone 座机 String
isEmployee 是否本公司员工 Boolean
campaignId 营销活动ID String
campaignName 营销活动 String
lastUpdated 最后更新时间 String 只读字段,格式为:“2017-06-01T12:12:12Z”为UTC时间
remark 备注 String
dateCreated 系统创建时间 String 只读字段,格式为:“2017-06-01T12:12:12Z”为UTC时间
attr 自定义字段 Object 自定义字段数据存放在该对象上

除了系统内置的客户属性外,您还可以增加自定义属性。请登录DM Hub,并打开 设置 > 客户属性 设置页面:

进入客户属性页面后,点击右上角的 新建用户属性 按钮,新建客户属性:

新建的用户属性会在客户属性列表页显示其技术名,如attr1,attr2等:

客户自定义属性会作为客户attr字段的属性,attr字段是一个对象类型。以下是含有自定义字段attr1的客户数据的JSON示例:

{
    "name": "西门吹雪",
    "attr": {
        "attr1": "西门剑铺"
    }
}

客户身份模型

客户通常是跨触点的,即一个客户同时在多个触点上与您接触。比如一个客户既使用浏览器浏览您的官网,又关注了您的微信公众号,同时又在您的某网上商城购买了东西。通常情况下,客户在任一个触点,都拥有一个该触点所特有的身份信息,如网页里的cookie,微信的openid,网上商城的登录账号。在DM Hub系统中一个客户可以同时拥有多个身份。DM Hub可以通过身份信息将多个触点上的客户信息进行合并。

客户身份有身份类型和身份值两个字段组成:

字段 说明
type 字符串(String) 身份类型,如wechat表示微信openid,最长32位字符。对于自定义的身份类型,进入「设置中心」点击「客户身份」并「新建客户身份」
value 字符串(String) 身份值,与type对应的值,如果type为wechat,value就是对应的openid。最长128位字符

DM Hub内置了几个身份类型:

内置身份类型 含义
wechat 微信的openid
wechat-unionid 微信的unionid
email 邮箱
mobile 手机号

创建客户

带身份创建客户的API

带身份的客户创建,顾名思义是创建客户的时候提供一个或多个客户身份。如果提供的身份已绑定到DM Hub中的现有客户,那么该API便不会创建新的客户,而是更新既有客户,同时将其他身份绑定到该客户上;如果客户信息内提供了手机和邮件地址信息,并且能通过该手机号或邮件地址在DM Hub查到客户,那么该API也不会创建新客户,而是更新找到的客户,并把身份绑定到该客户身上。如果以上两种情况都没找到客户,那么该API会创建一个新客户,并将所有客户身份信息绑定到该客户上。

调用请求

HTTP请求方式: POST
https://api.convertlab.com/v1/customerandidentities?access_token={access_token}&nullAble=false&mergeByEmail=true&mergeByMobile=true
POST数据示例:
{
    "customer": {
        "name": "小D",
        "mobile": "18612341234",
        "mobileVerified": true,
        "gender": 1,
        "attr":{
            "attr1":"",
            "attr2":""
        }
    },

    "customerIdentities": [
        {
            "identityType": "wechat",
            "identityValue": "o123456...",
            "identityName": "微信昵称"
        },
        {
            "identityType": "your-system-account",
            "identityValue": "user123",
            "identityName": "您系统里的用户名"
        }
    ]
}

参数说明

请求体中同时需要提供customer和customerIdentities的信息。

其中身份类型,可以使用DM Hub内置的身份类型,如wechat, wechat-unionid, mobile, email,也可以使用自定义的身份类型,对于自定义的身份类型,建议使用小写字母加中划线或下划线的方式,如taobao-account,这样便于使用身份搜索客户。

返回结果

{
  "id": 7,
  "displayName": "小D",
  "name": "小D",
  "img": null,
  "gender": 1,
  "mobile": "18612341234",
  "mobileVerified": true,
  "email": null,
  "emailVerified": false,
  "birthday": null,
  "wechat": null,
  "nickName": null,
  "country": null,
  "province": null,
  "city": null,
  "county": null,
  "homeAddress": null,
  "officeAddress": null,
  "qq": null,
  "stage": null,
  "dateJoin": "2017-06-06T03:18:23Z",
  "source": null,
  "contentName": null,
  "company": null,
  "title": null,
  "industry": null,
  "employeeNumber": null,
  "annualRevenue": null,
  "website": null,
  "telephone": null,
  "ownerId": null,
  "ownerName": null,
  "isEmployee": false,
  "campaignId": null,
  "campaignName": null,
  "lastUpdated": "2017-06-06T03:18:23Z",
  "remark": null,
  "isMember": false,
  "dateCreated": "2017-06-06T03:18:23Z",
  "attr": {
    "attr1": null
  }
}

注意事项: 使用微信openid或unionid作为客户身份之前,请将微信公众号绑定到DM Hub系统,并将微信粉丝导入到DM Hub系统。

缺少customer数据-返回结果

status: 400
"No customer field found"

缺少customerIdentities数据-返回结果

status: 400
"No customerIdentities field found"

customerIdentities非list类型-返回结果

status: 400
"customerIdentities must be an array of values in customerIdentity"

字段验证错误-返回结果

status: 200
{
    "error": {
        "code": "400001",
        "message": "ClValidationException: Customer validation exception",
        "fieldErrors": [
            {
                "fieldName": "birthday",
                "message": "test parse error"
            }
        ]
    }
}

普通创建客户API

普通创建客户API会根据请求体中的手机号码和邮件地址去查找现有客户,如果能查找到客户,就会更新现有客户,否则则创建一下新客户。

调用请求

HTTP请求方式: POST
https://api.convertlab.com/v1/customers?access_token={access_token}
POST数据示例:
{
    "name": "小D",
    "mobile": "18612341234",
    "mobileVerified": true,
    "gender": 1,
    "createMethod": "ImportFromExternalSystem"
}
参数说明
{access_token} 的值为调用API的令牌,请参见 获取access_token

返回结果
新客户 status:201
已有客户 status:200
{
  "id": 7,
  "displayName": "小D",
  "name": "小D",
  "img": null,
  "gender": 1,
  "mobile": "18612341234",
  "mobileVerified": true,
  "email": null,
  "emailVerified": false,
  "birthday": null,
  "wechat": null,
  "nickName": null,
  "country": null,
  "province": null,
  "city": null,
  "county": null,
  "homeAddress": null,
  "officeAddress": null,
  "qq": null,
  "stage": null,
  "dateJoin": "2017-06-06T03:18:23Z",
  "source": null,
  "contentName": null,
  "company": null,
  "title": null,
  "industry": null,
  "employeeNumber": null,
  "annualRevenue": null,
  "website": null,
  "telephone": null,
  "ownerId": null,
  "ownerName": null,
  "isEmployee": false,
  "campaignId": null,
  "campaignName": null,
  "lastUpdated": "2017-06-06T03:18:23Z",
  "remark": null,
  "isMember": false,
  "dateCreated": "2017-06-06T03:18:23Z",
  "attr": {
    "attr1": null
  }
}

请求对象为空-返回结果

status: 400
"Request data need at least one field"

字段验证错误-返回结果

status: 200
{
    "error": {
        "code": "401011",
        "message": "Customer validation exception",
        "fieldErrors": [
            {
                "birthday": "testet parse error"
            }
        ]
    }
}

更新客户的API

调用该API可以对DM Hub系统中的客户进行修改。 需要注意的一点是,对于mobileVerified为true的手机号,在手机号码不变的情况下,无法将mobileVerified字段改为false。对于emailVerified为true的电子邮箱,在邮箱地址不变的情况下,无法将emailVerified字段改为false。 调用该接口,无法将客户的字段清空。

调用请求

HTTP请求方式: PUT
https://api.convertlab.com/v1/customers/{id}?access_token={access_token}&forceUpdate=true&nullAble=false
PUT数据示例:
{
    "name": "小D",
    "mobile": "18612341234",
    "mobileVerified": true,
    "gender": 1
}

参数说明

返回结果

返回修改前的客户信息

删除客户的API

删除指定的客户

调用请求

HTTP请求方式: DELETE
https://api.convertlab.com/v1/customers/{id}?access_token={access_token}

参数说明

返回结果

返回状态码为204

获取单个客户的API

调用请求

HTTP请求方式: GET
https://api.convertlab.com/v1/customers/{id}?access_token={access_token}

参数说明

返回结果

{
  "id": 7,
  "displayName": "小D",
  "name": "小D",
  "img": null,
  "gender": 1,
  "mobile": "18612341234",
  "mobileVerified": true,
  "email": null,
  "emailVerified": false,
  "birthday": null,
  "wechat": null,
  "nickName": null,
  "country": null,
  "province": null,
  "city": null,
  "county": null,
  "homeAddress": null,
  "officeAddress": null,
  "qq": null,
  "stage": null,
  "dateJoin": "2017-06-06T03:18:23Z",
  "source": null,
  "contentName": null,
  "company": null,
  "title": null,
  "industry": null,
  "employeeNumber": null,
  "annualRevenue": null,
  "website": null,
  "telephone": null,
  "ownerId": null,
  "ownerName": null,
  "isEmployee": false,
  "campaignId": null,
  "campaignName": null,
  "lastUpdated": "2017-06-06T03:18:23Z",
  "remark": null,
  "isMember": false,
  "dateCreated": "2017-06-06T03:18:23Z",
  "attr": {
    "attr1": null
  }
}

查询客户的API

调用请求

HTTP请求方式: GET
https://api.convertlab.com/v1/customers?access_token={access_token}&stage={stage}&source={source}&mobile={mobile}&email={email}&gender={gender}&idList={idList}&dateCreatedFrom={dateCreatedFrom}&dateCreatedTo&lastUpdatedFrom={lastUpdatedFrom}&lastUpdatedTo={lastUpdatedTo}&select={select}&rows={rows}&page={page}&sidx={sidx}&sord={sord}

参数说明

参数 是否必填 说明
access_token 访问API的令牌
stage 用客户所处的阶段查询,如过查询的阶段为空,请使用stage=_empty
mobile 用客户的手机查询
email 用客户的邮箱查询
hasMobile 手机号不为空
hasEmail 邮箱不为空
identityType 身份类型
identityValue 身份值
idList 支持以逗号分开的客户id列表,如idList=1,2,3,4
dateCreatedFrom 客户创建的起始时间,时间格式为 “2016-11-11T11:11:11” 为UTC时间,备注:北京时间需要减8后传入
dateCreatedTo 客户创建的结束时间,时间格式为 “2016-11-11T11:11:11” 为UTC时间
lastUpdatedFrom 客户更新的起始时间(包含),时间格式为 “2016-11-11T11:11:11” 为UTC时间
lastUpdatedTo 客户更新的结束时间,时间格式为 “2016-11-11T11:11:11” 为UTC时间
idFrom 起始客户id
idTo 结束客户id
select 返回的字段,多个字段用逗号隔开。默认返回所有字段,可以用select指定要返回的字段
rows 每页的记录数,默认每页返回20行
page 返回第几页,默认返回第1页
sidx 按什么字段排序,默认按id排序
sord asc表示升序,desc表示降序。默认按升序排序

返回结果 - 返回的所有客户数据保存在名叫rows的array字段中

{
  "rows": [
    {
      "id": 1,
      "displayName": "大D",
      "name": "大D",
      "img": null,
      "gender": 1,
      "mobile": "18612341234",
      "mobileVerified": true,
      "email": null
      // 客户的其他字段
    },
    {
      "id": 7,
      "displayName": "小D",
      "name": "小D",
      "img": null,
      "gender": 1,
      "mobile": "18612341235",
      "mobileVerified": true,
      "email": null
      // 客户的其他字段
    }
  ]
}

获取客户数量的API

调用请求

HTTP请求方式: GET
https://api.convertlab.com/v1/customers/count?access_token={access_token}&stage={stage}&source={source}&mobile={mobile}&gender={gender}&idList={idList}&dateCreatedFrom={dateCreatedFrom}&dateCreatedTo&lastUpdatedFrom={lastUpdatedFrom}&lastUpdatedTo={lastUpdatedTo}

参数说明

参数 是否必填 说明
access_token 访问API的令牌
stage 用客户所处的阶段查询,如过查询的阶段为空,请使用stage=_empty
source 用客户的初始来源查询
mobile 用客户的手机查询
gender 用客户的性别查询, 1代表男性,2代表女性,0代表未知
idList 支持以逗号分开的客户id列表,如idList=1,2,3,4
dateCreatedFrom 客户创建的起始时间,时间格式为 “2016-11-11T11:11:11” 为UTC时间
dateCreatedTo 客户创建的结束时间,格式为:“2017-06-01T12:12:12Z” 为UTC时间
lastUpdatedFrom 客户更新的其实时间(包含),格式为:“2017-06-01T12:12:12Z” 为UTC时间
lastUpdateTo 客户更新的结束时间,格式为:“2017-06-01T12:12:12Z” 为UTC时间
select 返回的字段,多个字段用逗号隔开。默认返回所有字段,可以用select指定要返回的字段

返回结果

返回满足条件的客户的数量

添加客户身份的API

可以为DM Hub系统中的现有客户添加客户身份。新添加的身份将出现在客户详情页的左下角

调用请求

HTTP请求方式: POST
https://api.convertlab.com/v1/customeridentities?access_token={access_token}

POST请求示例:

{
  "customerId": "123456",
  "identityType": "myshop-account",
  "identityValue": "user12345",
  "identityName": "小羊苏西"
}

参数说明

参数 是否必填 说明
access_token 访问API的令牌
customerId 需要添加身份的客户id
identityType 要添加的客户身份类型,详见 客户身份模型,最长32位字符
identityValue 要添加的客户身份值,最长128位字符
identityName 客户身份对应的昵称,最长256位字符

返回结果

{
  "customerId": "123456",
  "identityType": "myshop-account",
  "identityValue": "user12345",
  "identityName": "小羊苏西"
}

查询客户身份的API

可以根据一个或多个客户id查询客户的身份,也可以通过身份的类型和身份值查询客户id

调用请求

HTTP请求方式: GET
https://api.convertlab.com/v1/customeridentities?access_token={access_token}&customerIds={customerIds}&identityType={identityType}&identityValue={identityValue}

参数说明

参数 是否必填 说明
access_token 访问API的令牌
customerIds 要查询客户身份的客户id列表,多个客户id用逗号隔开,如 “123,124”
identityType 要查询客户id的身份类型,与identityValue同时使用
identityValue 要查询客户id的身份值,与identityType同时使用

返回结果

[
  {
    "customerId": "123456",
    "identityType": "myshop-account",
    "identityValue": "user12345",
    "identityName": "小羊苏西"
  },
  {
    "customerId": "123456",
    "identityType": "wechat",
    "identityValue": "openid12345",
    "identityName": "小羊苏西"
  }
]

返回参数说明

customerIds非数值类型-返回结果

status: 200 OK
{
    "error": {
        "code": "400001",
        "message": "customer id should be a number",
        "fieldErrors": [
            {
                "fieldName": "customerIds",
                "message": "customer id should be a number"
            }
        ]
    }
}

根据md5查询客户身份的API

可以根据md5查询对应的客户身份, md5作为与系统身份独立的数据,根据身份查询客户并不会查询md5数据,需要调用这个接口先查询md5对应的系统身份。

调用请求

HTTP请求方式: GET
https://api.convertlab.com/v1/customerService/getCustomerIdentityByMd5?access_token={access_token}&md5type={md5type}&md5value={md5value}

参数说明

参数 是否必填 说明
access_token 访问API的令牌
md5type md5类型,通用md5取common,天猫md5取tmall
md5value md5值

返回结果

{
    "id": 13,
    "dateCreated": "2019-04-01T05:50:27Z",
    "lastUpdated": "2019-04-01T05:55:09Z",
    "md5type": "common",
    "value": "MD100002",
    "type": "mobile",
    "customerId": 418615942793357312,
    "customerIdStr": "418615942793357312",
    "md5value": "1010cd3d89afa26a3d85c2605edc519a"
}

返回参数说明

找不到身份-返回结果

status: 200 OK
{
    "error": {
        "code": "409200",
        "message": "Not found"
    }
}

查询客户的统计信息

调用请求

GET
https://api.convertlab.com/v1/customerStatistics?access_token={access_token}&customerId={customerId}&customerIds={customerIds}

请求参数说明

Name In Required Type Description
access_token query yes string 用从“获取身份权限”节拿到的access_token替换
customerId query no number 精确查询某个客户的记录
customerIds query no number 和customerId两个参数一定要有一个,批量根据客户id获取统计数值,用逗号分隔

返回数据

  {
      "items":[
          {
              "customerId": 4678,
              "firstOrderDate": "2015-04-28T03:43:33Z",
              "id": 10948,
              "lastOrderDate": "2015-04-28T03:43:33Z",
              "lastOrderDays": 635,
              "lastUpdated": "2017-01-22T16:34:03Z",
              "latest30daysScore": 0,
              "orderAMT": 0.05,
              "orderAMTA": 4.2,
              "orderAPCT": 88,
              "orderTotal": 1,
              "orderTotalAmount": 88,
              "totalScore": 0
          }
      ],
      "meta": {
          "records": 20,
          "total": 7,
          "hasNext": true
      }
  }

返回数据说明

Name Type Description
items array 数据块标签
customerId
firstOrderDate 格式为:“2017-06-01T12:12:12Z” 为UTC时间
id number 这条记录的ID
lastOrderDate 格式为:“2017-06-01T12:12:12Z” 为UTC时间
lastOrderDays
lastUpdated 格式为:“2017-06-01T12:12:12Z” 为UTC时间
latest30daysScore
orderAMT
orderAMTA
orderAPCT
orderTotal
orderTotalAmount
totalScore number 客户活跃度值
meta object 元数据块标签
records number 总记录条数
total number 总页数
hasNext boolean 是否还有记录

根据客户身份合并客户API

根据客户身份把两个客户进行合并,合并后customer(From)会被删除掉,customer(To)的customerid 会被返回

调用请求

HTTP请求方式: POST
https://api.convertlab.com/v1/customerService/mergeCustomerByIdentities?access_token={access_token}

POST请求示例:

{
  "from": {
    "identityType": "wechat",
    "identityValue": "aaaa"
  },
  "to": {
    "identityType": "wechat-openid",
    "identityValue": "oVLMTt0zw5JEZc6PE0tIsA5Kz7f0"
  }
}

参数说明

参数 是否必填 说明
access_token 访问API的令牌
identityType 客户身份类型,详见 客户身份模型,最长32位字符
identityValue 客户身份值,最长128位字符

返回结果

{
  "data": {
    "customerId": "{合并后的客户id}"
  }
}

根据客户ID合并客户API

根据客户ID把两个客户进行合并,合并后customer(From)会被删除掉,customer(To)的customerid 会被返回

调用请求

HTTP请求方式: POST
https://api.convertlab.com/v1/customerService/mergeCustomerById?access_token={access_token}&fromId={fromId}&toId={toId}

参数说明

参数 是否必填 说明
access_token 访问API的令牌
fromId 需要合并的来源客户ID
toId 需要合并的目标客户ID

返回结果

{
  "data": {
    "customerId": "{合并后的客户id}"
  }
}

解绑客户微信身份API

该接口根据传入的微信公众号openid或者unionid对客户的微信身份进行解绑。openid和unionid至少传入一个,优先根据unionid进行解绑,如果只有openid 会根据DMhub系统中openid 对应的unionid进行解绑。 解绑完成后会生成一个带有微信unionid和此unionid对应的所有openid身份的新客户,并且,新客户会带有一条关注事件和一条系统事件(客户微信解绑事件)。如果解绑成功则返回新客户ID以及身份。

调用请求

HTTP请求方式: POST
https://api.convertlab.com/v1/customers/wechat/unbinding?access_token={access_token}

参数说明

参数 是否必填 说明
access_token 访问API的令牌
openid 微信公众号openid,与unionid至少传一个
unionid 微信公众号unionid,与openid至少传一个

请求体

{
  "openid":"xxxxx",
  "unionid":"xxxxxx"
}

返回结果

成功

{
    "customerId":"123456",
    "identities":[
        {
            "type":"wechat",
            "value":"xxxx"
        }
    ]
}

失败

{
    "error": {
        "code": "400005",
        "message": "openid and unionid not found!"
    }
}