> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trestleiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Caller Identification API

> Caller Identification API identifies the phone owner’s name and demographic details, along with that owner’s address.

<Panel>
  <RequestExample>
    ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl --request GET \
      --url "https://api.trestleiq.com/3.1/caller_id?phone=2069735100" \
      --header "x-api-key: YOUR_API_KEY"
    ```

    ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch(
      "https://api.trestleiq.com/3.1/caller_id?phone=2069735100",
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
        },
      }
    );
    const data = await response.json();
    ```

    ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import axios from "axios";

    const { data } = await axios.get(
      "https://api.trestleiq.com/3.1/caller_id?phone=2069735100",
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
        },
      }
    );
    console.log(data);
    ```

    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import requests

    headers = {"x-api-key": "YOUR_API_KEY"}

    response = requests.get(
        "https://api.trestleiq.com/3.1/caller_id",
        params={"phone": "2069735100"},
        headers=headers,
        timeout=30,
    )
    data = response.json()
    print(data)
    ```

    ```csharp C# theme={"theme":{"light":"github-light","dark":"github-dark"}}
    using var client = new HttpClient();
    client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

    var response = await client.GetAsync("https://api.trestleiq.com/3.1/caller_id?phone=2069735100");
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
    ```

    ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
    package main

    import (
    	"fmt"
    	"io"
    	"net/http"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.trestleiq.com/3.1/caller_id?phone=2069735100", nil)
    	req.Header.Set("x-api-key", "YOUR_API_KEY")

    	resp, err := http.DefaultClient.Do(req)
    	if err != nil {
    		panic(err)
    	}
    	defer resp.Body.Close()

    	body, _ := io.ReadAll(resp.Body)
    	fmt.Println(string(body))
    }
    ```

    ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
    <?php
    $curl = curl_init("https://api.trestleiq.com/3.1/caller_id?phone=2069735100");
    curl_setopt($curl, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($curl);
    curl_close($curl);

    echo $response;
    ```

    ```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import java.net.URI;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;

    public class CallerIdExample {
      public static void main(String[] args) throws Exception {
        HttpRequest request =
            HttpRequest.newBuilder()
                .uri(URI.create("https://api.trestleiq.com/3.1/caller_id?phone=2069735100"))
                .header("x-api-key", "YOUR_API_KEY")
                .GET()
                .build();

        HttpResponse<String> response =
            HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
      }
    }
    ```
  </RequestExample>

  <ResponseExample>
    ```json Response Example theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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"
      },
      "add_ons": {
        "litigator_checks": {
            "phone.is_litigator_risk": false
        },
        "spam_checks": {
            "phone.is_spam": true
        }
      },
      "warnings": [
        "Missing Input"
      ]
    }
    ```
  </ResponseExample>
</Panel>

## Caller ID API 3.1

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET https://api.trestleiq.com/3.1/caller_id?phone=[insert_phone_number]
```

## Query Parameters

<ParamField query="phone" type="string" required>
  The phone number in E.164 or local format. The default country calling code is +1 (USA). **Example:** `phone=2069735100`
</ParamField>

<ParamField query="phone.country_hint" type="string (ISO-3166-2)">
  The ISO-3166 alpha-2 country code of the phone number. **Example:** `phone.country_hint=US`
</ParamField>

<ParamField query="phone.name_hint" type="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`
</ParamField>

<ParamField query="phone.postal_code_hint" type="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`
</ParamField>

<ParamField query="add_ons" type="string">
  Request parameter to enable specific add-ons available for this endpoint. Add-ons incur additional charges. Please see [here](https://trestleiq.com/pricing/) for more details.

  * litigator\_checks: to enable TCPA litigator detection checks in the response.
  * spam\_checks: to enable spam and scam detection checks in the response

  **Example:** `litigator_checks,spam_checks`
</ParamField>

## Headers

<ParamField query="x-api-key" body="header" type="string" required>
  Your API key for authentication. **Example:** `{{ apiKey }}`
</ParamField>

## Response

<ResponseField name="id" type="string or null <Phone.<uuid>>">
  The persistent ID of the phone number.
</ResponseField>

<ResponseField name="phone_number" type="string or null (PhoneNumber)">
  The phone number in E.164 or local format. The default country calling code is +1 (USA).
</ResponseField>

<ResponseField name="is_valid" type="boolean or null">
  True if the phone number is valid.
</ResponseField>

<ResponseField name="country_calling_code" type="string or null <E.164>">
  The country code of the phone number.
</ResponseField>

<ResponseField name="line_type" 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
</ResponseField>

<ResponseField name="carrier" type="string or null">
  The company that provides voice and/or data services for the phone number. Carriers are returned at the MVNO level.
</ResponseField>

<ResponseField name="is_prepaid" type="boolean or null">
  True if the phone is associated with a prepaid account.
</ResponseField>

<ResponseField name="is_commercial" type="boolean or null">
  True if the phone number is registered to a business.
</ResponseField>

<ResponseField name="belongs_to" type="object[]">
  The primary owner of the phone number.

  <Expandable title="belongs_to object">
    <ResponseField name="id" type="string or null <Person.<uuid>>">
      The persistent ID of the address.
    </ResponseField>

    <ResponseField name="name" type="string or null">
      The full name of the person.
    </ResponseField>

    <ResponseField name="firstname" type="string or null (FirstName)">
      The first name of the person.
    </ResponseField>

    <ResponseField name="middlename" type="string or null (MiddleName)">
      The middle name (or middle initial) of the person.
    </ResponseField>

    <ResponseField name="lastname" type="string or null (LastName)">
      The last name of the person.
    </ResponseField>

    <ResponseField name="alternate_names" type="string[]">
      Alternate names of the person associated with the phone.
    </ResponseField>

    <ResponseField name="age_range" type="string or null (AgeRange)">
      The age of the person in a 5-year range.
    </ResponseField>

    <ResponseField name="gender" type="string or null (Gender)">
      The gender of the person.
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the legal entity.

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

      \
      Enum: <Badge>Business</Badge>, <Badge>Person</Badge>
    </ResponseField>

    <ResponseField name="link_to_phone_start_date" type="string or null">
      The date when the person was first linked to the phone number.
    </ResponseField>

    <ResponseField name="industry" type="string[] or null">
      The industry classification of the business associated to the phone.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current_addresses" type="object[]">
  Current location associated with Person or Business in belongs\_to array.

  <Expandable title="address object">
    <ResponseField name="id" type="string or null <Location.<uuid>>">
      The persistent ID of the address.
    </ResponseField>

    <ResponseField name="location_type" type="string or null">
      The type of the location. Enum: <Badge>Country</Badge> <Badge>State</Badge> <Badge>City</Badge> <Badge>PostalCode</Badge> <Badge>ZipPlus4</Badge> <Badge>Neighborhood</Badge><Badge>Address</Badge>
    </ResponseField>

    <ResponseField name="street_line_1" type="string or null">
      The first line of the street part in the structured address.
    </ResponseField>

    <ResponseField name="street_line_2" type="string or null">
      The second line of the street part in the structured address.
    </ResponseField>

    <ResponseField name="city" type="string or null">
      The city associated with the address.
    </ResponseField>

    <ResponseField name="postal_code" type="string or null">
      The postal code of the structured address.
    </ResponseField>

    <ResponseField name="zip4" type="string or null ^\d+-\d{4}$">
      The ZIP+4 code of the structured address (USA).
    </ResponseField>

    <ResponseField name="state_code" type="string or null">
      The state code of the structured address.
    </ResponseField>

    <ResponseField name="country_code" type="string or null">
      The ISO-3166 alpha-2 country code of the structured address. See: [ISO-3166](https://www.nationsonline.org/oneworld/country_code_list.htm).
    </ResponseField>

    <ResponseField name="lat_long" type="object">
      The coordinates of the geographical location of the address.

      <Expandable title="lat_long object">
        <ResponseField name="latitude" type="number or null <double>">
          The latitude coordinate of the location.
        </ResponseField>

        <ResponseField name="longitude" type="number or null <double>">
          The longitude coordinate of the location.
        </ResponseField>

        <ResponseField name="accuracy" type="string or null">
          The accuracy of the geographical location. Enum: <Badge>Country</Badge> <Badge>State</Badge> <Badge>City</Badge>\
          <Badge>PostalCode</Badge> <Badge /> <Badge>Street</Badge> <Badge>RoofTop</Badge>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="is_active" type="boolean or null">
      True if the address is currently receiving mail.
    </ResponseField>

    <ResponseField name="delivery_point" type="string or null (DeliveryPoint)">
      The type of the delivery point of the address. Enum: <Badge>SingleUnit</Badge>, <Badge>MultiUnit</Badge>, <Badge>POBox</Badge>, <Badge>PartialAddress</Badge>
    </ResponseField>

    <ResponseField name="link_to_person_start_date" type="string or null (LinkToPersonStartDate)">
      The date when the address was first linked to the person.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="add_ons" type="object or null">
  <Expandable title="Add Ons Object">
    <ResponseField name="litigator_checks" type="object">
      <Expandable title="litigator_checks">
        <ResponseField name="phone.is_litigator_risk" type="boolean or null">
          True if the phone subscriber is a TCPA litigator.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="spam_checks" type="object">
      <Expandable title="spam_checks Object">
        <ResponseField name="phone.is_spam" type="boolean or null">
          True if the phone number is identified as a spam, scam, or fraudulent caller.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object(PartialError)">
  Error details in case of an error.

  <Expandable title="error object">
    <ResponseField name="name" type="string">
      Incomplete response due to external timeouts. **value:** "InternalError"
    </ResponseField>

    <ResponseField name="message" type="string">
      The error message. **value:** "Could not retrieve entire response"
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="string[]">
  Warnings returned as part of the response, if applicable.\
  \
  Enum: <Badge>Invalid Input</Badge> <Badge>International number. Not authorized</Badge> <Badge>Missing Input</Badge>
</ResponseField>

<Danger>
  ## 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](/guides/errors) for all error response bodies and codes.
</Danger>