User Guide

About the API

Data Group REST API提供了一个基于web的API,允许客户以更低的成本获得更好的直接营销结果.

The Data Group provides comprehensive, 满足各种规模组织的业务目标的定制服务, ranging from Fortune 1000 companies to startups. Our clients work in an array of industries, including insurance, 金融, 旅行, 零售, automotive, 教育, 健康, 媒体, and telecommunications basically, any field that utilizes direct marketing.

Account Types

该API支持三种不同的帐户类型,它们具有不同的权限.The different account 类型s are described below.

Unrestricted Account

Unrestricted Accounts are paying accounts with unlimited access to all of the uri. 注册一个具有这种访问权限的付费帐户, 或者将一个不同的帐户升级到此访问级别, by contacting: support@www.china-heermeng.com

Restricted Account

受限账户(Restricted Accounts)是指可以无限制访问所有uri的支付账户, excluding the Asynchronous Email Append uri. 注册一个具有这种访问权限的付费帐户, 或者将一个不同的帐户升级到此访问级别, by contacting: support@www.china-heermeng.com

Trial Account

Trial Accounts are nonpaying, temporary accounts. 这些帐户对API的查询数量有限,并且没有使用异步电子邮件追加uri的权限. 请记住,不返回结果的查询仍将计入Trial Account查询限制. 试用帐户可以升级为无限制帐户或限制帐户, or extended, by contacting: support@www.china-heermeng.com

请求

API的所有请求有效负载都应该以JSON对象的形式提供. The specific attributes required for each request payload depends on the specific URI being called. 此外,所有对API的请求必须包含以下头属性:

Header 属性Description笔记
AuthorizationToken这是授权令牌,是访问API所必需的. 这个属性的值通过调用/身份验证 URI获得.调用/身份验证 URI时不需要这个头文件.
x-api-keyThis is the API Key needed to access the API. 此属性的值将在注册后提供.
Content-TypeThis is the content 类型 for POST requests.该API目前只支持application/json有效负载.

反应

所有来自API的响应有效负载将是JSON对象. The specific attributes found in the JSON response object depends on the specific URI being called.

Response Status Codes

Status  CodeDescription
200OK The request completed successfully and the response payload does not contain any errors.
204请求有效,API成功处理, but no information can be provided in the response.
400错误的请求错误API无法处理请求,因为缺少信息或API被错误使用. 错误消息将解释丢失的信息.
 401 由于用户未被成功授权,API无法处理请求. If this error is received, validate the user’s Authentication Token or reauthorize the user using the /身份验证 URI.
 403 Forbidden Error The API was unable to process the request because the user has been authenticated, but is not allowed to perform the desired request. Please contact support@www.china-heermeng.com when this error is received.
 429 API无法处理请求,因为已达到事务的最大数量.
 440 由于提供的信息不满足URI的先决条件,API无法处理请求. 错误消息将解释需要修复哪些信息.
 500 服务器内部错误服务器内部错误导致请求失败. Please contact support@www.china-heermeng.com when this error is received.

Commonly Used Fields

下面是请求和响应有效负载中常用的字段名列表. These fields are casesensitive.

字段名Description
job_id 当请求中需要一个异步作业id或者响应中可以找到一个异步作业id时使用.
batch_id 当请求中需要一个异步批处理id,或者在响应中可以找到一个异步批处理id时使用.
output_format 当请求中需要输出格式或响应中可以找到输出格式时使用. The API currently only supports: JSON for this field.
 notification_URL 当请求中需要异步通知URL或响应中可以找到异步通知URL时使用. Only the http protocol is supported. 如果提供了这个字段,则需要notification_method字段.
 notification_method 当请求中需要异步通知方法或响应中可以找到异步通知方法时使用. 如果提供了这个字段,则需要notification_URL字段. 该字段只支持GET和POST
 created_date 当请求中需要异步创建的日期或响应中可以找到异步创建的日期时使用.
 data 当请求中需要数据数组或响应中可以找到数据数组时使用.
 external_id Used when the user needs to provide ids to their records for their own future reference.
 first_nameUsed when a first name is needed in the request or when a first name can be found in the response.
 middle_name Used when a middle name is needed in the request or when a middle name can be found in the response.
 last_name Used when a 姓 is needed in the request or when a 姓 can be found in the response.
 address_1Used when an address is needed in the request or when as address can be found in the response.
 address_2 Used when an address needed the in the request or found in the response has two parts. 当没有找到address_1时,不应该使用这个参数.
 address_3 Used when an address needed the in the request or found in the response has three parts. 当没有找到address_1和address_2时,不应该使用此参数.
 street_number 当请求中需要地址街道号或在响应中可以找到地址街道号时使用.
 street_name 当请求中需要地址街道名称或在响应中可以找到地址街道名称时使用.
 street_类型 当请求中需要地址街道类型或响应中可以找到地址街道类型时使用.
 pre_direction 当请求中需要地址街名预方向或在响应中可以找到地址街名预方向时使用.
 post_direction 当请求中需要地址街道名称发送方向或当响应中可以找到地址街道名称发送方向时使用.
 unit_类型 当请求中需要地址单元类型或在响应中可以找到地址单元类型时使用.
 unit_number 当请求中需要地址单元号或在响应中可以找到地址单元号时使用.
 城市 Used when a 城市 is needed in the request or when a 城市 can be found in the response.
 状态 Used when a 状态 is needed in the request or when a 状态 can be found in the response. Depending on the URI, 这可以指示一个地址状态或系统中一个异步对象的状态.
 zipcode Used when a zipcode is needed in the request or when a zipcode can be found in the response.
 电话 Used when a 电话 number is needed in the request or when a 电话 number can be found in the response.
 电子邮件 Used when an 电子邮件 is needed in the request or when an 电子邮件 can be found in the response.
 ip Used when an IP Address is needed in the request or when an IP Address can be found in the response.

uri

Details

Below are the list of the available uri, their names, and descriptions about them:

的名字URIDescription
 Authorization/身份验证Authenticates the user with the username and password provided in the request payload. 这个URI在响应中返回一个身份验证令牌.
 Create Async Job/async/append/电子邮件/job 在请求有效负载中使用提供的电子邮件/job名称创建一个新的异步作业. This URI returns the created job’s id in the response.
 Retrieve Async Job /async/append/电子邮件/job/{jobid} 返回jobid参数指定的作业状态.
 Create Async 批处理 /async/append/电子邮件/job/{jobid}使用请求有效负载中提供的数据/batch为jobid参数指定的作业创建一个新的异步批处理. 这个URI在响应中返回创建的批处理的id.
Retrieve Async 批处理 Status /async/append/电子邮件/job/{jobid}返回由jobid和batchid参数指定的批处理状态.
 Retrieve Async 批处理 Result /async/append/电子邮件/job/{jobid}/batch/{batchid} Returns the data for the completed batch specified by the jobid and batch id parameters. If the specified batch has not been completed /result yet, an error message will be returned.
 Create Async 批处理 File /async/append/电子邮件/job/{jobid}/batchfile 为jobid参数指定的作业创建一个新的异步批处理文件.这个URI在响应中返回创建的批处理文件的id.
 Retrieve Async 批处理 File Status /async/append/电子邮件/job/{jobid}/batchfile/{batchid} 返回由jobid和batchid参数指定的批处理文件的状态.
 Retrieve Async 批处理 File Result /异步/添加/电子邮件/工作/ {jobid} / batchfile / {batchid} /结果 Returns the download url for the completed batch file specified by the jobid and batched parameters. If the specified batch file has not been completed yet, an error message will be returned.
 Address Standardization/sync/standardize/address标准化requestpayload中给出的地址,将其分解为单独的部分,并在可能的情况下提供关于地址的额外信息.
 Email Lookup /sync/lookup/电子邮件 Returns information about the owner of the 电子邮件 address provided in the request payload.
 IP查找 /sync/lookup/ip Returns information about the owner of the IP Address provided in the request payload.
 Mobile Lookup /sync/lookup/mobile Returns information about the owner of the mobile 电话 number provided in the request payload.
 Phone Lookup /sync/lookup/电话 Returns information about the owner of the 电话 number provided in the request payload.
 Skip Tracing Lookup /sync/lookup/skiptracing Returns the current and former addresses, the birth date, the death date, 以及请求负载中提供的人员的别名.
 Email Append /sync/append/电子邮件 返回与名字相关联的电子邮件地址, 姓, and address provided in the request payload.
 Mobile Append /sync/append/mobile 返回请求负载中提供的人员的移动电话号码.
 Phone Append /sync/append/电话 返回请求有效负载中提供的人的电话号码.
 Vehicle Append /sync/append/vehicle 返回请求载荷中提供的人当前拥有和以前拥有的所有车辆的列表…
 Demographics Append /sync/append/demographics 返回请求负载中提供的人员的大量人口统计和生活方式信息.
 Email Verify /sync/verify/电子邮件 返回对请求有效负载中提供的电子邮件的验证.
 Phone Verify /sync/verify/电话Returns a verification for the owner of the 电话 number provided in the request payload.
 TCPA /sync/verify/tcpa返回请求有效负载中提供的电话号码的状态验证.
 Disconnect Verify /sync/verify/disconnect Returns a disconnection status verification for the 电话 number provided in the request payload. Using The RealTime

uri

RealTime服务是以:/sync/开头的uri. 这些服务可用于立即返回单个记录的数据.

Using The Asynchronous Email Append uri

Creating An Asynchronous Job

异步电子邮件追加服务允许用户一次对大量的记录执行电子邮件追加. 首先,需要使用创建异步作业URI创建一个异步作业.

Formatting The Record Data

一旦创建了作业,将向用户提供一个作业id. With that job id, 用户可以选择创建批处理文件或批处理文件, 这取决于需要处理的记录的数量. Each record should be formatted as a JSON Object, 所有的记录应该放在一个JSON数组. 下面的字段名是JSON对象的有效属性:

  1. external_id
  2. first_name
  3. middle_name
  4. last_name
  5. address_1
  6. address_2
  7. address_3
  8. 城市
  9. 状态
  10. zipcode
  11. 电话

After all of the records are added to the JSON Array, 用户可以决定是创建一个批处理还是一个批处理文件. If the total size of the JSON Array is less than 10 MB, the user can create a 批处理. If, 然而, the total size is greater than or equal to 10 MB, the user will need to create a 批处理-File. If the total size is greater than 50 MB, JSON数组将需要被分割成多个批处理文件. 一个作业可以包含多个batch和多个batchfile, so any additional 批处理es or 批处理-Files which may be needed can be added to the same job.

Creating An Asynchronous 批处理

To create a 批处理, 使用创建异步批处理URI,并在请求负载的数据属性中提供JSON数组. 创建的批处理id将从创建异步批处理URI返回. 用户稍后将需要这个id来检查批处理的状态.

Creating An Asynchronous 批处理-File

To create a 批处理-File, use the Create Async 批处理 File URI, 它将返回创建的批处理的id和一个上传URL. 用户稍后将需要这个id来检查批处理的状态. Save the JSON Array in a .json文件,并使用提供的上传URL上传json文件.

检查异步批处理或批处理文件的状态

After some times has passed, 用户可以检查他们的批处理或批处理文件的状态,以确定他们的数据是否已经被处理. 要检查批处理的状态,请使用检索异步批处理状态URI. 要检查批处理文件的状态,请使用检索异步批处理文件状态URI.

The 批处理 or 批处理-File can be in several different 状态s, which are described below:

状态Description笔记
 WAITING_FOR_UPLOAD 此状态表明已经创建了批处理文件, but no data has been uploaded using the Upload URL provided This 状态 only exists for 批处理-Files. upon creation.This is the initial 状态 of 批处理-Files.
 MALFORMED_JSON This 状态 indicates that the data provided for the 批处理 or 批处理-File is not correctly formatted. The user will need to create a new valid. 批处理 or 批处理-File with correctly formatted data.This 状态 only exists for 批处理-Files.
 排队 此状态指示批处理或批处理文件数据已被接受,目前正在排队等待处理. This is the final 状态 for 批处理es and 批处理-Files when the input data is not valid.
 IN_PROGRESS 此状态表示当前正在处理批处理或批处理文件. This is the initial 状态 of 批处理es.
 完成 This 状态 indicates that the 批处理 or 批处理-File has finished processing successfully. This is the final 状态 for 批处理es and 批处理-Files when the process completes successfully.
 失败的 This 状态 indicates that the 批处理 or 批处理File has failed to process successfully. There are several reasons why this could happen; support@www.china-heermeng.com should be contacted to determine exactly why.This is the final 状态 for 批处理es and 批处理Files when the process does not complete successfully.

Retrieving The Asynchronous Job

After some times has passed, 用户还可以检查他们的Job的状态,以确定作业中所有批次的运行情况. To retrieve a Job, use the Retrieve Async Job URI, which will provide a breakdown of the current 状态s of all of the 批处理es or 批处理Files in the job, a list of the 批处理 and 批处理File ids for the job, and the overall 状态 of the job itself.

Job可以有几种不同的状态,具体描述如下:

状态Description笔记
创建This 状态 indicates that a Job has been created. 一旦所有的批处理和批处理文件被传递到WAITING_FOR_UPLOAD状态,作业就会从这个状态开始.This is the initial 状态 of Jobs.
IN_PROGRESS此状态表明作业中的所有批处理和批处理文件至少处于排队状态.
完成This 状态 indicates that all of the 批处理es and 批处理Files in the job are in the 完成 状态.This is the final 状态 for 批处理es and 批处理-Files when the process completes successfully.
失败的此状态表明作业中所有的批处理和批处理文件都已处理完毕,并且至少有一个批处理或批处理文件处于失败的或MALFORMED_JSON状态.当至少有一个批处理或批处理文件未成功处理时,这是作业的最终状态.

Using Notification URLs and Notification Methods

可以利用通知url和通知方法来接收对作业的自动更新, 批处理, and 批处理-File 状态s, which must be set at Job, 批处理, and 批处理-File creation. 设置了“通知URL”和“通知方式”, when the Job, 批处理, or 批处理-File completes, the system will send a message to the Notification URL. Please note that http is currently the only supported protocol for the Notification URLs.

These messages will contain the following attributes:

属性Description
 类型 The 类型 the message is for. Either: JOB, BATCH, or BATCHFILE
 id 消息的Job Id、批处理 Id或批处理- file Id.
 状态 The new 状态 of the entity the message is for. Either: 完成, 失败的, or MALFORMED_JSON

Two different Notification Methods are supported, 使用它们的规则如下所示.

GET Methods

When creating the Job, 批处理, or 批处理File, set the Notification Method attribute to: GET , and set the Notification URL attribute to the URL which should receive the update message. URL必须进行格式化,以便有关已完成内容的信息可以作为URL路径参数提供, using the path keys: {类型} , {id} , and {状态} . 例如,下面是一个有效的通知URL:

http://ww.例子.com/notification?类型=(类型)&id = (id)&状态=(状态)

POST Methods

When creating the Job, 批处理, or 批处理File, set the Notification Method attribute to: POST , and set the Notification URL attribute to the URL which should receive the update message. 对于URL的格式没有特殊要求. The message will be sent to the URL as a JSON Payload similar to the 例子 below:

{
类型: ...,
id: ...,
状态: ...
}

 Retrieving The 批处理 Result

在一个批处理成功完成之后,可以从该批处理检索数据. To retrieve that data, use the Retrieve Async 批处理 Result URI, which will respond with a JSON Array containing the valid records with 电子邮件 addresses appended. The 电子邮件 addresses for each record can be found in the 电子邮件 attribute of each record.

Retrieving The 批处理-File Result

After a 批处理-File has finished successfully, the data from that 批处理-File can be retrieved. To retrieve that data, use the Retrieve Async 批处理-File Result URI, which will respond with a Download URL. 使用提供的URL下载包含有效记录的JSON数组,并附加电子邮件地址. The 电子邮件 addresses for each record can be found in the 电子邮件 attribute of each record.