Phone Append API Documentation
Real-Time Phone Append API for CRM Enrichment and Customer Data Completion
The Data Group Phone Append API helps developers, CRM teams, and data operations teams add phone numbers to existing customer, lead, and prospect records. Use this endpoint when you already have a name and address, but the phone field is missing, incomplete, or outdated. This API is built for real-time enrichment workflows, including CRM cleanup, lead routing, sales follow-up, call center preparation, SMS readiness, and multichannel marketing campaigns.What Is the Phone Append API?
The Phone Append API is a real-time data enrichment endpoint that returns a matched phone number when a reliable record is available.
This is different from reverse phone lookup.
Phone append starts with a known person or household record and tries to add a missing phone number.
Reverse phone lookup starts with a phone number and tries to identify the person or household connected to it.
This page is focused only on phone append API documentation. If your workflow starts with a phone number and needs name or address data, use the Reverse Phone API instead.
When To Use This API
Use the Phone Append API when your business has customer or lead records that are missing phone numbers.
Common use cases include:
- Completing missing CRM phone fields
- Enriching leads before sales routing
- Preparing customer records for call center workflows
- Supporting SMS and phone outreach readiness
- Improving speed-to-lead for sales teams
- Reactivating older customer or prospect records
- Connecting direct mail records to phone channels
- Improving database hygiene before campaign launch
- Building stronger multichannel marketing records
This API is especially useful when your team needs phone data in real time instead of waiting for a batch file process.
Who This API Is For
This API is designed for teams that need cleaner, more complete, and more usable customer records.
Common users include:
- Developers building data enrichment workflows
- CRM and RevOps teams improving contact records
- Sales teams trying to improve speed-to-lead
- Marketing teams preparing multichannel campaigns
- Call centers preparing outbound contact files
- Data operations teams reducing manual cleanup
- Agencies managing client customer or prospect databases
How the Phone Append API Works
The workflow is simple.
First, your application sends a customer or lead record to the API. The strongest input records usually include first name, last name, street address, and ZIP code.
Next, the API searches for a reliable phone match tied to that identity record.
If a match is found, the response returns phone details such as the phone number, phone type, first seen date, last seen date, telephone company name, phone verification value, and trace ID.
Your system can then write the returned phone data into your CRM, lead routing platform, call center system, marketing database, or internal application.
Best Input Fields for Matching
For stronger phone append results, send the cleanest identity data available.
Recommended fields include:
- First name
- Last name
- Street address
- ZIP code
Clean input data improves match quality. Incomplete, stale, misspelled, or poorly formatted records may reduce the chance of a successful match.
Quick Start
The TDG Phone Append API provides real-time access to phone append data so developers can enrich customer records through a RESTful interface.
Use this endpoint when your system needs to add a mobile or landline number to an existing customer, lead, or prospect record.
Authentication
To access The Data Group API services, each request must include an API key.
Your API key confirms that the request is authorized and allows your application to securely connect to the correct data service.
Obtaining an API Key
To obtain an API key, contact The Data Group. The team will review your request and provide access details.
Including the API Key in Requests
When interacting with The Data Group APIs, SDKs, or command-line tools, include your API key in the request header.
The API key acts as a unique identifier for your account and authorizes the request.
Best Practices for API Key Security
- Use HTTPS for every request.
- Do not expose your API key in public code repositories.
- Do not hard-code keys in client-side applications.
- Limit access to the key inside your organization.
- Monitor usage for unusual activity.
- Rotate keys when needed.
- Apply rate limits and access controls where possible.
Security
HTTPS is mandatory for all requests.
Request and response bodies are encoded as JSON.
Conventions
The Data Group API is organized into lookup, append, and verify 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 where possible, with most operations performed through POST requests. Request and response bodies use JSON.
Endpoint Specifications
Phone Append
Append verified phone numbers to contact records so your team can improve customer profiles, support outreach workflows, and reduce incomplete records.
Use this endpoint when your system already has a known person or household record and needs to append a phone number.
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"
}
Response Fields Explained
| Response Field | Description |
| Phone | The matched phone number returned for the submitted record. |
| PhoneType | The type of phone number returned. This can help your team decide whether the record is better suited for voice, SMS, or other outreach workflows. |
| FirstSeen | The first date the phone number was observed in the available data history. |
| LastSeen | The most recent date the phone number was observed in the available data history. |
| TelcoName | The telephone company or carrier information associated with the returned phone number when available. |
| PHV | The phone verification value. This helps your system understand the confidence or verification status of the returned phone data. |
| trace | A unique trace ID for the API request. Use this for debugging, reporting, support requests, and internal logging. |
Compliance Endpoint: TCPA Verify
TCPA Verify helps support compliance workflows by checking phone number append data before initiating automated calls or SMS outreach.
This endpoint can help teams add another review layer before activating appended phone data in outbound campaigns.
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"
}
Phone Append API vs Reverse Phone API
These two APIs solve different problems.
Use Phone Append API when:
- You already have a name and address.
- You need to add a missing phone number.
- You are enriching CRM records with phone data.
- You are preparing records for voice or SMS outreach.
Use Reverse Phone API when:
- You have a phone number and need to identify the person or household behind it.
- You need caller identification.
- You need to enrich phone-only records.
- You need identity lookup from a phone number.
Keeping these use cases separate helps users and search engines understand the purpose of each API page.
Phone Append API vs Batch Phone Append
The API is best when your system needs real-time enrichment.
Use the API when:
- Records are processed one at a time.
- Your workflow starts from a form, CRM event, or live request.
- Speed matters.
- Your team wants automated enrichment inside an application.
Use batch phone append when:
- You need to enrich a large file all at once.
- The project is campaign-based.
- Overnight or scheduled processing is acceptable.
- Your team is cleaning a database before launch.
Many teams use both. Batch processing works well for large historical files, while the API works well for new records entering your system.
Data Quality Tips
Phone append results depend on the quality of the record submitted.
To improve match performance:
- Use standardized names.
- Send complete street addresses when possible.
- Include ZIP codes.
- Avoid blank or partial records.
- Normalize formatting before sending requests.
- Remove duplicate records before processing.
- Suppress records that already have trusted phone numbers.
Better input data usually means better returned data.
Common Integration Workflows
| CRM Enrichment | Send new or existing CRM records to the API when the phone field is empty. If a match is returned, write the phone number back to the CRM. |
| Lead Routing | Enrich lead records before assigning them to sales teams. This helps improve contactability and speed-to-lead. |
| Call Center Preparation | Append phone numbers before outbound calling workflows so agents have more complete contact files. |
| Marketing Automation | Use appended phone numbers to support SMS, voice, direct mail follow-up, and multichannel campaign planning. |
| Data Operations | Automate phone append workflows instead of relying on manual list cleanup or one-off spreadsheet processes. |
Compliance and Responsible Use
Phone append data should be used carefully and within your organization’s legal, privacy, and compliance requirements.
Before using appended phone data, confirm:
- Whether your intended use is allowed.
- Whether consent is required for outreach.
- Whether TCPA verification is needed.
- How returned phone data will be stored.
- Who can access appended phone data.
- How suppression lists will be applied.
- How opt-outs will be honored.
The Data Group provides data and API tools, but your organization is responsible for how that data is used.
Developer Tools: SDK and Postman
TDG SDK
The TDG SDK is an open-source project designed to simplify the process of integrating The Data Group data services into your applications.
By using the SDK, developers can more easily access API functionality, structure requests, and connect data services to internal applications.
Access: Read Documentation on PyPI
Postman Collection
Postman is a tool that simplifies API development and testing. It allows developers to create, test, and manage API requests without writing code from scratch.
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 |
Related API and Data Services
- API Hub: Use this page to compare The Data Group API services and choose the right endpoint.
- Phone Append Services: Use this page for the full phone append service overview, including batch append options.
- Reverse Phone API: Use this when your workflow starts with a phone number and needs identity or household information.
- TCPA API: Use this for TCPA-related phone verification workflows.
- Email Append API: Use this when you need to append email addresses to existing records.
- Email Validation API: Use this when you need to verify whether an email address is valid and usable.
- Pricing: Review pricing options for data append and API services.
Frequently Asked Questions
What is a Phone Append API?
A Phone Append API is a real-time data service that adds a phone number to an existing customer, lead, or prospect record when a reliable match is available.
What information is required for phone append?
The main required fields are first name, last name, street address, and ZIP code. The better the input record, the better the chance of a successful match.
Is phone append the same as reverse phone lookup?
No. Phone append starts with a known person or address and returns a phone number. Reverse phone lookup starts with a phone number and returns identity or household information.
Can the API return mobile numbers?
The API may return phone type information, including wireless data when available.
Can this API be used for CRM enrichment?
Yes. CRM enrichment is one of the most common use cases for the Phone Append API.
Can this API be used for call center workflows?
Yes. Teams can use the API to enrich customer or lead records before outbound calling.
Does every request return a phone number?
No. A phone number is returned only when a reliable match is available.
What does a 204 response mean?
A 204 response means no record was found for the submitted request.
What does the trace field mean?
The trace field is a unique request identifier. It can be used for troubleshooting, logging, and support.
Does this page replace the main API hub?
No. This page is only for Phone Append API documentation. The main API overview should remain on the API hub page.
Ready To Use the Phone Append API?
