User Guide
About the API
The Data Group REST API provides a web based 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: API@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: API@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 |
|---|---|---|
| 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 API@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 API@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 case sensitive.
| 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. |
| 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. |
| 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. |
| 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. |
| TCPA | /sync/verify/tcpa | Returns a status verification for the phone number provided in the request payload. |
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
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
Using Notification URLs and Notification Methods
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: ...
}
