List a segment's contacts
curl --request GET \
--url https://api.privy.com/v1/segments/{id}/contacts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.privy.com/v1/segments/{id}/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.privy.com/v1/segments/{id}/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.privy.com/v1/segments/{id}/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.privy.com/v1/segments/{id}/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.privy.com/v1/segments/{id}/contacts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.privy.com/v1/segments/{id}/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": "cus_a1b2c3d4e5f6g7h8",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane@example.com",
"email_consent": "subscribed",
"email_consent_at": "2025-03-20T14:22:00Z",
"phone_number": "+15551234567",
"sms_consent": "subscribed",
"sms_consent_at": "2025-03-20T14:22:00Z",
"source": "csv",
"source_type": "import",
"imported": true,
"import_ids": [
"im_k2R5m8Q"
],
"tags": [
"vip"
],
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-03-20T14:22:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 40,
"total_count": 1240,
"total_pages": 31
}
}{
"status": "processing",
"message": "Segment membership is being computed. Check back shortly."
}{
"error": {
"code": "unauthorized",
"message": "Bearer token is missing or invalid"
}
}{
"error": {
"code": "insufficient_scope",
"message": "Token does not have the required scope"
}
}{
"error": {
"code": "not_found",
"message": "Not found"
}
}{
"error": {
"code": "contacts_not_ready",
"message": "This account's contacts have not been assigned public API ids, so contact reads are unavailable. Enable API access for the account, or have Privy staff run the public_id backfill task for it, then retry."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded"
}
}Segments
List a segment's contacts
Retrieve the segment’s members as a paginated list of contacts, in the same shape as the Contacts API, most recently created first.
Membership is computed periodically, so the list may be up to an hour old (see
counts.refreshed_at on the segment). If the segment’s membership has never been computed,
this endpoint returns 202 Accepted, starts the computation in the background, and you should
retry shortly.
Every member is returned whatever their consent state, so pagination.total_count is the
segment’s total membership, as its total_count was at the last refresh. It is neither the
segment’s mailable_count nor its textable_count — those are consent-filtered counts taken
at the last refresh.
Required scope: segments_read
GET
/
segments
/
{id}
/
contacts
List a segment's contacts
curl --request GET \
--url https://api.privy.com/v1/segments/{id}/contacts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.privy.com/v1/segments/{id}/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.privy.com/v1/segments/{id}/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.privy.com/v1/segments/{id}/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.privy.com/v1/segments/{id}/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.privy.com/v1/segments/{id}/contacts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.privy.com/v1/segments/{id}/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": "cus_a1b2c3d4e5f6g7h8",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane@example.com",
"email_consent": "subscribed",
"email_consent_at": "2025-03-20T14:22:00Z",
"phone_number": "+15551234567",
"sms_consent": "subscribed",
"sms_consent_at": "2025-03-20T14:22:00Z",
"source": "csv",
"source_type": "import",
"imported": true,
"import_ids": [
"im_k2R5m8Q"
],
"tags": [
"vip"
],
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-03-20T14:22:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 40,
"total_count": 1240,
"total_pages": 31
}
}{
"status": "processing",
"message": "Segment membership is being computed. Check back shortly."
}{
"error": {
"code": "unauthorized",
"message": "Bearer token is missing or invalid"
}
}{
"error": {
"code": "insufficient_scope",
"message": "Token does not have the required scope"
}
}{
"error": {
"code": "not_found",
"message": "Not found"
}
}{
"error": {
"code": "contacts_not_ready",
"message": "This account's contacts have not been assigned public API ids, so contact reads are unavailable. Enable API access for the account, or have Privy staff run the public_id backfill task for it, then retry."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded"
}
}Authorizations
Headers
Path Parameters
Query Parameters
Was this page helpful?