{
"lists": [
{
"id": 42,
"phone_number": "+12025551234",
"brand_name": "Acme Co",
"list_name": "Acme Promo List",
"list_type": "twilio",
"status": "active",
"contact_count": 15230,
"created_at": "2025-03-15T14:30:00"
},
{
"id": 43,
"phone_number": "+12025559876",
"brand_name": "Acme Co",
"list_name": "Acme Welcome List",
"list_type": "twilio",
"status": "active",
"contact_count": 8412,
"created_at": "2025-04-01T09:00:00"
}
]
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Lists (v2)
List All Sending Lists
Retrieve all sending lists associated with your account.
GET
/
v2
/
lists
{
"lists": [
{
"id": 42,
"phone_number": "+12025551234",
"brand_name": "Acme Co",
"list_name": "Acme Promo List",
"list_type": "twilio",
"status": "active",
"contact_count": 15230,
"created_at": "2025-03-15T14:30:00"
},
{
"id": 43,
"phone_number": "+12025559876",
"brand_name": "Acme Co",
"list_name": "Acme Welcome List",
"list_type": "twilio",
"status": "active",
"contact_count": 8412,
"created_at": "2025-04-01T09:00:00"
}
]
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Returns all sending lists for your account, optionally filtered by status. By default, deleted lists are excluded from results.
Supply
List discovery does not establish send eligibility or recipient consent. API-key list constraints restrict sending, not this account-scoped read; check the key’s send policy and run preflight before proposing a send.
limit or cursor to request a bounded page. Paginated results are ordered by ascending list ID. Without either parameter, the existing unpaginated response is unchanged.
Query Parameters
string
Filter lists by status. Accepted values:
active, paused, suspended, deleted. When omitted, all lists except those with deleted status are returned.integer
Page size from 1 to 100. Supplying this parameter enables pagination. When only
cursor is supplied, the page size defaults to 50.string
Use the previous page’s
pagination.next_cursor unchanged with the same account and status filter. Cursors are at most 512 characters. A cursor from another account or status filter is rejected.Response Fields
array
Array of sending list objects.
Show List object properties
Show List object properties
integer
Unique identifier for the sending list.
string
The phone number associated with the list in E.164 format (e.g.
+12025551234).string
The brand name registered for this sending list.
string
The display name of the sending list.
string
The SMS provider used for this list. One of:
lime, infobip, twilio, cm, aloware.string
Current status of the list. One of:
active, paused, suspended, deleted.integer
The number of contacts currently subscribed to this list.
datetime
ISO 8601 timestamp of when the list was created.
object
Present only when
limit or cursor is supplied. Contains limit, has_more, and next_cursor. The cursor is null on the last page, including an empty result.Pagination
Start withGET /v2/lists?status=active&limit=50. Continue with the returned cursor and the same status=active filter until has_more is false. Pages reflect current list state rather than a fixed snapshot; creating or changing lists during traversal can change later results.
{
"lists": [],
"pagination": {
"limit": 50,
"has_more": false,
"next_cursor": null
}
}
Examples
cURL
curl -X GET "https://api.tracklysms.com/api/v2/lists?status=active" \
-H "X-Api-Key: trk_your_api_key_here"
Python
import requests
response = requests.get(
"https://api.tracklysms.com/api/v2/lists",
params={"status": "active"},
headers={"X-Api-Key": "trk_your_api_key_here"}
)
data = response.json()
for lst in data["lists"]:
print(f"{lst['list_name']} — {lst['contact_count']} contacts")
Node.js
const response = await fetch(
"https://api.tracklysms.com/api/v2/lists?status=active",
{
headers: {
"X-Api-Key": "trk_your_api_key_here",
},
}
);
const data = await response.json();
console.log(data.lists);
{
"lists": [
{
"id": 42,
"phone_number": "+12025551234",
"brand_name": "Acme Co",
"list_name": "Acme Promo List",
"list_type": "twilio",
"status": "active",
"contact_count": 15230,
"created_at": "2025-03-15T14:30:00"
},
{
"id": 43,
"phone_number": "+12025559876",
"brand_name": "Acme Co",
"list_name": "Acme Welcome List",
"list_type": "twilio",
"status": "active",
"contact_count": 8412,
"created_at": "2025-04-01T09:00:00"
}
]
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_param | Invalid limit or cursor, cursor account/status mismatch, or unsupported status when pagination is enabled. |
| 401 | invalid_credentials | API key is missing or invalid. |
| 403 | account_suspended | Your account is suspended. Resolve outstanding billing or contact support. |
Next Steps
Contacts Overview
Manage contacts across your lists
List Contacts
View contacts on a specific list