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.

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.

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.

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

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:
external_id
first_name
middle_name
last_name
address_1
address_2
address_3
city
state
zipcode
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.

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.

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

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.