Skip to main content
GET
/
v2
/
contacts
curl -X GET "https://app.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
  }
}
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://app.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