The Data Group

Phone ID Append

Append Phone Numbers matches names and addresses to your input.

Input

The following table displays variables that can be sent to the Phone ID Append endpoint to query for phone numbers matching names and addresses.

Input Field Required? Description
FName Required First name, 15 characters max
LName Required Last name, 15 characters max
Address1 Required Address line 1 (example: 123 Main Street), 60 characters max
Zip Required 5 digit numeric USPS zip code. * Either City/State or Zip is required
Maxscore Optional Filters by Match Score, 3 characters max. See Appendix C. "maxscore=299 will include all individual and household level matches"

At a minimum, the following combination is required for processing:

  • FName + LName + Address1 + Zip

Output

The following table displays the data returned from the API.
Phone Attributes
The Phone Types returned are sourced from the telephone carrier network and are authoritative and accurate, even in situations where a phone has been recently ported from landline to wireless.

The following table displays the list of Phone attributes.

Output Field Description Return Values
Phone Appended Telephone Number 10 characters
DID Direct Inward Dial Number Y or blank
RecType Appended Record Type R – Residential B – Business P – Payphone U - Unknown R, B, P, U
IDate Date record was first received YYYYMMDD
ODate Date record was last received as connected YYYYMMDD
TelcoName Name of original telephone company provider 100 Characters
PHV Telephone confidence score 1 is highest confidence, 5 is lowest. 4’s are considered possible disconnects, 5’s are likely disconnects. PHV 1-3 are considered high confidence records. 1 - 5
DACode Directory Assistance Flag, 1 character max. Y – Record as it appears in Directory Assistance D – Record was removed / delisted from Directory Assistance Blank – Private record (not in Directory Assistance) Y, D, Blank
Restful JSON API Example

Note: The JSON API uses DNS load balancing to route traffic to multiple IP addresses hosted at multiple data centers. Clients must use DNS and adhere to DNS TTL settings to avoid unexpected loss of service. As part of TheDataGroup’s ongoing commitment to data governance and security, the API requires TLS 1.2 encryption protocol for data communications.

POST Phone Append Successful Request (JSON)

Request Headers

Header Attribute Header Value
x-api-key {your api key}

Request Body (Parameters)

Output Field Description
FName First Name
LName Last Name
Address1 Address line 1, 64 characters max.
Zip 5 digit numeric USPS zip code.
Example Request with JSON Response
Below is an example of a successful Phone Append request and the JSON response.
Request Headers:

x-api-key: {your api key}

URL:

https://api.tdg1.io/v2/append/phone

Request Body:
				
					{
    "FName": "Tom",
    "LName": "Smith",
    "Address1": "123 Main St",
    "Zip": "12345"
}
				
			
Response:
				
					{
    "phone": "4127061884",
    "phoneType": "W",
    "DID": "",
    "recType": "R",
    "iDate": "20230413",
    "oDate": "20230901",
    "telcoName": "T-MOBILE USA, INC.",
    "PHV": "2",
    "daCode": ""
}

				
			
API Response Codes

The following is a table of potential output response codes and messages to indicate if the search was successful or returned an error.

Request Body (Parameters)

Output Field 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