Skip to main content
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"

{
  "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": "CELL PHONE",
      "timezone": "America/Los_Angeles",
      "is_valid": true,
      "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
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
list_number
string
Filter contacts by sending list phone number. Must be in E.164 format (e.g., +18005551234).
​
active
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.
​
page
integer
default:"1"
Page number for pagination.
​
per_page
integer
default:"50"
Number of contacts per page. Maximum value is 1000.

​
Response Fields

​
contacts
array
Array of contact objects.
​
pagination
object
Pagination metadata.

​
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"

{
  "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": "CELL PHONE",
      "timezone": "America/Los_Angeles",
      "is_valid": true,
      "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 Codes

HTTP StatusError CodeDescription
401unauthorizedMissing or invalid X-Api-Key header.
500internal_errorAn unexpected server error occurred.

​
Next Steps

Importing Contacts

Import contacts in bulk

Create Audience

Segment your contacts into audiences