Skip to main content
GET
/
v2
/
lists
{
  "lists": [
    {
      "id": 42,
      "phone_number": "+12025551234",
      "brand_name": "Acme Co",
      "list_name": "Acme Promo List",
      "list_type": "infobip",
      "status": "active",
      "contact_count": 15230,
      "created_at": "2025-03-15T14:30:00Z"
    },
    {
      "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:00Z"
    }
  ]
}
Returns all sending lists for your account, optionally filtered by status. By default, deleted lists are excluded from results.

​
Query Parameters

​
status
string
Filter lists by status. Accepted values: active, paused, suspended, deleted. When omitted, all lists except those with deleted status are returned.

​
Response Fields

​
lists
array
Array of sending list objects.

​
Examples

cURL
curl -X GET "https://app.tracklysms.com/api/v2/lists?status=active" \
  -H "X-Api-Key: trk_your_api_key_here"
Python
import requests

response = requests.get(
    "https://app.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://app.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": "infobip",
      "status": "active",
      "contact_count": 15230,
      "created_at": "2025-03-15T14:30:00Z"
    },
    {
      "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:00Z"
    }
  ]
}

​
Error Codes

HTTP StatusError CodeDescription
401unauthorizedAPI key is missing or invalid.

​
Next Steps

Contacts Overview

Manage contacts across your lists

List Contacts

View contacts on a specific list