Trestle Logo
Powered by Redocly

Real Contact API

Real Contact API verifies and grades phone numbers, emails, and addresses and delivers essential insights, including a phone activity score, line types, name matches for phone, email, and address, and phone and email contact grades.

Real Contact 1.1

URL Structure: https://api.trestleiq.com/1.1/real_contact?api_key=[insert_key]&name=[insert_name]&phone=[insert_phone]&email=[insert_email]&ip_address=[insert_ip_address]&address.street_line_1=[insert_street_line_1]&address.city=[insert_city]&address.state_code=[insert_state_code]&address.postal_code=[insert_postal_code]&address.country_code=[insert_country_code]

Request
query Parameters
name
required
string

The name of the person to search.

Example: name=Jon Snow
business.name
string

The business name to search.

Example: business.name=The Golden Company
phone
required
string

The phone provided by the lead on the web form.

Example: phone=4259853735
email
string

The email provided by the lead on the web form.

Example: email=kushal.shah@gmail.com
ip_address
string

The IP address from which the lead signed up on the web form.

Example: ip_address=192.0.0.1
address.street_line_1
string

The first line of the street part in the structured address. (Cannot be longer than 1000 characters.)

Example: address.street_line_1=100 Syrws St
address.city
string

The name of the city in the structured address. (Cannot be longer than 500 characters.)

Example: address.city=Lynden
address.state_code
string

The state code of the structured address. (Cannot be longer than 100 characters.)

Example: address.state_code=WA
address.postal_code
string

The postal code of the structured address. (Cannot be longer than 100 characters.)

Example: address.postal_code=98264
address.country_code
string <ISO-3166-2>

The ISO-3166 alpha-2 country code of the address. See: ISO-3166. (Cannot be longer than 100 characters.)

Example: address.country_code=US
header Parameters
x-api-key
required
string

The API Key.

Example: {{apiKey}}
Responses
200

Successful real contact response.

Response Schema: application/json
phone.is_valid
boolean or null

True if the phone number is valid.

phone.activity_score
integer

Trestle's activity scores range from 0 to 100. A score of 100 means consistent activity in the last 12 months, and a score of 0 means a disconnected number or no activity has been seen in the past year.

An activity score of 70 or above means there is a high confidence that the phone is connected, assigned to a subscriber, and someone has been taking calls consistently. An activity score of 30 or below means there is a high confidence that the phone is either disconnected or no one will answer the call when the number is dialed in. An activity score of 50 means Trestle doesn't have enough signals to predict whether the phone is connected or disconnected/inactive.

If you want to filter leads based on the activity score, the following rules can be recommended:

  • Prioritize dialing good numbers with consistent activity: Scores 70 or above.
  • Weed out leads with disconnected/inactive numbers: Scores of 30 or below.
phone.line_type
string or null

The line type of the phone number.

  • Landline - Traditional wired phone line.
  • Mobile - Wireless phone line.
  • FixedVOIP - VOIP number connected to a physical address, such as Vonix or Comcast.
  • NonFixedVOIP - VOIP number unconnected to a fixed physical address, such as Google Voice or Skype.
  • Premium - Caller pays a premium for the call–e.g. 976 area code.
  • TollFree - Callee pays for call.
  • Voicemail - Voicemail-only service.
  • Other - Line type is unclear or does not match current categories.
Enum: "Landline" "Premium" "NonFixedVOIP" "Mobile" "FixedVOIP" "TollFree" "Other" "Voicemail"
phone.name_match
boolean or null

A match/no match indicator whether the name provided on the lead form matches to the input phone number according to our database. A match is a positive indicator that verifies the lead is real and is who he/she says they are.

phone.contact_grade
string

An A-F grade determining the quality of the lead and whether it is contactable. A Grade-F lead is a bad lead and should be deprioritized while a Grade-A lead is real and contactable and should be prioritized.

email.is_valid
boolean or null

True if the email is valid.

email.name_match
boolean or null

A match/no match indicator whether the email provided on the lead form matches to the input email according to our database. A match is a positive indicator that verifies the lead is real and is who he/she says they are.

email.contact_grade
string

An A-F grade determining the quality of the lead and whether it is contactable. A Grade-F lead is a bad lead and should be deprioritized while a Grade-A lead is real and contactable and should be prioritized.

address.is_valid
boolean or null

True if the address is valid.

address.name_match
boolean or null

A match/no match indicator whether the address provided on the lead form matches to the input address according to our database. A match is a positive indicator that verifies the lead is real and is who he/she says they are.

error
object
warnings
Array of strings

Warnings returned as part of the response, if applicable. The possible values include - Missing Input, International number. Not authorized., Disposable Email, Invalid Phone, Invalid Email, Invalid Address, or Free Email Service Provider.

400

Bad Request: Indicates that the server cannot process the request due to client-side errors.

403
  • Invalid API Key: Indicates that the API key is either incorrect or has been deactivated.
  • API Key Missing: Indicates that your request did not include an API key.
  • API Key Expired: Indicates that the API key has expired.
429

Too Many Requests: API Key has exceeded its rate limit.

500

Internal Server Error: Indicates that the server encountered an unexpected error.

get/1.1/real_contact
Request samples 
curl --location --request GET 'https://api.trestleiq.com/1.1/real_contact?name=Waidong+L+Syrws&phone=2069735100&address.city=Lynden&address.country_code=US&address.postal_code=98264&address.state_code=WA&address.street_line_1=100+Syrws+St&email=wsyrws@gmail.com&ip_address=192.0.0.1'   
 --header 'x-api-key: [insert_api_key]'  
  --header 'Accept: application/json'
Response samples
application/json
{
  • "phone.is_valid": true,
  • "phone.activity_score": 57,
  • "phone.line_type": "Mobile",
  • "phone.name_match": true,
  • "phone.contact_grade": "A",
  • "email.is_valid": true,
  • "email.name_match": true,
  • "email.contact_grade": "B",
  • "address.is_valid": true,
  • "address.name_match": true,
  • "error": { },
  • "warnings": "Missing Input"
}