> ## 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.

# Smart CNAM API

> Smart CNAM API validates phone numbers and identifies the name or business to which the phone number belongs.

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

    ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch(
      "https://api.trestleiq.com/3.1/cnam?phone=2069735100&phone.country_hint=US",
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
          Accept: "application/json",
        },
      }
    );
    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/cnam?phone=2069735100&phone.country_hint=US",
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
          Accept: "application/json",
        },
      }
    );
    console.log(data);
    ```

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

    headers = {
        "x-api-key": "YOUR_API_KEY",
        "Accept": "application/json",
    }

    response = requests.get(
        "https://api.trestleiq.com/3.1/cnam",
        params={"phone": "2069735100", "phone.country_hint": "US"},
        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");
    client.DefaultRequestHeaders.Add("Accept", "application/json");

    var response = await client.GetAsync("https://api.trestleiq.com/3.1/cnam?phone=2069735100&phone.country_hint=US");
    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/cnam?phone=2069735100&phone.country_hint=US", nil)
    	req.Header.Set("x-api-key", "YOUR_API_KEY")
    	req.Header.Set("Accept", "application/json")

    	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/cnam?phone=2069735100&phone.country_hint=US");
    curl_setopt($curl, CURLOPT_HTTPHEADER, [
        "x-api-key: YOUR_API_KEY",
        "Accept: application/json"
    ]);
    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 SmartCnamExample {
      public static void main(String[] args) throws Exception {
        HttpRequest request =
            HttpRequest.newBuilder()
                .uri(URI.create("https://api.trestleiq.com/3.1/cnam?phone=2069735100&phone.country_hint=US"))
                .header("x-api-key", "YOUR_API_KEY")
                .header("Accept", "application/json")
                .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",
      "is_valid": true,
      "belongs_to": {
        "id": "Person.fffdcf06-0929-4b5a-9921-ee49b101ca84",
        "name": "Waidong L Syrws",
        "firstname": "Waidong",
        "middlename": "L",
        "lastname": "Syrws"
      },
      "error": {
        "name": "InternalError",
        "message": "Could not retrieve entire response"
      },
       "add_ons": {
        "spam_checks": {
            "phone.is_spam": true
        }
      },
      "warnings": [
        "Missing Input"
      ]
    }
    ```
  </ResponseExample>
</Panel>

## Smart CNAM API 3.1

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

## Query Parameters

<ParamField query="phone" type="string" required>
  The phone number in E.164 or local format. **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. See: [ISO-3166](https://www.nationsonline.org/oneworld/country_code_list.htm). **Example:** `phone.country_hint=US`
</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.

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

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

## Headers

<ParamField header="x-api-key" 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="is_valid" type="boolean or null">
  True if the phone number is valid.
</ResponseField>

<ResponseField
  name="belongs_to"
  type="	
(PhoneOwnerPersonSmartCNAM (object or null))"
>
  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>
  </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="add_ons" type="object or null">
  <Expandable title="Add Ons Object">
    <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="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>