The Data Group

Phone Lookup

The Phone Lookup product accepts Phone as input and performs a reverse phone search against The Data Group’s phones identity data sources and returns the matched record along with verification scores.

Input

The following table is a list of input fields accepted by the API.
Input Field Required? Description
Phone Required 10 digit numeric phone number (without spaces, dashes, or parentheses)

Output

The Phone Lookup returns both Identity and Phone attributes in the output. The following table is a list of main Identity attributes.
Name Attributes
The following table is a list of Name attributes included in the API response.
Output Field Description Return Values
FName Appended First Name 20 characters
MName Appended Middle Name 1 Character
LName Appended Last name 20 Characters
BusName Appended Business Name 100 Characters
Address Attributes
The following table is a list of Address attributes included in the API response.
Output Field Description Return Values
House Appended Primary House Number 10 Characters
PreDir Appended Street Pre Direction: N, S, E, W, NE, SW, etc 2 Characters
Street Appended Street name 28 Characters
StrType Appended Street suffix: ST, AVE, BLVD, etc 4 Characters
PostDir Appended Street Post Direction: N, S, E, W, NE, SW, etc 2 Characters
AptType Appended Secondary Unit designator: Apt, Suite, etc 4 Characters
AptNbr Appended Secondary unit number: Apt #, Suite #, etc 8 Characters
City Appended USPS City Name 28 Characters
State Appended USPS state abbreviation 2 Characters
Zip Appended numeric USPS zip code 6 Characters
Z4 Appended numeric USPS zip+4 4 Characters
DPC Appended Delivery point code with check digit 3 Characters
CRTE Appended Carrier Route 4 Characters
CNTY Appended FIPS county code 3 Characters
Z4Type Appended USPS Zip+4 type
  • F – firm or company address
  • G – General delivery address
  • H – High-rise or business complex
  • P – PO Box address
  • R – Rural route address
  • S – Street or residential address
  • Blank - Unknown
F, G, H, P, R, S
DPV Appended Delivery Point Validation
  • Y – Address DPV confirmed for both primary and (if present) secondary numbers
  • D – Address DPV confirmed for primary number only, secondary number information was missing
  • S – Address DPV confirmed for the primary number only, and secondary number information was present but unconfirmed
  • N – Both Primary and (if present) Secondary number information failed to DPV confirm Blank – Address not presented to hash table
Y, D, S, N
Deliverable Appended Deliverable flag Y, N, or Blank
ValDate Appended Last address validation date YYYYMMDD
Phone Attributes
The following table is a list of Phone attributes included in the API response.
Output Field Description Return Values
Phone Telephone Number, Echo of input phone 10 characters
PhoneType Appended Probable Phone Type
  • L – Land Line
  • V - VoIP
  • W – Wireless
  • O - Other
L, V, W, O
DID Direct Inward Dial Number Y or blank
RecType Appended Record Type
  • R - Residential
  • B – Business
  • P - Payphone
  • U - Unknow
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
Source Output record source:
  • TNR- US Record
  • New Connects- US Record
  • TNR New – US Record
  • CAN- Canadian Record
20 characters
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 The Data Group’s ongoing commitment to data governance and security, the API requires TLS 1.2 encryption protocol for data communications.
POST Phone Lookup Successful Request (JSON)

Request Headers

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

Request Body (Parameters)

Output Field Description
Phone 10 digit numeric phone number (without spaces, dashes, or parentheses)
Example Request with JSON Response
Below is an example of a successful Reverse Phone request and the JSON response.
Request Headers:
x-api-key: {your api key} URL: https://api.tdg1.io/v2/lookup/phone
Request Body:
				
					{
    "Phone": "555-555-5555"
}
				
			
Response:
				
					{
    "Name": {
        "FName": "TOM",
        "LName": "SMITH",
        "MName": "A",
        "BusName": ""
    },
    "Address": {
        "House": "123",
        "PreDir": "",
        "Street": "MAIN",
        "StrType": "ST",
        "PostDir": "",
        "AptType": "",
        "AptNbr": "",
        "City": "ORLANDO",
        "State": "FL",
        "Zip": "32803",
        "Z4": "9111",
        "DPC": "564",
        "CRTE": "R019",
        "CNTY": "SEM",
        "Z4Type": "S",
        "DPV": "Y",
        "Vacant": "N",
        "MSA": "5960",
        "CBSA": "36740"
    },
    "Phone": {
        "Phone": "5555555555",
        "PhoneType": "W",
        "DID": "",
        "RecType": "R",
        "IDate": "20230413",
        "ODate": "20230901",
        "TelcoName": "T-MOBILE USA, INC.",
        "PHV": "2",
        "DACode": "",
        "Source": "TNR"
    }
}

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