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

ParameterValuesDefault
page0-based page index0
size10, 20, 50, 100, or 20020
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
}
FieldMeaning
contentThe items on this page.
numberThe page you asked for.
sizeThe page size you asked for.
totalElementsHow many items match in total.
totalPagesceil(totalElements / size).
numberOfElementsHow 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.

OperatorMeaningExample
eqEqualsfilters[optOut][eq]=true
likePartial match (case-insensitive contains). On phone numbers, wrap a partial number in %: %5550%filters[firstName][like]=jan
gteGreater than or equalfilters[sentAt][gte]=2026-11-01T00:00:00Z
lteLess than or equalfilters[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:

EndpointUseful filters
GET /v1/contactsfilters[phoneNumber][like], filters[firstName][like], filters[lastName][like], filters[email][like], filters[groupName][like], filters[source][eq], filters[optOut][eq]
GET /v1/messagesfilters[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/conversationsfilters[unread][eq], filters[archived][eq], filters[from][eq], filters[optType][eq] (optIn/optOut), filters[query][eq]
GET /v1/message-reports/{id}/responses/deliveryfilters[status][eq] (delivered/bounced/queued/not_sent)
GET /v1/message-templatesfilters[name][eq], filters[name][like]
GET /v1/campaign-infofilters[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)
URL-encode the brackets

[ 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']}"
end
Stream<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. totalElements on page 0 with size=10 tells you how many match without fetching them all.
  • Contact fields and webhook subscriptions: use size=200, and don't rely on last or totalPages for 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/delivery and friends can return thousands of rows for a big campaign, with the same page/size/totalPages envelope.

Related

API reference


Did this page help you?