Pagination, filtering & sorting
Page, filter, and sort list results.
Every endpoint that returns a list (contacts, groups, messages, conversations, templates, media files, reports, webhooks) uses the same paging, filtering, and sorting conventions.
Paging
| Parameter | Values | Default |
|---|---|---|
page | 0-based page index | 0 |
size | 10, 20, 50, 100, or 200 | 20 |
curl "https://a.eztexting.com/v1/contacts?page=2&size=100" \
-u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD"import os, requests
auth = (os.environ["EZTEXTING_USERNAME"], os.environ["EZTEXTING_PASSWORD"])
page = requests.get("https://a.eztexting.com/v1/contacts", auth=auth, params={"page": 2, "size": 100}, timeout=30).json()const credentials = Buffer.from(
`${process.env.EZTEXTING_USERNAME}:${process.env.EZTEXTING_PASSWORD}`
).toString("base64");
const page = await (await fetch("https://a.eztexting.com/v1/contacts?page=2&size=100", {
headers: { Authorization: `Basic ${credentials}` },
})).json();<?php
$ch = curl_init("https://a.eztexting.com/v1/contacts?page=2&size=100");
curl_setopt($ch, CURLOPT_USERPWD, getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$page = json_decode(curl_exec($ch), true);
curl_close($ch);require "net/http"
require "json"
uri = URI("https://a.eztexting.com/v1/contacts?page=2&size=100")
req = Net::HTTP::Get.new(uri)
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
page = JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.body)String basicAuth = Base64.getEncoder().encodeToString(
(System.getenv("EZTEXTING_USERNAME") + ":" + System.getenv("EZTEXTING_PASSWORD")).getBytes());
HttpClient client = HttpClient.newHttpClient();
// Jackson
ObjectMapper mapper = new ObjectMapper();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://a.eztexting.com/v1/contacts?page=2&size=100"))
.header("Authorization", "Basic " + basicAuth)
.GET().build();
JsonNode page = mapper.readTree(client.send(request, HttpResponse.BodyHandlers.ofString()).body());var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(
$"{Environment.GetEnvironmentVariable("EZTEXTING_USERNAME")}:{Environment.GetEnvironmentVariable("EZTEXTING_PASSWORD")}"));
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);
var page = await client.GetFromJsonAsync<JsonElement>("https://a.eztexting.com/v1/contacts?page=2&size=100");req, _ := http.NewRequest("GET", "https://a.eztexting.com/v1/contacts?page=2&size=100", nil)
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var page map[string]any
json.NewDecoder(resp.Body).Decode(&page)The response wraps the items in a page envelope:
{
"content": [
{ "phoneNumber": "15551234567", "firstName": "Jane", "lastName": "Doe", "optOut": false, "groups": [] },
{ "phoneNumber": "15559876543", "firstName": "Sam", "lastName": "Park", "optOut": false, "groups": [] }
],
"number": 2,
"size": 100,
"totalElements": 2347,
"totalPages": 24,
"numberOfElements": 100
}| Field | Meaning |
|---|---|
content | The items on this page. |
number | The page you asked for. |
size | The page size you asked for. |
totalElements | How many items match in total. |
totalPages | ceil(totalElements / size). |
numberOfElements | How many items are actually on this page (less than size on the last page). |
Stop when number + 1 >= totalPages, or when content comes back empty. Use the largest size you can (200 for exports) to minimize requests against the rate limit.
Filtering
Filters use a bracket syntax in the query string: filters[field][operator]=value.
| Operator | Meaning | Example |
|---|---|---|
eq | Equals | filters[optOut][eq]=true |
like | Partial match (case-insensitive contains). On phone numbers, wrap a partial number in %: %5550% | filters[firstName][like]=jan |
gte | Greater than or equal | filters[sentAt][gte]=2026-11-01T00:00:00Z |
lte | Less than or equal | filters[sentAt][lte]=2026-11-30T23:59:59Z |
Only the fields and operators an endpoint supports are applied. An unknown field or operator is ignored, not rejected: you get the unfiltered list back. If a filter seems to do nothing, check totalElements.
Which fields and operators each endpoint supports is listed on its reference page. Some common ones:
| Endpoint | Useful filters |
|---|---|
GET /v1/contacts | filters[phoneNumber][like], filters[firstName][like], filters[lastName][like], filters[email][like], filters[groupName][like], filters[source][eq], filters[optOut][eq] |
GET /v1/messages | filters[contactNumber][eq], filters[userNumber][eq], filters[incoming][eq], filters[unread][eq], filters[type][eq] (sms/mms), filters[textQuery][eq], filters[messageId][eq] (the message ID), filters[deleted][eq] (true returns only deleted messages), filters[sentAt][gte], filters[sentAt][lte] |
GET /v1/conversations | filters[unread][eq], filters[archived][eq], filters[from][eq], filters[optType][eq] (optIn/optOut), filters[query][eq] |
GET /v1/message-reports/{id}/responses/delivery | filters[status][eq] (delivered/bounced/queued/not_sent) |
GET /v1/message-templates | filters[name][eq], filters[name][like] |
GET /v1/campaign-info | filters[sentAt][gte], filters[sentAt][lte] (dates as MM-dd-yyyy) |
Combine filters by repeating the parameter; they're ANDed:
curl -G https://a.eztexting.com/v1/contacts \
-u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
--data-urlencode "filters[groupName][like]=VIP" \
--data-urlencode "filters[optOut][eq]=false" \
--data-urlencode "size=200"vip = requests.get(
"https://a.eztexting.com/v1/contacts",
auth=auth,
params={"filters[groupName][like]": "VIP", "filters[optOut][eq]": "false", "size": 200},
timeout=30,
).json()const qs = new URLSearchParams({ "filters[groupName][like]": "VIP", "filters[optOut][eq]": "false", size: 200 });
const vip = await (await fetch(`https://a.eztexting.com/v1/contacts?${qs}`, {
headers: { Authorization: `Basic ${credentials}` },
})).json();<?php
$qs = http_build_query(["filters[groupName][like]" => "VIP", "filters[optOut][eq]" => "false", "size" => 200]);
$ch = curl_init("https://a.eztexting.com/v1/contacts?$qs");
curl_setopt($ch, CURLOPT_USERPWD, getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$vip = json_decode(curl_exec($ch), true);
curl_close($ch);uri = URI("https://a.eztexting.com/v1/contacts")
uri.query = URI.encode_www_form("filters[groupName][like]" => "VIP", "filters[optOut][eq]" => "false", "size" => 200)
req = Net::HTTP::Get.new(uri)
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
vip = JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.body)String qs = URLEncoder.encode("filters[groupName][like]", StandardCharsets.UTF_8) + "=VIP&"
+ URLEncoder.encode("filters[optOut][eq]", StandardCharsets.UTF_8) + "=false&size=200";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://a.eztexting.com/v1/contacts?" + qs))
.header("Authorization", "Basic " + basicAuth)
.GET().build();
JsonNode vip = mapper.readTree(client.send(request, HttpResponse.BodyHandlers.ofString()).body());var qs = $"{Uri.EscapeDataString("filters[groupName][like]")}=VIP&{Uri.EscapeDataString("filters[optOut][eq]")}=false&size=200";
var vip = await client.GetFromJsonAsync<JsonElement>($"https://a.eztexting.com/v1/contacts?{qs}");q := url.Values{"filters[groupName][like]": {"VIP"}, "filters[optOut][eq]": {"false"}, "size": {"200"}}
req, _ := http.NewRequest("GET", "https://a.eztexting.com/v1/contacts?"+q.Encode(), nil)
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
resp, err := http.DefaultClient.Do(req)[ and ] aren't valid in URLs unencoded. Most HTTP libraries encode them automatically when you pass a params object (requests, URLSearchParams, http.build_query). If you're hand-building a URL, write filters%5BoptOut%5D%5Beq%5D=false. cURL's --data-urlencode with -G handles it.
Sorting
sort=field,direction where direction is asc or desc, for example sort=created,desc. Sortable fields are listed per endpoint in the reference.
curl -G https://a.eztexting.com/v1/messages \
-u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
--data-urlencode "sort=created,desc" \
--data-urlencode "size=50"recent = requests.get(
"https://a.eztexting.com/v1/messages",
auth=auth,
params={"sort": "created,desc", "size": 50},
timeout=30,
).json()const qs = new URLSearchParams({ sort: "created,desc", size: 50 });
const recent = await (await fetch(`https://a.eztexting.com/v1/messages?${qs}`, {
headers: { Authorization: `Basic ${credentials}` },
})).json();<?php
$qs = http_build_query(["sort" => "created,desc", "size" => 50]);
$ch = curl_init("https://a.eztexting.com/v1/messages?$qs");
curl_setopt($ch, CURLOPT_USERPWD, getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$recent = json_decode(curl_exec($ch), true);
curl_close($ch);uri = URI("https://a.eztexting.com/v1/messages")
uri.query = URI.encode_www_form("sort" => "created,desc", "size" => 50)
req = Net::HTTP::Get.new(uri)
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
recent = JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.body)HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://a.eztexting.com/v1/messages?sort=created%2Cdesc&size=50"))
.header("Authorization", "Basic " + basicAuth)
.GET().build();
JsonNode recent = mapper.readTree(client.send(request, HttpResponse.BodyHandlers.ofString()).body());var recent = await client.GetFromJsonAsync<JsonElement>("https://a.eztexting.com/v1/messages?sort=created%2Cdesc&size=50");q := url.Values{"sort": {"created,desc"}, "size": {"50"}}
req, _ := http.NewRequest("GET", "https://a.eztexting.com/v1/messages?"+q.Encode(), nil)
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
resp, err := http.DefaultClient.Do(req)A page-through helper
import requests
def paginate(path, auth, params=None, size=200):
params = dict(params or {}, size=size)
page = 0
while True:
params["page"] = page
data = requests.get("https://a.eztexting.com" + path, auth=auth, params=params, timeout=30).json()
yield from data["content"]
if page + 1 >= data["totalPages"]:
return
page += 1
# Every opted-in contact in the VIP group
for c in paginate("/v1/contacts", auth,
{"filters[groupName][like]": "VIP", "filters[optOut][eq]": "false"}):
print(c["phoneNumber"], c["firstName"])async function* paginate(path, params = {}, size = 200) {
for (let page = 0; ; page++) {
const qs = new URLSearchParams({ ...params, size, page });
const data = await (await fetch(`https://a.eztexting.com${path}?${qs}`, {
headers: { Authorization: `Basic ${credentials}` },
})).json();
yield* data.content;
if (page + 1 >= data.totalPages) return;
}
}
// Every opted-in contact in the VIP group
for await (const c of paginate("/v1/contacts", {
"filters[groupName][like]": "VIP",
"filters[optOut][eq]": "false",
})) {
console.log(c.phoneNumber, c.firstName);
}<?php
function paginate(string $path, array $params = [], int $size = 200): Generator {
for ($page = 0; ; $page++) {
$qs = http_build_query($params + ['size' => $size, 'page' => $page]);
$ch = curl_init("https://a.eztexting.com$path?$qs");
curl_setopt($ch, CURLOPT_USERPWD, getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
yield from $data['content'];
if ($page + 1 >= $data['totalPages']) return;
}
}
foreach (paginate('/v1/contacts', ['filters[groupName][like]' => 'VIP', 'filters[optOut][eq]' => 'false']) as $c) {
echo "{$c['phoneNumber']} {$c['firstName']}\n";
}def paginate(path, params = {}, size: 200)
return to_enum(:paginate, path, params, size: size) unless block_given?
page = 0
loop do
uri = URI("https://a.eztexting.com#{path}")
uri.query = URI.encode_www_form(params.merge(size: size, page: page))
req = Net::HTTP::Get.new(uri)
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
data = JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }.body)
data["content"].each { |item| yield item }
break if page + 1 >= data["totalPages"]
page += 1
end
end
paginate("/v1/contacts", { "filters[groupName][like]" => "VIP", "filters[optOut][eq]" => "false" }).each do |c|
puts "#{c['phoneNumber']} #{c['firstName']}"
endStream<JsonNode> paginate(String path, Map<String, String> params, int size) {
return IntStream.iterate(0, page -> page + 1)
.mapToObj(page -> {
Map<String, String> q = new LinkedHashMap<>(params);
q.put("size", String.valueOf(size));
q.put("page", String.valueOf(page));
String qs = q.entrySet().stream()
.map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
.collect(Collectors.joining("&"));
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://a.eztexting.com" + path + "?" + qs))
.header("Authorization", "Basic " + basicAuth)
.GET().build();
try {
return mapper.readTree(client.send(request, HttpResponse.BodyHandlers.ofString()).body());
} catch (Exception e) {
throw new RuntimeException(e);
}
})
.takeWhile(data -> data.get("content").size() > 0)
.flatMap(data -> StreamSupport.stream(data.get("content").spliterator(), false));
}
// Every opted-in contact in the VIP group
paginate("/v1/contacts", Map.of("filters[groupName][like]", "VIP", "filters[optOut][eq]", "false"), 200)
.forEach(c -> System.out.println(c.get("phoneNumber").asText() + " " + c.path("firstName").asText("")));async IAsyncEnumerable<JsonElement> Paginate(string path, Dictionary<string, string> parameters, int size = 200)
{
for (var page = 0; ; page++)
{
var qs = string.Join("&", parameters
.Append(KeyValuePair.Create("size", size.ToString()))
.Append(KeyValuePair.Create("page", page.ToString()))
.Select(p => $"{Uri.EscapeDataString(p.Key)}={Uri.EscapeDataString(p.Value)}"));
var data = await client.GetFromJsonAsync<JsonElement>($"https://a.eztexting.com{path}?{qs}");
foreach (var item in data.GetProperty("content").EnumerateArray()) yield return item;
if (page + 1 >= data.GetProperty("totalPages").GetInt32()) yield break;
}
}
// Every opted-in contact in the VIP group
await foreach (var c in Paginate("/v1/contacts", new() { ["filters[groupName][like]"] = "VIP", ["filters[optOut][eq]"] = "false" }))
{
Console.WriteLine($"{c.GetProperty("phoneNumber")} {c.GetProperty("firstName")}");
}func paginate(path string, params url.Values, size int, each func(map[string]any) error) error {
for page := 0; ; page++ {
q := url.Values{}
for k, v := range params {
q[k] = v
}
q.Set("size", strconv.Itoa(size))
q.Set("page", strconv.Itoa(page))
req, _ := http.NewRequest("GET", "https://a.eztexting.com"+path+"?"+q.Encode(), nil)
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
var data struct {
Content []map[string]any `json:"content"`
TotalPages int `json:"totalPages"`
}
err = json.NewDecoder(resp.Body).Decode(&data)
resp.Body.Close()
if err != nil {
return err
}
for _, item := range data.Content {
if err := each(item); err != nil {
return err
}
}
if page+1 >= data.TotalPages {
return nil
}
}
}
// Every opted-in contact in the VIP group
paginate("/v1/contacts", url.Values{"filters[groupName][like]": {"VIP"}, "filters[optOut][eq]": {"false"}}, 200,
func(c map[string]any) error {
fmt.Println(c["phoneNumber"], c["firstName"])
return nil
})Tips
- Snapshot large exports by time. Contacts can be created while you page. For a consistent export of messages, pin the window with
filters[sentAt][lte]=<now>before you start. - Don't page to count.
totalElementson page 0 withsize=10tells you how many match without fetching them all. - Contact fields and webhook subscriptions: use
size=200, and don't rely onlastortotalPagesfor these two lists; keep paging until a page comes back empty. - Empty fields are omitted from list items rather than returned as
null. - Reports are paged too.
/responses/deliveryand friends can return thousands of rows for a big campaign, with the samepage/size/totalPagesenvelope.
Related
- Rate limits — paging through large lists counts against the limit
- Core concepts
- Troubleshooting — invalid filter errors
API reference
Try Troubleshooting, check status.eztexting.com, or contact support.
Updated 2 days ago