Skip to main content
GET
/
v2
/
contacts
/
{phone_number}
curl -X GET "https://app.tracklysms.com/api/v2/contacts/%2B14155559876" \
  -H "X-Api-Key: trk_your_api_key_here"

{
  "phone_number": "+14155559876",
  "carrier": "T-Mobile",
  "line_type": "CELL PHONE",
  "timezone": "America/Los_Angeles",
  "is_valid": true,
  "lists": [
    {
      "list_id": 42,
      "list_number": "+18005551234",
      "active": true,
      "signup_date": "2025-03-15T14:30:00",
      "custom_fields": {
        "first_name": "Jane",
        "source": "landing_page_v2"
      },
      "send_count": 12,
      "click_count": 3
    },
    {
      "list_id": 43,
      "list_number": "+18005559999",
      "active": false,
      "signup_date": "2025-01-10T09:00:00",
      "custom_fields": {},
      "send_count": 5,
      "click_count": 0
    }
  ]
}
Returns contact details and all list memberships for a given phone number across every sending list owned by your account. This provides a unified view of a contact’s carrier information, validation status, and per-list engagement metrics.

​
Path Parameters

​
phone_number
string
required
Contact phone number in E.164 format. Must be URL-encoded in the request path (e.g., %2B14155559876 for +14155559876).

​
Response Fields

​
phone_number
string
Contact phone number in E.164 format.
​
carrier
string
Mobile carrier name (e.g., T-Mobile, Verizon, AT&T).
​
line_type
string
Phone line type. Values: CELL PHONE, VOIP, LANDLINE, FAKE, UNKNOWN.
​
timezone
string
Contact’s timezone based on phone number area code (e.g., America/New_York).
​
is_valid
boolean
Whether the phone number passed carrier validation and is deliverable.
​
lists
array
Array of list membership objects representing every list this contact appears on within your account.

​
Examples

curl -X GET "https://app.tracklysms.com/api/v2/contacts/%2B14155559876" \
  -H "X-Api-Key: trk_your_api_key_here"

{
  "phone_number": "+14155559876",
  "carrier": "T-Mobile",
  "line_type": "CELL PHONE",
  "timezone": "America/Los_Angeles",
  "is_valid": true,
  "lists": [
    {
      "list_id": 42,
      "list_number": "+18005551234",
      "active": true,
      "signup_date": "2025-03-15T14:30:00",
      "custom_fields": {
        "first_name": "Jane",
        "source": "landing_page_v2"
      },
      "send_count": 12,
      "click_count": 3
    },
    {
      "list_id": 43,
      "list_number": "+18005559999",
      "active": false,
      "signup_date": "2025-01-10T09:00:00",
      "custom_fields": {},
      "send_count": 5,
      "click_count": 0
    }
  ]
}

​
Error Codes

HTTP StatusError CodeDescription
400invalid_phoneThe phone number in the path is not a valid E.164 number.
401unauthorizedMissing or invalid X-Api-Key header.
404not_foundThe contact does not exist or is not on any sending list owned by your account.
500internal_errorAn unexpected server error occurred.
The + character in E.164 phone numbers must be URL-encoded as %2B in the path. For example, +14155559876 becomes %2B14155559876.

​
Next Steps

Importing Contacts

Import contacts in bulk

Create Audience

Segment your contacts