Trestle Logo
Powered by Redocly

Phone Validation API

Phone Validation API validates phone numbers and provides phone metadata, including carrier, line type, prepaid status, and a phone activity score to identify disconnected numbers.

Phone Validation API 3.0

URL Structure: https://api.trestleiq.com/3.0/phone_intel?phone=[insert_phone]

Request
query Parameters
phone
required
string

The phone number in E.164 or local format. The default country calling code is +1 (USA).

Example: phone=2069735100
phone.country_hint
string <ISO-3166-2>

The ISO-3166 alpha-2 country code of the phone number. See: ISO-3166

Example: phone.country_hint=US
header Parameters
x-api-key
required
string

The API Key.

Example: {{apiKey}}
Responses
200

Successful phone validation response.

Response Schema: application/json
id
string or null <Phone.<uuid>>

The persistent ID of the phone number.

phone_number
string or null (PhoneNumber)

The phone number in E.164 or local format. The default country calling code is +1 (USA).

is_valid
boolean or null

True if the phone number is valid.

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.
country_calling_code
string or null <E.164>

The country code of the phone number.

country_code
string or null <ISO-3166-2>

The ISO-3166 alpha-2 country code of the phone number. See: ISO-3166

country_name
string or null

The country name of the location associated with the phone number.

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"
carrier
string or null

The company that provides voice and/or data services for the phone number. Carriers are returned at the MVNO level.

is_prepaid
boolean or null

True if the phone is associated with a prepaid account.

object (PartialError)
warnings
Array of strings

Warnings returned as part of the response, if applicable. The possible values include - Invalid Input, International number. Not authorized, or Missing Input.

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/3.0/phone_intel
Request samples 
curl --location --request GET 'https://api.trestleiq.com/3.0/phone_intel?phone=2069735100&phone.country_hint=US'   
  --header 'x-api-key: [insert_api_key]'  
  --header 'Accept: application/json'
Response samples
application/json
{
  • "id": "Phone.3dbb6fef-a2df-4b08-cfe3-bc7128b6f5b4",
  • "phone_number": "2069735100",
  • "is_valid": true,
  • "activity_score": 57,
  • "country_calling_code": "1",
  • "country_code": "US",
  • "country_name": "United States",
  • "line_type": "NonFixedVOIP",
  • "carrier": "Level 3 Communications, LLC",
  • "is_prepaid": false,
  • "error": {
    },
  • "warnings": "Missing Input"
}
➔ Next to Reverse Address API