Reverse Phone Append API Documentation
Real-Time Reverse Phone Lookup API for Identity Resolution
The Data Group Reverse Phone Append API helps developers and data teams start with a phone number and return linked identity data when a reliable match is available. Use it to identify the person, household, or address associated with a 10-digit phone number. This API is built for lead validation, caller identification, CRM enrichment, fraud review, form verification, call center workflows, and identity resolution.What Is the Reverse Phone Append API?
The Reverse Phone Append API is a real-time phone lookup endpoint that uses a submitted phone number to return available identity and address data.
This is different from phone append.
Reverse phone append starts with a phone number and tries to return name and address information connected to that number.
Phone append starts with a known person or address record and tries to add a missing phone number.
This page is focused only on reverse phone append API documentation. If your workflow starts with a name and address and needs a phone number, use the Phone Append API instead.
When To Use This API
Use the Reverse Phone Append API when your business receives or stores phone numbers but needs more information about the person or household behind the number.
Common use cases include:
- Caller identification
- Lead validation
- CRM record enrichment
- Inbound call intelligence
- Fraud review and identity checks
- Form verification
- Customer support routing
- Right-party contact workflows
- Marketing database enrichment
This API is useful when your system needs identity data in real time instead of waiting for a batch enrichment project.
Who This API Is For
This API is built for teams that need to turn phone-only records into more complete customer or lead profiles.
Common users include:
- Developers building lookup and enrichment workflows
- CRM teams improving incomplete contact records
- Call centers identifying inbound or outbound phone records
- Sales teams validating lead data before follow-up
- Marketing teams improving audience records
- Fraud and risk teams checking identity signals
- Data operations teams reducing manual lookups
How the Reverse Phone Append API Works
The workflow is simple.
First, your application sends a 10-digit phone number to the lookup endpoint.
Next, the API searches for a matching record tied to that phone number.
If a match is found, the response may return name fields, address fields, deliverability status, validation date, and a trace ID.
Your system can then write the returned data into a CRM, lead routing platform, call center tool, fraud review workflow, or internal customer database.
Best Input Format for Matching
For stronger lookup results, submit clean phone numbers in the required format.
Recommended input format:
- Use a 10-digit U.S. phone number.
- Do not include spaces.
- Do not include dashes.
- Do not include parentheses.
- Normalize phone numbers before sending requests.
Clean input helps reduce failed requests and improves the chance of returning a useful match.
Quick Start
The TDG Reverse Phone API provides real-time identity recovery and lead validation by resolving available name and address data from a submitted phone number.
Use this endpoint when your system starts with a phone number and needs to return associated identity or household information.
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, please contact The Data Group. Our 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.
- 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 encryption is required for all API transmissions.
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 Lookup
Phone Lookup
Retrieve name and address information associated with a specific phone number. This phone number lookup API is designed for identity linkage, lead validation, and customer profile enrichment.
Use this endpoint when your system already has a phone number and needs to identify the matching person or household.
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://testapi.tdg1.io/v3/lookup/phone Sample Request
curl --location 'https://testapi.tdg1.io/v3/lookup/phone' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api_key>' \
--data '{
"Phone":"<555-555-5555>"
}'
Sample Response
{
"Name": {
"LName": "Smith",
"FName": "Tom",
"MName": ""
},
"Address": {
"House": "123",
"PreDir": "",
"Street": "Main",
"StrType": "St.",
"PostDir": "",
"AptType": null,
"City": "Anytown",
"State": "FL",
"Zip": "34786",
"Z4": "",
"CNTY": "",
"Deliverable": true,
"ValDate": "5/1/2025"
},
"trace": "c31c2d88-2d57-4dcf-ac12-f5d4e139a8871"
}
Response Fields Explained
| Response Field | Description |
| Name | The name object returns available name fields connected to the submitted phone number. |
| LName | The matched last name associated with the phone record. |
| FName | The matched first name associated with the phone record. |
| MName | The matched middle name or middle initial when available. |
| Address | The address object returns available mailing or household address fields connected to the phone number. |
| House | The street number for the matched address. |
| Street | The street name for the matched address. |
| StrType | The street type, such as Street, Avenue, Road, or Drive. |
| City, State, and Zip | The matched city, state, and ZIP code tied to the returned address. |
| Deliverable | A deliverability value that helps indicate whether the returned address is considered deliverable. |
| ValDate | The validation date associated with the returned address data. |
| trace | A unique trace ID for the API request. Use this for debugging, reporting, support requests, and internal logging. |
Identity Validation: ID Verify
ID Verify validates identity signals using multiple data points. This endpoint can help confirm whether names, addresses, emails, and phone numbers appear connected.
Use ID Verify when your workflow needs more than a phone lookup and must compare multiple identity fields together.
This can support lead validation, fraud review, CRM quality checks, and identity confidence scoring.
Body Params
- FName (string) | required if verified: Individual’s first name. (Required if you want to verify FName).
- LName (string) | required if verified: Last name, 20 characters max. (Required if you want to verify LName).
- Address1 (string) | required if verified: Address line 1, 64 characters max. (Required if you want to verify Address).
- Zip (string) | required if verified: 5 digit numeric USPS zip code. (Required if you want to verify Zip).
- Phone (string) | required if verified: 10 digit numeric phone number. (Required if you want to verify Phone).
- Email (string) | required if verified: Email address, 100 characters max. (Required if you want to verify Email).).
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: <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"
}
}
Reverse Phone API vs Phone Append API
These two APIs solve different problems.
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 leads.
- You need to validate identity from a phone number.
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.
Keeping these use cases separate helps users and search engines understand the purpose of each API page.
Reverse Phone API vs Batch Reverse Phone Append
The API is best when your system needs real-time lookup.
Use the API when:
- Records are processed one at a time.
- Your workflow starts from a form, call, CRM event, or live request.
- Speed matters.
- Your team wants automated lookup inside an application.
Use batch reverse phone append when:
- You need to enrich a large phone 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 live phone lookup workflows.
Common Integration Workflows
Caller Identification
Use the API to identify the available name and address tied to a phone number before routing or reviewing the contact.
Lead Validation
Check whether a submitted phone number is connected to a real identity before sending the lead to sales or support.
CRM Enrichment
Turn phone-only records into more complete customer profiles by adding available name and address data.
Fraud Review
Use phone, name, address, and email signals together to help review whether customer-submitted information appears consistent.
Call Center Workflows
Improve inbound and outbound call workflows by connecting phone records to identity and household details.
Data Quality Tips
Reverse phone append results depend on the quality and format of the submitted phone number.
To improve lookup performance:
- Submit a 10-digit phone number.
- Remove spaces, dashes, and parentheses before sending the request.
- Validate required fields before the API call.
- Use consistent phone formatting across your application.
- Store the trace ID for troubleshooting.
- Use ID Verify when you need to compare phone data against other identity fields.
Compliance and Responsible Use
Reverse phone append data should be used carefully and within your organization’s legal, privacy, and compliance requirements.
Before using returned data, confirm:
- Whether your intended use is allowed.
- Whether consent is required for outreach.
- Whether the data will be used only for permitted marketing, validation, or operational purposes.
- How returned identity data will be stored.
- Who can access returned data.
- How suppression lists and opt-outs will be honored.
- Whether additional legal review is needed for your workflow.
The Data Group is not a Consumer Reporting Agency. Reverse phone append and identity verification tools are for marketing, lead validation, and operational use cases only. Data may not be used for FCRA-regulated purposes, including eligibility decisions for credit, insurance, employment, housing, or similar uses.
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) |
| 401 | The user is invalid (verify your credentials) |
| 429 | You have reached the maximum number of transactions allowed |
| 440 | Too many results. Please refine your search criteria |
| 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.
If you need help with endpoint setup, request formatting, field mapping, response handling, SDK usage, Postman testing, ID verification, or production rollout, contact our support team.
Related API and Data Services
- API Hub: Use this page to compare The Data Group API services and choose the right endpoint.
- Reverse Phone Append Services: Use this page for the full reverse phone append service overview.
- Phone Append API: Use this when your workflow starts with name and address data and needs a phone number.
- Phone Append Services: Use this for batch phone append and phone data enrichment.
- ID Verification API: Use this when you need to validate identity signals across multiple fields.
- TCPA API: Use this for TCPA-related phone verification workflows.
- Pricing: Review pricing options for data append and API services.
Frequently Asked Questions
What is a Reverse Phone Append API?
A Reverse Phone Append API is a real-time data service that starts with a phone number and returns available name and address information when a reliable match is found.
Is reverse phone append the same as phone append?
No. Reverse phone append starts with a phone number and returns identity data. Phone append starts with a known person or address and returns a phone number.
What input is required?
The phone lookup endpoint requires a 10-digit numeric phone number without spaces, dashes, or parentheses.
What data can the API return?
The API may return name fields, address fields, deliverability status, validation date, and a trace ID when a match is available.
Can this API be used for caller identification?
Yes. Caller identification is one of the main use cases for reverse phone lookup.
Can this API be used for CRM enrichment?
Yes. It can help enrich phone-only records with available name and address data.
Does every request return a match?
No. A result is returned only when a reliable matching record 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.
Can reverse phone append data be used for credit, insurance, or employment eligibility?
No. The Data Group is not a Consumer Reporting Agency, and the data may not be used for FCRA-regulated eligibility decisions.
Does this page replace the main API hub?
No. This page is only for Reverse Phone Append API documentation. The main API overview should remain on the API hub page.
Ready To Use the Reverse Phone Append API?
