Quick Start
The TDG API enhances data by offering a suite of functionalities designed to verify, look up, and append information. Through its various endpoints, the API provides tailored solutions that cater to specific user needs. Each endpoint is dedicated to a distinct function, allowing users to efficiently manage and enrich their data according to their requirements. Whether you need to validate data accuracy, perform detailed lookups, or add supplementary information, the TDG API's comprehensive features ensure that you have the tools necessary to optimize your data management processes.
Get Your API Key
To obtain an API key, please contact us. Our team will respond and provide your API key within 24 hours.
Contact Us
>
Authentication
To access data, you must authenticate your requests using an API Key. By authenticating your requests with an API Key, you ensure secure and authorized access to our data services, allowing you to integrate our comprehensive and reliable data seamlessly into your applications and workflows.
API Keys
Obtaining an API Key
To obtain an API key, please contact us. Our team will respond and provide your API key within 24 hours.
Contact Us
>
API Keys ensure secure access to our APIs by verifying the identity of the requester. They prevent unauthorized access and help protect sensitive data and resources.
Including the API Key in Requests
When interacting with our data services through APIs, SDKs, or command-line interfaces (CLI), it's essential to include your API Key in the request. This API Key acts as a unique identifier that authenticates and authorizes your request to access our data. Detailed documentation for each method specifies how to configure and use your API Key.
Managing Your API Key
Proper management of your API Key is crucial. Ensure it is kept confidential and not shared publicly or hard-coded in client-side applications. Rotate your keys periodically and revoke them immediately if compromised.
Best Practices
  1. Use HTTPS to encrypt API Key transmissions over the network, preventing interception by unauthorized parties.

  2. Implement rate limiting and access controls based on API Key usage to manage and monitor access effectively.
APIs Overview
The TDG API enriches the data and provides functionality to verify, lookup or append the data through APIs which have different endpoints to serve different functionality based on the user's needs.

They follows RESTful conventions when possible, with most operations performed via POST requests on database resources. Request and response bodies are encoded as JSON.
Get Your API Key
To obtain an API key, please contact us. Our team will respond and provide your API key within 24 hours.
Contact Us
>
Conventions
The base URL to send API requests is segregated into 3 categories.



Lookup: https://api.tdg1.io/v2/lookup
Append: https://api.tdg1.io/v2/append
Verify: https://api.tdg1.io/v2/verify
HTTPS is required for all API requests. The TDG API follows RESTful conventions when possible, with most operations performed via POST requests on database resources. Request and response bodies are encoded as JSON.
Supported Endpoints
Our API provides various endpoints categorized into Append, Lookup, and Verify to cater to your specific data needs. These categories help you enhance, retrieve, and validate your data efficiently.
Append Endpoints
Append endpoints are used to enrich your existing records by adding missing information. This helps to create a more complete and accurate database, improving your ability to communicate with and understand your customers.
Lookup Endpoints
Lookup endpoints are designed to retrieve detailed information associated with specific data points. This allows you to gain deeper insights and verify the accuracy of your existing data.
Verify Endpoints
Verify endpoints ensure the data you have is accurate and up-to-date. These endpoints are essential for maintaining data quality and ensuring compliance with regulations.
End Point
Description
Auto Append
Automatically append missing data to your records.
Demographic Append
Append demographic details like age, gender, and income.
Email Append
Append email addresses to your contact records.
Phone Append
Append phone numbers to your existing records.
Email Lookup
Retrieve information associated with email addresses.
Email Verify
Verify the accuracy and deliverability of email addresses.
TCPA Verify
Verify phone numbers for compliance with TCPA regulations.
ID Verify
Verify the identity of individuals to prevent fraud.
API Response Codes
Understanding API response codes is essential for handling the outcomes of your API requests effectively. Here is a list of possible response codes and their descriptions:
HTTPS STATUS CODE
Description
200
Successful
204
No Records found
400
Missing required parameter(s)
440
Too many results. Please refine your search criteria
429
You have reached the maximum number of transactions allowed
401
The user is invalid (verify your credentials)
500
System error. Retry search, if failure continues, contact support
SDKs
The TDG SDK is an open-source project designed to simplify the process of integrating our data services into your applications. By using the SDK, developers can easily access and utilize our API functionalities, ensuring a smooth and efficient development experience.
Read Documentation
>
Postman
Postman is a powerful tool that simplifies API development and testing. It allows you to easily create, test, and manage your API requests without writing any code. Using Postman with the TDG API provides a user-friendly way to explore and integrate our data services.
Run in Postman
>
Read Documentation
>
Append APIs
Auto Append
Automatically append missing data to your existing records to enhance your database with the most accurate and up-to-date information.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us. This is required.
BODY PARAMS
Phone
string
conditionally required*
10 digit numeric phone number (without spaces, dashes, or parentheses.
*Required if Phone and other parameters are not included
Email
string
conditionally required*
Individual’s email address. 100 characters max.
*Required if Phone and other parameters are not included
FullName
string
conditionally required*
Individual’s full name.
*FullName, Address1 and Zip parameters are required altogether.
Address1
string
conditionally required*
Individual’s full name.
*FullName, Address1 and Zip parameters are required altogether.
Zip
string
conditionally required*
5 digit numeric USPS zip code.
*FullName, Address1 and Zip parameters are required altogether.
POST
https://api.tdg1.io/v2/append/auto
Sample Request
curl --location 'https://api.tdg1.io/v2/append/auto' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data-raw '
{
"Phone": "<phone>",
"Email": "<email>",
"FullName": "<full name>",
"Address1": "<address>",
"Zip": "<zip>"
}'
Sample Response
{
"Name": {
"FName": "Tom",
"LName": "Smith",
"MName": "A",
"Suffix": ""
},
"Address": {
"House": "123",
"PreDir": "",
"Street": "LONG LAKE",
"StrType": "",
"PostDir": "",
"AptType": "",
"AptNbr": "",
"City": "Orlando",
"State": "FL",
"Zip": "12345",
"Z4": "9111",
"DPC": "564",
"CRTE": "R019",
"CNTY": "SEM",
"Z4Type": "S",
"DPV": "Y",
"Vacant": "N",
"MSA": "5960",
"CBSA": "36740"
},
"IDS": {
"PID": "Y67511710678784",
"AID": "Y00000676763",
"HHID": "Y0000007676"
},
"Vehicle": {
"Make": "Hyundai",
"Model": "Creta",
"Year": "2020",
"ClassCD": "Sedan",
"FuelTypeCD": "G",
"MFGCD": "",
"StyleCD": "UTIL",
"Mileages": "A",
"ODate": "20001025"
},
 "Vehicle2": {
        "Make": "Porsche",
        "Model": "camrea",
        "Year": "2019",
        "ClassCD": "Sedan",
        "FuelTypeCD": "G",
        "MFGCD": "",
        "StyleCD": "UTIL",
        "Mileages": "A",
        "ODate": "20101103"
    },
    "Vehicle3": {
        "Make": "TOYOTA",
        "Model": "Corolla Altis",
        "Year": "2019",
        "ClassCD": "Sedan",
        "FuelTypeCD": "G",
        "MFGCD": "",
        "StyleCD": "PICKUP",
        "Mileages": "A",
        "ODate": "20090809"
    },
    "Vehicle4": {
        "Make": "",
        "Model": "",
        "Year": "",
        "ClassCD": "",
        "FuelTypeCD": "",
        "MFGCD": "",
 "StyleCD": "",
        "Mileages": "",
        "ODate": ""
    }
}
Demographic Append
Append demographic details such as age, gender, and income to your records for better customer profiling and targeted marketing.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us. This is required.
BODY PARAMS
FName
string
conditionally required*
First name, 15 characters max.
*Should be a combination of FName, LName, Zip and Address parameters; Phone or Email is Required
LName
string
conditionally required*
Last name, 20 characters max
*Should be a combination of FName,LName,Zip and Address parameters; Phone or Email is Required
Address1
string
conditionally required*
Address line 1, 64 characters max.
*Should be a combination of FName,LName,Zip and Address parameters; Phone or Email is Required
Zip
string
conditionally required*
5 digit numeric USPS zip code. * Either City/State or Zip is required
*Should be a combination of FName,LName,Zip and Address parameters; Phone or Email is Required.  Either City/State or Zip is required.
Phone
string
conditionally required*
10 digit numeric phone number (without spaces, dashes, or parentheses.
*Required if Email is not included and other parameters are included
Email
string
conditionally required*
Email address, 100 characters max
*Required if phone is not included and other parameters are included
City
string
optional*
City name, 28 characters max.
*Either City/State or Zip is required
State
string
optional*
2 character state abbreviation.
*Either City/State or Zip is required
POST
https://api.tdg1.io/v2/append/append/demographic
Sample Request
curl --location 'https://api.tdg1.io/v2/append/demographic' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data-raw '
{
"FName": "<FName>",
"LName": "<LName>",
"Address1": "<Address1>",
"Zip": "<Zip>",
"Phone":"<Phone>",
"Email": "<Email>"

}'
Sample Response
{
"Demographics": {
"Gender": "",
"Age": "",
"DOB": "",
"LOR": "06",
"Homeowner": "H",
"EHI": "F",
"DwellType": "S",
"Married": "M",
"MedYrBld": "1998",
"MobHome": "",
"Pool": "",
"FirePl": "",
"SglParent": "",
"HHNBRSR": "",
"CreditCard": "",
"WealthScr": "H",
"CharityDnr": "",
"MrktHomeVal": "N",
"Education": "",
"Ethnicity": "",
"ChildCd": "Y",
"ChildAgeCd": "A",
"ChildNbrCd": "",
"VehLux": "",
"VehSuv": "Y",
"VehTrk": "Y",
"PctBlk": "R",
"PctWht": "E",
"PctHsp": "Q",
"PctAsi": "T",
"PctEngSpeak": "D",
"PctSpnSpeak": "S",
"PctAsiaSpeak": "T",
"PctSFDU": "A",
"PctMFDU": "",
"MHV": "E",
"MOR": "G",
"PctAuto": "A",
"MedSchl": "153",
"PctWhiteCollar": "K",
"PctBlueCollar": "T",
"PctOccO": "K",
"DemoLvl": "1"
}
}
Email Append
Append email addresses to your existing contact records to improve communication channels and marketing outreach.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us. This is required.
BODY PARAMS
FName
string
conditionally required*
First name, 15 characters max.
*Required if LName, Address1, Zip is included
LName
string
conditionally required*
Last name, 20 characters max
*Required if FName, Address1, Zip is included
Address1
string
conditionally required*
Address line 1, 64 characters max.
*Required if FName, LName and Zip is included
Zip
string
conditionally required*
5 digit numeric USPS zip code.
*Required if FName, LName and Address is included. Either City/State or Zip is required.
Suppression
string
optional*
Suppress records containing restrictions, True or False. Default: Suppression=True.
includemonths
string
optional*
Integer value in months. For example, IncludeMonths=24 would include records that have been validated within the last 2 years. By default, all matches are included regardless of validation date.
*FullName, Address1 and Zip parameters are required altogether.
max_score
string
optional*
Filters by Match Score, 3 characters max. maxscore=299 will include all individual and household level matches
*FullName, Address1 and Zip parameters are required altogether.
POST
https://api.tdg1.io/v2/append/email
Sample Request
curl --location 'https://api.tdg1.io/v2/append/email' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"FName": "<FName>",
"LName": "<LName>",
"Address1": "<Address1>",
"Zip": "<Zip>"
}'
Sample Response
{
"email": "Tom.Smith@Sample.com",
"suppression": "",
"score": "300",
"category": "A"
}
Phone Append
Append phone numbers to your existing records to enhance your ability to reach customers via phone.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us. This is required.
BODY PARAMS
FName
string
required
First name, 15 characters max.
LName
string
required
Last name, 15 characters max
Address1
string
required
Address line 1 (example: 123 Main Street), 60 characters max.
Zip
string
conditionally required*
5 digit numeric USPS zip code.
*Either City/State or Zip is required.
Maxscore
string
optional*
Filters by Match Score, 3 characters max. maxscore=299 will include all individual and household level matches.
POST
https://api.tdg1.io/v2/append/phone
Sample Request
curl --location 'https://api.tdg1.io/v2/append/phone' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"FName": "<First name>",
"LName": "<Last name>",
"Address1": "<Address1>",
"Zip": "<Zip>",
"Maxscore": " <Maxscore>"
}'
Sample Response
{
"phone": "5555555555",
"phoneType": "V",
"DID": "",
"recType": "R",
"iDate": "20211003",
"oDate": "20211003",
"telcoName": "BRIGHT HOUSE NTWS INFORMATION SVCS (FLORIDA) - FL",
"PHV": "5",
"daCode": "D"
}
Lookup APIs
Email Lookup
Look up email addresses to retrieve associated information and verify the validity and status of the emails.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us.
BODY PARAMS
Email
string
required
Email address. 100 Characters max.
POST
https://api.tdg1.io/v2/lookup/email
Sample Request
curl --location 'https://api.tdg1.io/v2/lookup/email' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"Email": "<Email address>"
}'
Sample Response
{
"Name": {
"LName": "Tom",
"FName": "Smith",
"MName": "",
"BusName": ""
},
"Address": {
"House": "1432",
"PreDir": "S",
"Street": "ORACLE",
"StrType": "",
"PostDir": "",
"AptType": "",
"AptNbr": "",
"City": "Orlando",
"State": "FL",
"Zip": "32803",
"Z4": "6045",
"DPC": "321",
"CRTE": "C016",
"CNTY": "013",
"Z4Type": "S",
"DPV": "Y",
"Deliverable": "Y",
"ValDate": "20240411"
},
"Email": "Tom.Smith@Sample.com",
"Suppression": "B"
}
Phone Lookup
Look up phone numbers to retrieve associated information and verify the accuracy and status of the numbers.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us.
BODY PARAMS
Phone
string
required
10 digit numeric phone number (without spaces, dashes, or parentheses.
POST
https://api.tdg1.io/v2/lookup/phone
Sample Request
curl --location 'https://api.tdg1.io/v2/lookup/phone' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"Phone":"<phone>"
}'
Sample Response
{
"Person": {
"Name": {
"LName": "Smith",
"FName": "Tom",
"MName": "",
"BusName": "UNKNOWN CALLER"
},
"Address": {
"House": "",
"PreDir": "",
"Street": "",
"StrType": "",
"PostDir": "",
"AptType": "",
"AptNbr": "",
"City": "Orlando",
"State": "FL",
"Zip": "32803",
"Z4": "",
"DPC": "",
"CRTE": "",
"CNTY": "",
"Z4Type": "",
"DPV": "",
"Deliverable": "",
"ValDate": ""
},
"Phone": {
"Phone": "5555555555",
"PhoneType": "",
"DID": "",
"RecType": "",
"IDate": "",
"ODate": "",
"TelcoName": "",
 "PHV": "",
            "DACode": "",
            "Source": "NPAtoState"
        }
    }
}
Verify APIs
Email Verify
Verify the deliverability and accuracy of email addresses in your database to ensure successful email campaigns.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us.
BODY PARAMS
Email
string
required
Email address. 100 Characters max.
POST
https://api.tdg1.io/v2/verify/email
Sample Request
curl --location 'https://api.tdg1.io/v2/verify/email' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"Email":"<Email Address>"
}'
Sample Response
{
"Email": "Tom.Smith@Sample.com",
"Result": "Complainer"
}
TCPA Verify
Ensure compliance with the Telephone Consumer Protection Act (TCPA) by verifying phone numbers for telemarketing and automated calls.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us.
BODY PARAMS
Phone
string
required
10 digit numeric phone number (without spaces, dashes, or parentheses.
*Required if Phone and other parameters are not included
last_name
string
required
Last name
POST
https://api.tdg1.io/v2/verify/tcpa
Sample Request
curl --location 'https://api.tdg1.io/v2/verify/tcpa' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '
{
"phone": "<phone>",
"last_name": "<Last name>"
}'
Sample Response
{
"verification_code": "U",
"phone_type": "W"
}
ID Verify
Verify the identity of individuals using various data points to prevent fraud and ensure the accuracy of your records.
HEADERS
x-api-key
string
required
Unique key obtained after contacting us.
BODY PARAMS
FName
string
required if*
Individual’s full name.
*Required if you want to verify FName, Phone and Email is required when x accuracy is needed with FName
LName
string
required if*
Last name, 20 characters max.
*Required if you want to verify LName. Phone and Email is required when relative accuracy is needed with LName
Address1
string
required if*
Address line 1, 64 characters max.
*Required if you want to verify Address, Phone and Email is required when relative accuracy is needed with Address
Zip
string
required if*
5 digit numeric USPS zip code. * Either City/State or Zip is required.
*Required if you want to verify Zip, Phone and Email is required when relative accuracy is needed with Zip
Phone
string
required if*
10 digit numeric phone number (without spaces, dashes, or parentheses.
*Required if want to verify Phone, other parameters are needed if relative accuracy with other params are required
Email
string
required if*
Email address, 100 characters max.
*Required if want to verify Email, other parameters are needed if relative accuracy with other params are required
POST
https://api.tdg1.io/v2/verify/id
Sample Request
curl --location 'https://api.tdg1.io/v2/verify/id' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data-raw '
{
"FName": "<FName>",
"LName": "<LName>",
"Address1": "<Address1>",
"Zip": "<Zip>",
"Phone": "<Phone>",
"Email": "<Email>"
}'
Sample Response
{
"IDScores": {
"ValidAddress": "85",
"ValidPhone": "0",
"ValidEmail": "",
"ValidName": "100",
"ValidZip": "0",
"Deceased": "100",
"NameToPhone": "0",
"NameToEmail": "",
"NameToAddress": "0",
"AddressToPhone": "0",
"AddressToEmail": "",
"PhoneToEmail": "",
"ZipToPhone": "",
"USLocation": "",
"ValidPhone2": "",
"NameToPhone2": "",
"AddressToPhone2": "",
"Phone2ToEmail": "",
"PhoneConfidenceScore": "0",
"Phone2ConfidenceScore": "",
"AddressConfidenceScore": "0",
"ValidCount": "1.8",
"LinkageCount": "0",
"RiskFlagCount": "0",
"ValidationSummary": "FAIL",
"LinkageSummary": "FAIL",
"RiskFlagSummary": "PASS",
"IDVerifyScore": "76"
}
}