Real Contact API

curl --request GET \
  --url "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1" \
  --header "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();

import axios from "axios";

const { data } = await axios.get(
  "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
console.log(data);

import requests

headers = {"x-api-key": "YOUR_API_KEY"}
params = {
    "name": "John Doe",
    "phone": "4259853735",
    "email": "john.doe@example.com",
    "ip_address": "192.0.0.1",
}

response = requests.get(
    "https://api.trestleiq.com/2.0/real_contact",
    params=params,
    headers=headers,
    timeout=30,
)
data = response.json()
print(data)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var response = await client.GetAsync("https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1");
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

package main

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

func main() {
 req, _ := http.NewRequest("GET", "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1", 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
$curl = curl_init("https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1");
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;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class RealContactExample {
  public static void main(String[] args) throws Exception {
    HttpRequest request =
        HttpRequest.newBuilder()
            .uri(
                URI.create(
                    "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1"))
            .header("x-api-key", "YOUR_API_KEY")
            .GET()
            .build();

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

{
  "phone": {
    "contact_grade": "A",
    "is_valid": true,
    "activity_score": 95,
    "line_type": "Mobile",
    "name_match": true
  },
  "email": {
    "contact_grade": "A",
    "is_valid": true,
    "name_match": true
  },
  "address": {
    "is_valid": true,
    "name_match": true
  },
  "ip_address": {
    "trust_score": 92,
    "ip_distance_to_address": 12
  },
  "add_ons": {
    "litigator_checks": {
      "phone_is_litigator_risk": false
    },
    "email_checks": {
      "email_age_score": 95,
      "email_is_deliverable": true
    }
  },
  "warnings": [],
  "errors": null
}

curl --request GET \
  --url "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1" \
  --header "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();

import axios from "axios";

const { data } = await axios.get(
  "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
console.log(data);

import requests

headers = {"x-api-key": "YOUR_API_KEY"}
params = {
    "name": "John Doe",
    "phone": "4259853735",
    "email": "john.doe@example.com",
    "ip_address": "192.0.0.1",
}

response = requests.get(
    "https://api.trestleiq.com/2.0/real_contact",
    params=params,
    headers=headers,
    timeout=30,
)
data = response.json()
print(data)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var response = await client.GetAsync("https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1");
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

package main

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

func main() {
 req, _ := http.NewRequest("GET", "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1", 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
$curl = curl_init("https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1");
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;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class RealContactExample {
  public static void main(String[] args) throws Exception {
    HttpRequest request =
        HttpRequest.newBuilder()
            .uri(
                URI.create(
                    "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1"))
            .header("x-api-key", "YOUR_API_KEY")
            .GET()
            .build();

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

{
  "phone": {
    "contact_grade": "A",
    "is_valid": true,
    "activity_score": 95,
    "line_type": "Mobile",
    "name_match": true
  },
  "email": {
    "contact_grade": "A",
    "is_valid": true,
    "name_match": true
  },
  "address": {
    "is_valid": true,
    "name_match": true
  },
  "ip_address": {
    "trust_score": 92,
    "ip_distance_to_address": 12
  },
  "add_ons": {
    "litigator_checks": {
      "phone_is_litigator_risk": false
    },
    "email_checks": {
      "email_age_score": 95,
      "email_is_deliverable": true
    }
  },
  "warnings": [],
  "errors": null
}

curl --request GET \
  --url "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1" \
  --header "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();

import axios from "axios";

const { data } = await axios.get(
  "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
console.log(data);

import requests

headers = {"x-api-key": "YOUR_API_KEY"}
params = {
    "name": "John Doe",
    "phone": "4259853735",
    "email": "john.doe@example.com",
    "ip_address": "192.0.0.1",
}

response = requests.get(
    "https://api.trestleiq.com/2.0/real_contact",
    params=params,
    headers=headers,
    timeout=30,
)
data = response.json()
print(data)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var response = await client.GetAsync("https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1");
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

package main

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

func main() {
 req, _ := http.NewRequest("GET", "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1", 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
$curl = curl_init("https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1");
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;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class RealContactExample {
  public static void main(String[] args) throws Exception {
    HttpRequest request =
        HttpRequest.newBuilder()
            .uri(
                URI.create(
                    "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1"))
            .header("x-api-key", "YOUR_API_KEY")
            .GET()
            .build();

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

{
  "phone": {
    "contact_grade": "A",
    "is_valid": true,
    "activity_score": 95,
    "line_type": "Mobile",
    "name_match": true
  },
  "email": {
    "contact_grade": "A",
    "is_valid": true,
    "name_match": true
  },
  "address": {
    "is_valid": true,
    "name_match": true
  },
  "ip_address": {
    "trust_score": 92,
    "ip_distance_to_address": 12
  },
  "add_ons": {
    "litigator_checks": {
      "phone_is_litigator_risk": false
    },
    "email_checks": {
      "email_age_score": 95,
      "email_is_deliverable": true
    }
  },
  "warnings": [],
  "errors": null
}

curl --request GET \
  --url "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1" \
  --header "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();

import axios from "axios";

const { data } = await axios.get(
  "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
console.log(data);

import requests

headers = {"x-api-key": "YOUR_API_KEY"}
params = {
    "name": "John Doe",
    "phone": "4259853735",
    "email": "john.doe@example.com",
    "ip_address": "192.0.0.1",
}

response = requests.get(
    "https://api.trestleiq.com/2.0/real_contact",
    params=params,
    headers=headers,
    timeout=30,
)
data = response.json()
print(data)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var response = await client.GetAsync("https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1");
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

package main

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

func main() {
 req, _ := http.NewRequest("GET", "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1", 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
$curl = curl_init("https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1");
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;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class RealContactExample {
  public static void main(String[] args) throws Exception {
    HttpRequest request =
        HttpRequest.newBuilder()
            .uri(
                URI.create(
                    "https://api.trestleiq.com/2.0/real_contact?name=John%20Doe&phone=4259853735&email=john.doe@example.com&ip_address=192.0.0.1"))
            .header("x-api-key", "YOUR_API_KEY")
            .GET()
            .build();

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

{
  "phone": {
    "contact_grade": "A",
    "is_valid": true,
    "activity_score": 95,
    "line_type": "Mobile",
    "name_match": true
  },
  "email": {
    "contact_grade": "A",
    "is_valid": true,
    "name_match": true
  },
  "address": {
    "is_valid": true,
    "name_match": true
  },
  "ip_address": {
    "trust_score": 92,
    "ip_distance_to_address": 12
  },
  "add_ons": {
    "litigator_checks": {
      "phone_is_litigator_risk": false
    },
    "email_checks": {
      "email_age_score": 95,
      "email_is_deliverable": true
    }
  },
  "warnings": [],
  "errors": null
}

Real Contact 2.0

GET https://api.trestleiq.com/2.0/real_contact?name=[insert_name]&phone=[insert_phone]&email=[insert_email]&address.street_line_1=[insert_street_line_1]&address.city=[insert_city]&address.state_code=[insert_state_code]&address.postal_code=[insert_postal_code]&address.country_code=[insert_country_code]&ip_address=[insert_ip_address]

Note: Authentication must be provided via the x-api-key header. Query parameter authentication is not supported in v2.0.

Query Parameters

string

required

The name of the person to search. Example: name=John Doe

string

The first name of the person to search. Example: first_name=John

string

The last name of the person to search. Example: last_name=Doe

string

The business name to search. Example: business.name=The Golden Company

string

required

The phone provided by the lead on the web form. Example: phone=4259853735

string

The email provided by the lead on the web form. Example: email=john.doe@example.com

string

The first line of the street part in the structured address. Example: address.street_line_1=100 Syrws St

string

The second line of the street part in the structured address. Example: address.street_line_2=Apt 4B

string

The name of the city in the structured address. Example: address.city=Lynden

string

The state code of the structured address. Example: address.state_code=WA

string

The postal code of the structured address. Example: address.postal_code=98229

string (ISO-3166-2)

The ISO-3166 alpha-2 country code of the address. Example: address.country_code=US

string

The IP address captured at the time of interaction (web form, sign up, etc.). Example: ip_address=192.0.0.1

string

Request parameter to enable specific add-ons available for this endpoint. Add-ons incur additional charges. Please see here for more details.

email_checks_deliverability: to enable email deliverability checks in the response
email_checks_age: to enable email age score in the response
litigator_checks: to enable litigator checks in the response

Example: add_ons=litigator_checks,email_checks_deliverability

Headers

string

required

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

Response

object

Phone verification and grading results.

Hide phone object

string or null

An A-F grade determining the quality of the lead and whether it is contactable. A Grade-F lead is a bad lead and should be deprioritized while a Grade-A lead is real and contactable and should be prioritized. Read up on contact grades in our Knowledge Base article.

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

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

boolean or null

A match/no match indicator whether the name provided on the lead form matches to the input phone number according to our database. A match is a positive indicator that verifies the lead is real and is who he/she says they are.

object

Email verification and grading results.

Hide email object

string or null

An A-F grade determining the quality of the lead and whether it is contactable via the email provided. Read up on contact grades in our Knowledge Base article.

boolean or null

True if the email is valid.

boolean or null

A match/no match indicator whether the name provided on the lead form matches to the input email address according to our database.

object

Address verification results.

Hide address object

boolean or null

True if the address is valid.

boolean or null

A match/no match indicator whether the name provided on the lead form matches to the input address according to our database.

object or null

IP Trust Score and IP distance results. Returned when an IP address is provided in the request.

Hide ip_address object

integer or null

The IP Trust Score is a 0–100 score that evaluates how legitimate an interaction appears based on the user’s IP address. It factors in network type (VPN, proxy, data center vs. residential), IP reuse/sharing patterns, and geographic signals to determine whether the lead, contact, or signup is from an authentic source or potentially risky.

integer or null

The approximate distance (in miles) between the user’s IP location and the provided address. This helps assess whether the user’s location aligns with the provided contact details. This returns NULL values when confidence in the location accuracy of the IP address is low.

object or null

Hide Add Ons Object

object

Hide litigator_checks

boolean or null

True if the phone subscriber is a TCPA litigator.

object

Hide email_checks Object

boolean or null

True if the email is valid and deliverable.

integer or null

A 0-100 score indicating the longevity and activity-level of an email address.

object(PartialError) or null

Error details in case of a partial error, or null if no errors occurred.

Hide errors object

string

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

string

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

string[]

Warnings returned as part of the response, if applicable.Missing InputMissing Unit/Apt/Suite NumberInvalid AddressInvalid House/Building NumberInvalid Unit/Apt/Suite NumberInvalid PhoneLead is a Litigator. Must not be contacted.TimeoutError: Timeout getting response for litigator check. Partial response returned.Invalid EmailFree Email Service ProviderTumbled EmailDisposible EmailPrivacy EmailEmail is a spam trapPotential Junk EmailRole Based EmailUndeliverable EmailDomain is a catch all and does not support validationMX forwarding detected. This email may route through a forwarding service.Could not validate emailTimeoutError: Timeout getting a response from the email server for email deliverability checkInput IP address is invalid. Please provide a valid IPv4 or IPv6 addressTimeout getting response for IP information. Partial response returned

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.

Get Started

API Reference

Reference

Real Contact 2.0

Query Parameters

Headers

Response

Error Responses

400 Bad Request

403 Forbidden

429 Too Many Requests

500 Internal Server Error

​Real Contact 2.0

​Query Parameters

​Headers

​Response

​Error Responses

​400 Bad Request

​403 Forbidden

​429 Too Many Requests

​500 Internal Server Error

Real Contact 2.0

Query Parameters

Headers

Response

Error Responses

400 Bad Request

403 Forbidden

429 Too Many Requests

500 Internal Server Error