Phone Append API Documentation

Introduction The TDG Phone Append API provides real-time access to our master database of 700M+ verified records. This phone appending services endpoint allows developers to append phone numbers to existing customer profiles via a RESTful interface. By utilizing our telephone number appending logic, enterprises can execute a mobile phone append or landline identification to optimize dialing and SMS outreach.

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.

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]

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.

Best Practices Use HTTPS to encrypt API Key transmissions over the network, preventing interception by unauthorized parties. Implement rate limiting and access controls based on API Key usage to manage and monitor access effectively.

Security HTTPS is mandatory for all requests. Request and response bodies are encoded as JSON.

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.

ENDPOINT SPECIFICATIONS

Phone Append Append verified phone numbers to your contact records to enhance connectivity and execute high-volume telephone append workflows.

HEADERS

x-api-key (string) | required: Unique key obtained after contacting us.

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).

				
					POST: https://testapi.tdg1.io/v3/append/phone

				
					Sample Request

curl --location 'https://testapi.tdg1.io/v3/append/phone' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api_key>' \
--data '{
    "FName": "<Tom>",
    "LName": "<Smithj>",
    "Address1": "<123 Main Street>",
    "Zip": "<12345>"
}'

				
					Sample Response

{
  "Phone": "(555) 555-5555",
  "PhoneType": "Wireless",
  "FirstSeen": "12/1/2010",
  "LastSeen": "5/1/2025",
  "TelcoName": "Telconame",
  "PHV": 1,
  "trace": "30e4cd15-fbea-4849-a198-8a55189deaba1"
}

COMPLIANCE ENDPOINT (TCPA VERIFY)

TCPA Verify Ensure compliance with the Telephone Consumer Protection Act (TCPA) by verifying phone number append data before initiating automated calls or SMS.

BODY PARAMS

phone (string) | required: 10 digit numeric phone number (no spaces, dashes, or parentheses).
last_name (string) | required: Last name of the individual associated with the phone number.

				
					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: <api_key>' \
--data '{
    "phone": "<phone>",
    "last_name": "<Last name>"
}'

				
					Sample Response

{
    "verification_code": "U",
    "phone_type": "W"
}

DEVELOPER TOOLS (SDK & POSTMAN)

TDG SDK 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.

Access: Read Documentation on PyPI

Postman Collection 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.

Run in Postman: [Import TDG Collection]
Technical Docs: View Documentation

API RESPONSE CODES

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

Need Technical Assistance?

Our engineering team is available for custom integration support and technical consultations.