curl -X GET "https://api.tracklysms.com/api/v2/contacts?list_number=%2B18005551234&active=true&page=1&per_page=50" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
response = requests.get(
"https://api.tracklysms.com/api/v2/contacts",
params={
"list_number": "+18005551234",
"active": "true",
"page": 1,
"per_page": 50
},
headers={"X-Api-Key": "trk_your_api_key_here"}
)
data = response.json()
for contact in data["contacts"]:
print(contact["phone_number"], contact["active"])
const response = await fetch(
"https://api.tracklysms.com/api/v2/contacts?list_number=%2B18005551234&active=true&page=1&per_page=50",
{
method: "GET",
headers: {
"X-Api-Key": "trk_your_api_key_here",
},
}
);
const data = await response.json();
console.log(data.contacts);
console.log(data.pagination);
{
"contacts": [
{
"phone_number": "+14155559876",
"list_number": "+18005551234",
"list_id": 42,
"active": true,
"signup_date": "2025-03-15T14:30:00",
"signup_method": "api",
"custom_fields": {
"first_name": "Jane",
"source": "landing_page_v2"
},
"carrier": "T-Mobile",
"line_type": "mobile",
"timezone": "America/Los_Angeles",
"is_valid": true,
"country": "US",
"send_count": 12,
"click_count": 3,
"revenue_total": 47.50,
"conversion_count": 1,
"last_sent_at": "2025-04-01T18:00:00",
"last_clicked_at": "2025-04-01T18:05:32",
"in_workflow": false
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 1,
"total_pages": 1
}
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Contacts (v2)
List Contacts
Retrieve a paginated list of contacts for your account, with optional filtering by list and subscription status.
GET
/
v2
/
contacts
curl -X GET "https://api.tracklysms.com/api/v2/contacts?list_number=%2B18005551234&active=true&page=1&per_page=50" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
response = requests.get(
"https://api.tracklysms.com/api/v2/contacts",
params={
"list_number": "+18005551234",
"active": "true",
"page": 1,
"per_page": 50
},
headers={"X-Api-Key": "trk_your_api_key_here"}
)
data = response.json()
for contact in data["contacts"]:
print(contact["phone_number"], contact["active"])
const response = await fetch(
"https://api.tracklysms.com/api/v2/contacts?list_number=%2B18005551234&active=true&page=1&per_page=50",
{
method: "GET",
headers: {
"X-Api-Key": "trk_your_api_key_here",
},
}
);
const data = await response.json();
console.log(data.contacts);
console.log(data.pagination);
{
"contacts": [
{
"phone_number": "+14155559876",
"list_number": "+18005551234",
"list_id": 42,
"active": true,
"signup_date": "2025-03-15T14:30:00",
"signup_method": "api",
"custom_fields": {
"first_name": "Jane",
"source": "landing_page_v2"
},
"carrier": "T-Mobile",
"line_type": "mobile",
"timezone": "America/Los_Angeles",
"is_valid": true,
"country": "US",
"send_count": 12,
"click_count": 3,
"revenue_total": 47.50,
"conversion_count": 1,
"last_sent_at": "2025-04-01T18:00:00",
"last_clicked_at": "2025-04-01T18:05:32",
"in_workflow": false
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 1,
"total_pages": 1
}
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Returns all contacts associated with your account. Results are sorted by signup date in descending order (newest first). Use query parameters to filter by sending list or active/inactive subscription status.
Query Parameters
string
Filter contacts by sending list phone number. Must be in E.164 format (e.g.,
+18005551234).string
Filter by subscription status. Pass
"true" to return only active (subscribed) contacts, or "false" to return only inactive (unsubscribed) contacts. Omit to return all contacts regardless of status.integer
default:"1"
Page number for pagination.
integer
default:"50"
Number of contacts per page. Maximum value is
1000.Response Fields
array
Array of contact objects.
Show Contact object properties
Show Contact object properties
string
Contact phone number in E.164 format.
string
Sending list phone number in E.164 format.
integer
Unique identifier of the sending list.
boolean
Whether the contact is currently subscribed to the list.
string
ISO 8601 UTC timestamp of when the contact was added.
string
How the contact was added (e.g.,
api, web_form, import).object
Key-value pairs of custom fields associated with the contact on this list.
string
Mobile carrier name.
string
Phone line type. Values:
mobile, landline, voip, toll_free, unknown, premium_rate. null when the number carries no classification or was flagged as an invalid number (a fake/invalid-number verdict stores line_type: null and sets is_valid to false).string
Contact’s timezone based on phone number area code.
boolean
Whether the phone number passed carrier validation.
null if the number has never been validated for your account.string
ISO 3166-1 alpha-2 country code.
null if the number has never been validated for your account.integer
Total number of messages sent to this contact on this list.
integer
Total number of link clicks from this contact on this list.
number
Total revenue attributed to this contact on this list.
integer
Total number of conversions attributed to this contact on this list.
string
ISO 8601 UTC timestamp of the last message sent to this contact.
string
ISO 8601 UTC timestamp of the last click from this contact.
boolean
Whether the contact is currently enrolled in an active journey workflow.
object
Examples
curl -X GET "https://api.tracklysms.com/api/v2/contacts?list_number=%2B18005551234&active=true&page=1&per_page=50" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
response = requests.get(
"https://api.tracklysms.com/api/v2/contacts",
params={
"list_number": "+18005551234",
"active": "true",
"page": 1,
"per_page": 50
},
headers={"X-Api-Key": "trk_your_api_key_here"}
)
data = response.json()
for contact in data["contacts"]:
print(contact["phone_number"], contact["active"])
const response = await fetch(
"https://api.tracklysms.com/api/v2/contacts?list_number=%2B18005551234&active=true&page=1&per_page=50",
{
method: "GET",
headers: {
"X-Api-Key": "trk_your_api_key_here",
},
}
);
const data = await response.json();
console.log(data.contacts);
console.log(data.pagination);
{
"contacts": [
{
"phone_number": "+14155559876",
"list_number": "+18005551234",
"list_id": 42,
"active": true,
"signup_date": "2025-03-15T14:30:00",
"signup_method": "api",
"custom_fields": {
"first_name": "Jane",
"source": "landing_page_v2"
},
"carrier": "T-Mobile",
"line_type": "mobile",
"timezone": "America/Los_Angeles",
"is_valid": true,
"country": "US",
"send_count": 12,
"click_count": 3,
"revenue_total": 47.50,
"conversion_count": 1,
"last_sent_at": "2025-04-01T18:00:00",
"last_clicked_at": "2025-04-01T18:05:32",
"in_workflow": false
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 1,
"total_pages": 1
}
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 401 | invalid_credentials | Missing or invalid X-Api-Key header. |
| 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. |
| 500 | internal_error | An unexpected server error occurred. |
Next Steps
Importing Contacts
Import contacts in bulk
Create Audience
Segment your contacts into audiences
⌘I