List Contacts
curl --request GET \
--url https://api.usesimple.ai/api/v1/contacts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.usesimple.ai/api/v1/contacts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.usesimple.ai/api/v1/contacts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usesimple.ai/api/v1/contacts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.usesimple.ai/api/v1/contacts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.usesimple.ai/api/v1/contacts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usesimple.ai/api/v1/contacts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"email": "jsmith@example.com",
"phoneNumber": "<string>",
"isTest": true,
"attributes": {},
"derivedAttributes": {},
"externalIdentities": [
{
"sourceKey": "<string>",
"externalId": "<string>"
}
],
"consents": [
{
"phoneNumber": "<string>",
"sourceKey": "<string>",
"medium": "voice",
"category": "all",
"status": "opted_in",
"observedAt": "2023-11-07T05:31:56Z"
}
]
}
],
"hasMore": true,
"nextCursor": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"status": "error",
"success": false,
"error": "<string>",
"errors": [
"<string>"
]
}{
"status": "error",
"success": false,
"error": "<string>",
"errors": [
"<string>"
]
}List Contacts
List contacts with filters for source, external ID, email, or phone number.
GET
/
contacts
List Contacts
curl --request GET \
--url https://api.usesimple.ai/api/v1/contacts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.usesimple.ai/api/v1/contacts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.usesimple.ai/api/v1/contacts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usesimple.ai/api/v1/contacts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.usesimple.ai/api/v1/contacts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.usesimple.ai/api/v1/contacts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usesimple.ai/api/v1/contacts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"email": "jsmith@example.com",
"phoneNumber": "<string>",
"isTest": true,
"attributes": {},
"derivedAttributes": {},
"externalIdentities": [
{
"sourceKey": "<string>",
"externalId": "<string>"
}
],
"consents": [
{
"phoneNumber": "<string>",
"sourceKey": "<string>",
"medium": "voice",
"category": "all",
"status": "opted_in",
"observedAt": "2023-11-07T05:31:56Z"
}
]
}
],
"hasMore": true,
"nextCursor": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"status": "error",
"success": false,
"error": "<string>",
"errors": [
"<string>"
]
}{
"status": "error",
"success": false,
"error": "<string>",
"errors": [
"<string>"
]
}Filter by
The response contains
sourceKey, externalId, phoneNumber, or email. All supplied filters must match. externalId requires sourceKey; email matching is case-insensitive. Phone numbers use E.164 format. URL-encode a leading plus sign as %2B.
curl 'https://api.usesimple.ai/api/v1/contacts?sourceKey=your_crm&externalId=customer-42' \
--header 'Authorization: Bearer YOUR_API_KEY'
data, hasMore, and nextCursor. Each contact has the same profile fields as Get Contact, including consent records for its current phone number. Only active contacts in your organization are included. No matches returns an empty data array.
Results are ordered by UUID. Set limit between 1 and 100 (default 50). When hasMore is true, pass after with the returned nextCursor, keeping the same filters, to fetch the next page.Authorizations
Your API key, sent as Authorization: Bearer YOUR_API_KEY
Query Parameters
Stable lowercase snake_case identifier for the source.
Required string length:
1 - 63Pattern:
^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$Required string length:
1 - 1000Pattern:
^\+[1-9]\d{1,14}$Required range:
1 <= x <= 100Last modified on September 17, 2026