Get a Sending List

{
  "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"
}

{
  "error": "List not found",
  "code": "not_found"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

GET

lists

{list_id}

{
  "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"
}

{
  "error": "List not found",
  "code": "not_found"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

Returns the full details of a single sending list, including an accurate count of active contacts.

Path Parameters

integer

required

The unique identifier of the sending list.

Response Fields

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 active contacts on this list. Calculated by counting the active ListContacts for this list.

datetime

ISO 8601 timestamp of when the list was created.

Examples

cURL

curl -X GET "https://api.tracklysms.com/api/v2/lists/42" \
  -H "X-Api-Key: trk_your_api_key_here"

Python

import requests

response = requests.get(
    "https://api.tracklysms.com/api/v2/lists/42",
    headers={"X-Api-Key": "trk_your_api_key_here"}
)

data = response.json()
print(f"{data['list_name']} — {data['contact_count']} contacts")

Node.js

const response = await fetch(
  "https://api.tracklysms.com/api/v2/lists/42",
  {
    headers: {
      "X-Api-Key": "trk_your_api_key_here",
    },
  }
);

const data = await response.json();
console.log(data);

{
  "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"
}

{
  "error": "List not found",
  "code": "not_found"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

Error Codes

HTTP Status	Error Code	Description
401	`invalid_credentials`	API key is missing or invalid.
403	`account_suspended`	Your account is suspended. Resolve outstanding billing or contact support.
429	`rate_limited`	Request throttled; retry with exponential backoff after the window resets.
404	`not_found`	No sending list exists with the given ID, or the list has been deleted.

API Reference

V2 API Reference

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Profiles (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

API Reference (v1 - Deprecated)

Path Parameters

Response Fields

Examples

Error Codes

Next Steps

Contacts Overview

List Contacts

​Path Parameters

​Response Fields

​Examples

​Error Codes

​Next Steps

Contacts Overview

List Contacts

Path Parameters

Response Fields

Examples

Error Codes

Next Steps