Skip to main content
curl --request GET \
  --url "https://api.trestleiq.com/1.1/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com" \
  --header "x-api-key: YOUR_API_KEY"

{
  "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": "F",
  "address.is_valid": true,
  "address.name_match": true,
  "add_ons": {
    "litigator_checks": {
      "phone.is_litigator_risk": false
    },
    "email_checks": {
      "email.is_deliverable": false,
      "email.age_score": 70
    }
  },
  "error": {
    "name": "InternalError",
    "message": "Could not retrieve entire response"
  },
  "warnings": [
    "Missing Input"
  ]
}

curl --request GET \
  --url "https://api.trestleiq.com/1.1/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com" \
  --header "x-api-key: YOUR_API_KEY"

{
  "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": "F",
  "address.is_valid": true,
  "address.name_match": true,
  "add_ons": {
    "litigator_checks": {
      "phone.is_litigator_risk": false
    },
    "email_checks": {
      "email.is_deliverable": false,
      "email.age_score": 70
    }
  },
  "error": {
    "name": "InternalError",
    "message": "Could not retrieve entire response"
  },
  "warnings": [
    "Missing Input"
  ]
}

​
Real Contact 1.1

GET 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]

​
Query Parameters

​
name
string
required
The name of the person to search. Example: name=John Doe
​
business.name
string
The business name to search. Example: business.name=The Golden Company
​
phone
string
required
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=john.doe@example.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. Example: address.street_line_1=100 Syrws St
​
address.city
string
The name of the city in the structured address. Example: address.city=Lynden
​
address.state_code
string
The state code of the structured address. Example: address.state_code=WA
​
address.postal_code
string
The postal code of the structured address. Example: address.postal_code=98229
​
address.country_code
string <ISO-3166-2>
The ISO-3166 alpha-2 country code of the address. Example: address.country_code=US
​
add_ons
string
Request parameter to enable specific add-ons available for this endpoint. Add-ons incur additional charges. Please see here for more details.
  • email_checks_deliverability: to enable email deliverability checks in the response
  • email_checks_age: to enable email age score in the response
  • litigator_checks: to enable litigator checks in the response
Example: add_ons=litigator_checks,email_checks_deliverability

​
Headers

​
x-api-key
string
required
Your API key for authentication. Example: {{ apiKey }}

​
Response

​
phone.is_valid
boolean or null
True if the phone number is valid.
​
phone.activity_score
integer or null
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. Possible values:
  • Landline - Traditional wired phone line
  • Mobile - Wireless phone line
  • FixedVOIP - VOIP number connected to a physical address
  • NonFixedVOIP - VOIP number unconnected to a fixed physical address
  • Premium - Caller pays a premium for the call
  • TollFree - Callee pays for call
  • Voicemail - Voicemail-only service
  • Other - Line type is unclear
Enum: Landline Mobile FixedVOIP NonFixedVOIP Premium TollFree Voicemail Other
​
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 or null
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. Read up on contact grades in our Knowledge Base article.
​
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 name provided on the lead form matches to the input email address according to our database.
​
email.contact_grade
string or null
An A-F grade determining the quality of the lead and whether it is contactable via the email provided. Read up on contact grades in our Knowledge Base article.
​
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 name provided on the lead form matches to the input address according to our database.
​
add_ons
object or null
​
error
object(PartialError)
Error details in case of an error.
​
warnings
string[]
Warnings returned as part of the response, if applicable.Enum: Missing Input Missing Unit/Apt/Suite Number Invalid Address Invalid House/Building Number Invalid Unit/Apt/Suite Number Invalid Phone Lead is a Litigator. Must not be contacted. TimeoutError: Timeout getting response for litigator check. Partial response returned. Invalid Email Free Email Service Provider Tumbled Email Disposible Email Privacy Email Email is a spam trap Potential Junk Email Role Based Email Undeliverable Email Domain is a catch all and does not support validation Could not validate email TimeoutError: Timeout getting a response from the email server for email deliverability check

​
Error Responses

​
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:

  • An unexpected error occurred on the server.