Caller Identification API

curl --request GET \
  --url "https://api.trestleiq.com/3.1/caller_id?phone=2069735100" \
  --header "x-api-key: YOUR_API_KEY"

{
  "id": "Phone.3dbb6fef-a2df-4b08-cfe3-bc7128b6f5b4",
  "phone_number": "2069735100",
  "is_valid": true,
  "country_calling_code": "1",
  "line_type": "NonFixedVOIP",
  "carrier": "Trestle Telco",
  "is_prepaid": false,
  "is_commercial": true,
  "belongs_to": {
    "id": "Person.fffdcf06-0929-4b5a-9921-ee49b101ca84",
    "name": "Waidong L Syrws",
    "firstname": "Waidong",
    "middlename": "L",
    "lastname": "Syrws",
    "alternate_names": [
      "Sryws W L"
    ],
    "age_range": "25-29",
    "gender": null,
    "type": "Person",
    "industry": null,
    "link_to_phone_start_date": "2019-03-23"
  },
  "current_address": {
      "id": "Location.d1a40ed5-a70a-46f8-80a9-bb4ac27e3a01",
      "location_type": "Address",
      "street_line_1": "100 Syrws St",
      "street_line_2": "Ste 1",
      "city": "Lynden",
      "postal_code": "98264",
      "zip4": "98264-9999",
      "state_code": "WA",
      "country_code": "US",
      "lat_long": {
        "latitude": 0,
        "longitude": 0,
        "accuracy": "Neighborhood"
      },
      "is_active": true,
      "delivery_point": "SingleUnit",
      "link_to_person_start_date": "2011-10-05"
  },
  "error": {
    "name": "InternalError",
    "message": "Could not retrieve entire response"
  },
  "warnings": [
    "Missing Input"
  ]
}

curl --request GET \
  --url "https://api.trestleiq.com/3.1/caller_id?phone=2069735100" \
  --header "x-api-key: YOUR_API_KEY"

{
  "id": "Phone.3dbb6fef-a2df-4b08-cfe3-bc7128b6f5b4",
  "phone_number": "2069735100",
  "is_valid": true,
  "country_calling_code": "1",
  "line_type": "NonFixedVOIP",
  "carrier": "Trestle Telco",
  "is_prepaid": false,
  "is_commercial": true,
  "belongs_to": {
    "id": "Person.fffdcf06-0929-4b5a-9921-ee49b101ca84",
    "name": "Waidong L Syrws",
    "firstname": "Waidong",
    "middlename": "L",
    "lastname": "Syrws",
    "alternate_names": [
      "Sryws W L"
    ],
    "age_range": "25-29",
    "gender": null,
    "type": "Person",
    "industry": null,
    "link_to_phone_start_date": "2019-03-23"
  },
  "current_address": {
      "id": "Location.d1a40ed5-a70a-46f8-80a9-bb4ac27e3a01",
      "location_type": "Address",
      "street_line_1": "100 Syrws St",
      "street_line_2": "Ste 1",
      "city": "Lynden",
      "postal_code": "98264",
      "zip4": "98264-9999",
      "state_code": "WA",
      "country_code": "US",
      "lat_long": {
        "latitude": 0,
        "longitude": 0,
        "accuracy": "Neighborhood"
      },
      "is_active": true,
      "delivery_point": "SingleUnit",
      "link_to_person_start_date": "2011-10-05"
  },
  "error": {
    "name": "InternalError",
    "message": "Could not retrieve entire response"
  },
  "warnings": [
    "Missing Input"
  ]
}

curl --request GET \
  --url "https://api.trestleiq.com/3.1/caller_id?phone=2069735100" \
  --header "x-api-key: YOUR_API_KEY"

{
  "id": "Phone.3dbb6fef-a2df-4b08-cfe3-bc7128b6f5b4",
  "phone_number": "2069735100",
  "is_valid": true,
  "country_calling_code": "1",
  "line_type": "NonFixedVOIP",
  "carrier": "Trestle Telco",
  "is_prepaid": false,
  "is_commercial": true,
  "belongs_to": {
    "id": "Person.fffdcf06-0929-4b5a-9921-ee49b101ca84",
    "name": "Waidong L Syrws",
    "firstname": "Waidong",
    "middlename": "L",
    "lastname": "Syrws",
    "alternate_names": [
      "Sryws W L"
    ],
    "age_range": "25-29",
    "gender": null,
    "type": "Person",
    "industry": null,
    "link_to_phone_start_date": "2019-03-23"
  },
  "current_address": {
      "id": "Location.d1a40ed5-a70a-46f8-80a9-bb4ac27e3a01",
      "location_type": "Address",
      "street_line_1": "100 Syrws St",
      "street_line_2": "Ste 1",
      "city": "Lynden",
      "postal_code": "98264",
      "zip4": "98264-9999",
      "state_code": "WA",
      "country_code": "US",
      "lat_long": {
        "latitude": 0,
        "longitude": 0,
        "accuracy": "Neighborhood"
      },
      "is_active": true,
      "delivery_point": "SingleUnit",
      "link_to_person_start_date": "2011-10-05"
  },
  "error": {
    "name": "InternalError",
    "message": "Could not retrieve entire response"
  },
  "warnings": [
    "Missing Input"
  ]
}

curl --request GET \
  --url "https://api.trestleiq.com/3.1/caller_id?phone=2069735100" \
  --header "x-api-key: YOUR_API_KEY"

{
  "id": "Phone.3dbb6fef-a2df-4b08-cfe3-bc7128b6f5b4",
  "phone_number": "2069735100",
  "is_valid": true,
  "country_calling_code": "1",
  "line_type": "NonFixedVOIP",
  "carrier": "Trestle Telco",
  "is_prepaid": false,
  "is_commercial": true,
  "belongs_to": {
    "id": "Person.fffdcf06-0929-4b5a-9921-ee49b101ca84",
    "name": "Waidong L Syrws",
    "firstname": "Waidong",
    "middlename": "L",
    "lastname": "Syrws",
    "alternate_names": [
      "Sryws W L"
    ],
    "age_range": "25-29",
    "gender": null,
    "type": "Person",
    "industry": null,
    "link_to_phone_start_date": "2019-03-23"
  },
  "current_address": {
      "id": "Location.d1a40ed5-a70a-46f8-80a9-bb4ac27e3a01",
      "location_type": "Address",
      "street_line_1": "100 Syrws St",
      "street_line_2": "Ste 1",
      "city": "Lynden",
      "postal_code": "98264",
      "zip4": "98264-9999",
      "state_code": "WA",
      "country_code": "US",
      "lat_long": {
        "latitude": 0,
        "longitude": 0,
        "accuracy": "Neighborhood"
      },
      "is_active": true,
      "delivery_point": "SingleUnit",
      "link_to_person_start_date": "2011-10-05"
  },
  "error": {
    "name": "InternalError",
    "message": "Could not retrieve entire response"
  },
  "warnings": [
    "Missing Input"
  ]
}

Caller ID API 3.1

GET https://api.trestleiq.com/3.1/caller_id?phone=[insert_phone_number]

Query Parameters

phone

string

required

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. Example: phone.country_hint=US

phone.name_hint

string

Person or Business name associated with the phone number. If multiple names are associated with the phone in Trestle database, this name will be ranked higher. Example: phone.name_hint=Waidong Syrws

phone.postal_code_hint

string

The postal code of the subscriber address associated with the phone number. If multiple names or addresses are associated with the phone in Trestle database, this postal code hint will be used to rank name/address higher. Example: phone.postal_code_hint=98264

Headers

x-api-key

string

required

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

Response

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.

country_calling_code

string or null <E.164>

The country code of the phone number.

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

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.

is_commercial

boolean or null

True if the phone number is registered to a business.

belongs_to

object[]

The primary owner of the phone number.

Show belongs_to object

string or null <Person.<uuid>>

The persistent ID of the address.

name

string or null

The full name of the person.

firstname

string or null (FirstName)

The first name of the person.

middlename

string or null (MiddleName)

The middle name (or middle initial) of the person.

lastname

string or null (LastName)

The last name of the person.

alternate_names

string[]

Alternate names of the person associated with the phone.

age_range

string or null (AgeRange)

The age of the person in a 5-year range.

gender

string or null (Gender)

The gender of the person.

type

string

The type of the legal entity.

Person: The legal entity is a person.
Business: The legal entity is a company.

Enum: Business, Person

link_to_phone_start_date

string or null

The date when the person was first linked to the phone number.

industry

string[] or null

The industry classification of the business associated to the phone.

current_addresses

object[]

Current location associated with Person or Business in belongs_to array.

Show address object

string or null <Location.<uuid>>

The persistent ID of the address.

location_type

string or null

The type of the location. Enum: Country State City PostalCode ZipPlus4 NeighborhoodAddress

street_line_1

string or null

The first line of the street part in the structured address.

street_line_2

string or null

The second line of the street part in the structured address.

city

string or null

The city associated with the address.

postal_code

string or null

The postal code of the structured address.

zip4

string or null ^\d+-\d{4}$

The ZIP+4 code of the structured address (USA).

state_code

string or null

The state code of the structured address.

country_code

string or null

The ISO-3166 alpha-2 country code of the structured address. See: ISO-3166.

lat_long

object

The coordinates of the geographical location of the address.

Show lat_long object

latitude

number or null <double>

The latitude coordinate of the location.

longitude

number or null <double>

The longitude coordinate of the location.

accuracy

string or null

The accuracy of the geographical location. Enum: Country State City
PostalCode Street RoofTop

is_active

boolean or null

True if the address is currently receiving mail.

delivery_point

string or null (DeliveryPoint)

The type of the delivery point of the address. Enum: SingleUnit, MultiUnit, POBox, PartialAddress

link_to_person_start_date

string or null (LinkToPersonStartDate)

The date when the address was first linked to the person.

error

object(PartialError)

Error details in case of an error.

Show error object

name

string

Incomplete response due to external timeouts. value: “InternalError”

message

string

The error message. value: “Could not retrieve entire response”

warnings

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.

Invalid API Key: The key is incorrect or deactivated. Check for: Trailing spaces, syntax errors, or incorrect character counts.
API Key Missing: The request header did not include an API key.
API Key Disabled (Portal Issue): 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): 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: 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: You have surpassed the queries-per-second (QPS) threshold for your tier.
Quota Exceeded (Portal Issue): 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.

Reverse Phone API Smart CNAM API

​Caller ID API 3.1

​Query Parameters

​Headers

​Response

​Error Responses

​400 Bad Request

​403 Forbidden

​429 Too Many Requests

​500 Internal Server Error

Caller ID API 3.1

Query Parameters

Headers

Response

Error Responses

400 Bad Request

403 Forbidden

429 Too Many Requests

500 Internal Server Error