User Guide

The Datagroup API User Guide

About the API

The Data Group REST API provides a webbased API allows clients to achieve better direct marketing results at reduced costs.

The Data Group provides comprehensive, tailored services that meet the business objectives of all sizes of organizations, ranging from Fortune 1000 companies to startups. Our clients work in an array of industries, including insurance, financial, travel, retail, automotive, education, health, media, and telecommunications basically, any field that utilizes direct marketing.

Account Types

The API supports three different Account Types, which have different permissions.The different account types are described below.

Unrestricted Account

Unrestricted Accounts are paying accounts with unlimited access to all of the URIs. Sign up for a paying account with this level of access, or upgrade a different account to this level of access, by contacting: support@thedatagroup.com

Restricted Account

Restricted Accounts are paying accounts with unlimited access to all of the URIs, excluding the Asynchronous Email Append URIs. Sign up for a paying account with this level of access, or upgrade a different account to this level of access, by contacting: support@thedatagroup.com

Trial Account

Trial Accounts are nonpaying, temporary accounts. These accounts have a limited number of queries to the API and do not have permission to use the Asynchronous Email Append URIs. Keep in mind that queries which do not return results still count against the Trial Account query limits. Trial Accounts can be upgraded to Unrestricted Accounts or Restricted Accounts, or extended, by contacting: support@thedatagroup.com

Requests

All request payloads to the API should be provided as JSON objects. The specific attributes required for each request payload depends on the specific URI being called. Furthermore, all requests to the API must contain the following header attributes:

Header Attribute Description Notes
AuthorizationToken This is the authorization token and is required for accessing the API. The value for this attribute is obtained by calling the /auth URI. This header is  not required when calling the /auth URI.
x-api-key This is the API Key needed to access the API. The value for this attribute will be provided after registration.
Content-Type This is the content type for POST requests. The API currently only supports application/json payloads.

Responses

All response payloads from the API will be JSON objects. The specific attributes found in the JSON response object depends on the specific URI being called.

Response Status Codes

Status  Code Description
200 OK The request completed successfully and the response payload does not contain any errors.
204 No Content The request was valid and the API processed it successfully, but no information can be provided in the response.
400 Bad Request Error The API was unable to process the request because there was missing information or the API was used incorrectly. The error message will explain what information is missing.
 401  Unauthorized Error The API was unable to process the request because the user has not been successfully authorized. If this error is received, validate the user’s Authentication Token or reauthorize the user using the /auth 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@thedatagroup.com when this error is received.
 429  Too Many Request The API was unable to process the request because the maximum number of transactions have been reached.
 440  Illegal Input Error The API was unable to process the request because the information provided does not fulfil the URI’s preconditions. The error message will explain what information needs to be fixed.
 500  Internal Server Error The request failed due to an error on the server. Please contact support@thedatagroup.com when this error is received.

Commonly Used Fields

Below is a list of commonly used field names in the requests and response payloads. These fields are casesensitive.

Field Name Description
job_id  Used when an async job id is needed in the request or when an async job id can be found in the response.
batch_id  Used when an async batch id is needed in the request or when an async batch id can be found in the response.
output_format  Used when an output format is needed in the request or when an output format can be found in the response. The API currently only supports: JSON for this field.
 notification_URL  Used when an async notification URL is needed in the request or when an async notification URL can be found in the response. Only the https protocol is supported. If this field is provided, the notification_method field will be required.
 notification_method  Used when an async notification method is needed in the request or when an async notification method can be found in the response. If this field is provided, the notification_URL field will be required. This field only supports the following values: GET and POST
 created_date  Used when an async created date is needed in the request or when an async created date can be found in the response.
 data  Used when an array of data is needed in the request or when an array of data can be found in the response.
 external_id  Used when the user needs to provide ids to their records for their own future reference.
 first_name Used 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 last name is needed in the request or when a last name can be found in the response.
 address_1 Used 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. This parameter should not be expected when address_1 is not found.
 address_3  Used when an address needed the in the request or found in the response has three parts. This parameter should not be expected when address_1 and address_2 is not found.
 street_number  Used when an address street number is needed in the request or when an address street number can be found in the response.
 street_name  Used when an address street name is needed in the request or when an address street name can be found in the response.
 street_type  Used when an address street type is needed in the request or when an address street type can be found in the response.
 pre_direction  Used when an address street name pre direction is needed in the request or when an address street name pre direction can be found in the response.
 post_direction  Used when an address street name post direction is needed in the request or when an address street name post direction can be found in the response.
 unit_type  Used when an address unit type is needed in the request or when an address unit type can be found in the response.
 unit_number  Used when an address unit number is needed in the request or when an address unit number can be found in the response.
 city  Used when a city is needed in the request or when a city can be found in the response.
 state  Used when a state is needed in the request or when a state can be found in the response. Depending on the URI, this can indicate an address state or the state of an async object in the system.
 zipcode  Used when a zipcode is needed in the request or when a zipcode can be found in the response.
 phone  Used when a phone number is needed in the request or when a phone number can be found in the response.
 email  Used when an email is needed in the request or when an email 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.

URIs

Details

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

Name URI Description
 Authorization /auth Authenticates the user with the username and password provided in the request payload. This URI returns an Authentication Token in the response.
 Create Async Job /async/append/email/job  Creates a new async job with the name provided email/job in the request payload. This URI returns the created job’s id in the response.
 Retrieve Async Job  /async/append/email/job/{jobid}  Returns the status of the job specified by the jobid parameter.
 Create Async Batch  /async/append/email/job/{jobid} Creates a new async batch for the job specified by the jobid parameter with the data provided /batch in the request payload. This URI returns the created batch’s id in the response.
Retrieve Async Batch Status  /async/append/email/job/{jobid} Returns the status of the batch specified by the jobid and batchid parameters.
 Retrieve Async Batch Result  /async/append/email/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 Batch File  /async/append/email/job/{jobid}/batchfile  Creates a new async batch file for the job specified by the jobid parameter.This URI returns the created batch file’s id in the response.
 Retrieve Async Batch File Status  /async/append/email/job/{jobid}/batchfile/{batchid}  Returns the status of the batch file specified by the jobid and batchid parameters.
 Retrieve Async Batch File Result  /async/append/email/job/{jobid}/batchfile/{batchid}/result  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 Standardizes the address given in the requestpayload by breaking it down into individual parts and providing additional information about the address when possible.
 Email Lookup  /sync/lookup/email  Returns information about the owner of the email address provided in the request payload.
 IP Lookup  /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 phone number provided in the request payload.
 Phone Lookup  /sync/lookup/phone  Returns information about the owner of the phone number provided in the request payload.
 Skip Tracing Lookup  /sync/lookup/skiptracing  Returns the current and former addresses, the birth date, the death date, and the aliases for the person provided in the request payload.
 Email Append  /sync/append/email  Returns an email address associated with the first name, last name, and address provided in the request payload.
 Mobile Append  /sync/append/mobile  Returns a mobile phone number for the person provided in the request payload.
 Phone Append  /sync/append/phone  Returns a phone number for the person provided in the request payload.
 Vehicle Append  /sync/append/vehicle  Returns a list of all the vehicles currently owned and previously owned for the person provided in the request payload…
 Demographics Append  /sync/append/demographics  Returns a large amount of demographic and lifestyle information for the person provided in the request payload.
 Email Verify  /sync/verify/email  Returns a verification for the email provided in the request payload.
 Phone Verify  /sync/verify/phone Returns a verification for the owner of the phone number provided in the request payload.
 TCPA  /sync/verify/tcpa Returns a status verification for the phone number provided in the request payload.
 Disconnect Verify  /sync/verify/disconnect  Returns a disconnection status verification for the phone number provided in the request payload. Using The RealTime

URIs

The RealTime Services are the URIs which begin with: /sync/. These Services can be used to immediately return data for individual records.

Using The Asynchronous Email Append URIs

Creating An Asynchronous Job

The Asynchronous Email Append Services allows the user to perform Email Appends on a massive amount of records at once. To begin, an asynchronous job needs to be created, using the Create Async Job URI.

Formatting The Record Data

Once the job is created, the user will be provided to a job id. With that job id, the user can choose to create either a Batch or a Batch-File, depending on the number of records which needs to be processed. Each record should be formatted as a JSON Object, and all of the records should be placed in a JSON Array. The following field names are valid attributes for the JSON Object:

  1. external_id
  2. first_name
  3. middle_name
  4. last_name
  5. address_1
  6. address_2
  7. address_3
  8. city
  9. state
  10. zipcode
  11. phone

After all of the records are added to the JSON Array, the user can determine if they should create a Batch or a Batch-File. If the total size of the JSON Array is less than 10 MB, the user can create a Batch. If, however, the total size is greater than or equal to 10 MB, the user will need to create a Batch-File. If the total size is greater than 50 MB, the JSON Array will need to be split up into multiple Batch-Files. A job can contain multiple Batches and multiple BatchFiles, so any additional Batches or Batch-Files which may be needed can be added to the same job.

Creating An Asynchronous Batch

To create a Batch, use the Create Async Batch URI and provide the JSON Array in the data attribute of the request payload. The created Batch’s id will be returned from the Create Async Batch URI. The user will need this id later to check on the status of their Batch.

Creating An Asynchronous Batch-File

To create a Batch-File, use the Create Async Batch File URI, which will return the create Batch’s id and an Upload URL. The user will need this id later to check on the status of their Batch. Save the JSON Array in a .json file and upload the JSON File using the provided Upload URL.

Checking On The State Of The Asynchronous Batch or Batch-File

After some times has passed, the user can check the state of their Batch or their Batch-File to determine if their data is done being processed. To check the state of a Batch, use the Retrieve Async Batch Status URI. To check the state of a Batch-File, use the Retrieve Async Batch File Status URI.

The Batch or Batch-File can be in several different states, which are described below:

State Description Notes
 WAITING_FOR_UPLOAD  This state indicates that a Batch-File has been created, but no data has been uploaded using the Upload URL provided This state only exists for Batch-Files. upon creation. This is the initial state of Batch-Files.
 MALFORMED_JSON  This state indicates that the data provided for the Batch or Batch-File is not correctly formatted. The user will need to create a new valid. Batch or Batch-File with correctly formatted data. This state only exists for Batch-Files.
 QUEUED  This state indicates that the Batch or Batch-File data has been accepted and is currently queued to be processed.  This is the final state for Batches and Batch-Files when the input data is not valid.
 IN_PROGRESS  This state indicates that the Batch or Batch-File is currently being processed.  This is the initial state of Batches.
 COMPLETED  This state indicates that the Batch or Batch-File has finished processing successfully.  This is the final state for Batches and Batch-Files when the process completes successfully.
 FAILED  This state indicates that the Batch or BatchFile has failed to process successfully. There are several reasons why this could happen; support@thedatagroup.com should be contacted to determine exactly why. This is the final state for Batches and BatchFiles when the process does not complete successfully.

Retrieving The Asynchronous Job

After some times has passed, the user can also check the state of their Job to determine how all of the batches in the job are going. To retrieve a Job, use the Retrieve Async Job URI, which will provide a breakdown of the current states of all of the Batches or BatchFiles in the job, a list of the Batch and BatchFile ids for the job, and the overall state of the job itself.

The Job can be in several different states, which are described below:

State Description Notes
CREATED This state indicates that a Job has been created. The job will progress from this state once all of the Batches and Batch-Files are passed the WAITING_FOR_UPLOAD state. This is the initial state of Jobs.
IN_PROGRESS This state indicates that all of the Batches and Batch-Files in the job are at least in the QUEUED state.
COMPLETED This state indicates that all of the Batches and BatchFiles in the job are in the COMPLETED state. This is the final state for Batches and Batch-Files when the process completes successfully.
FAILED This state indicates that all of the Batches and Batch-Files in the job are finished being processed and at least one Batch or Batch-File is in the FAILED or MALFORMED_JSON state. This is the final state for Jobs when at least one Batch or Batch-File has not processed successfully.

Using Notification URLs and Notification Methods

It is possible to leverage Notification URLs and Notification Methods to receive automatic updates to your Job, Batch, and Batch-File states, which must be set at Job, Batch, and Batch-File creation. If a Notification URL and Notification Method is specified, when the Job, Batch, or Batch-File completes, the system will send a message to the Notification URL. Please note that https is currently the only supported protocol for the Notification URLs.

These messages will contain the following attributes:

Attribute Description
 type  The type the message is for. Either: JOB, BATCH, or BATCHFILE
 id  The Job Id, Batch Id, or Batch-File Id the message is for.
 state  The new state of the entity the message is for. Either: COMPLETED, FAILED, or MALFORMED_JSON

Two different Notification Methods are supported, and the rules for using each of them can be found below.

GET Methods

When creating the Job, Batch, or BatchFile, set the Notification Method attribute to: GET , and set the Notification URL attribute to the URL which should receive the update message. The URL must be formatted such that the information about what has completed can be provided as URL path parameters, using the path keys: {type} , {id} , and {state} . For example, the following would be a valid Notification URL:

https://ww.example.com/notification?type=(type)&id=(id)&state=(state)

POST Methods

When creating the Job, Batch, or BatchFile, set the Notification Method attribute to: POST , and set the Notification URL attribute to the URL which should receive the update message. There are no special requirements for how the URL should be formatted. The message will be sent to the URL as a JSON Payload similar to the example below:

{
type: ...,
id: ...,
state: ...
}
 Retrieving The Batch Result

After a Batch has finished successfully, the data from that Batch can be retrieved. To retrieve that data, use the Retrieve Async Batch Result URI, which will respond with a JSON Array containing the valid records with email addresses appended. The email addresses for each record can be found in the email attribute of each record.

Retrieving The Batch-File Result

After a Batch-File has finished successfully, the data from that Batch-File can be retrieved. To retrieve that data, use the Retrieve Async Batch-File Result URI, which will respond with a Download URL. Use the provided URL to download the JSON Array containing the valid records with email addressed appended. The email addresses for each record can be found in the email attribute of each record.