Skip to main content

Phone Validation API 3.0

Query Parameters

string
required
The phone number in E.164 or local format. Example: phone=2069735100
string (ISO-3166-2)
The ISO-3166 alpha-2 country code of the phone number. Example: phone.country_hint=US
string
Request parameter to enable specific add-ons available for this endpoint. Add-ons incur additional charges. Please see here for more details. Example: litigator_checks

Headers

string
required
Your API key for authentication. Example: {{ apiKey }}

Response

string or null <Phone.<uuid>>
The persistent ID of the phone number.
string or null (PhoneNumber)
The phone number in E.164 or local format. The default country calling code is +1 (USA).
boolean or null
True if the phone number is valid.
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.
string or null <E.164>
The country code of the phone number.
string or null (ISO-3166-2)
The ISO-3166 alpha-2 country code of the phone number. See: ISO-3166.
string or null
The country name of the location associated with the phone number.
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
string or null
The company that provides voice and/or data services for the phone number.
boolean or null
True if the phone is associated with a prepaid account.
object or null
object(PartialError)
Error details in case of an error.
string[]
Warnings returned as part of the response, if applicable.

Enum: Invalid Input International number. Not authorized Missing Input

Error Responses

400 Bad Request

The server cannot process the request due to client-side errors.Check for: Syntax errors in the request script, malformed JSON, or invalid parameters.

403 Forbidden

The request is understood, but the server is refusing to fulfill it. Error responses include an errorCode field identifying the cause:
  • Invalid API Key (INVALID_API_KEY): The key is incorrect, deactivated, or missing from the request. Check for: Trailing spaces, syntax errors, incorrect character counts, or a missing x-api-key header.
  • API Key Disabled (Portal Issue) (FORBIDDEN): The key is inactive. Check for: Insufficient funds in your self-serve wallet or if a Trestle Admin manually deactivated your API key.
  • API Key does not have Product Access (Portal Issue) (FORBIDDEN): The API key is active, but it is not enabled for this product or API version. Check for: Incorrect endpoint, incorrect API version, or missing product access on the key.
  • API Key Expired (FORBIDDEN): The key has reached its end-of-life (primarily affects Trial users).

429 Too Many Requests

You have sent too many requests in a given amount of time.
  • Rate Limit Exceeded (RATE_LIMIT_EXCEEDED): You have surpassed the queries-per-second (QPS) threshold for your tier.
  • Quota Exceeded (Portal Issue) (QUOTA_EXCEEDED): You have reached the total volume allowed for your current billing cycle. Upgrade your plan in the portal to resume service.

500 Internal Server Error

An unexpected error occurred on the server side. Please contact support if this persists.See Error handling for all error response bodies and codes.