curl -X GET "https://api.tracklysms.com/api/v2/contacts/%2B14155559876" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
from urllib.parse import quote
phone_number = "+14155559876"
encoded_phone = quote(phone_number, safe="")
response = requests.get(
f"https://api.tracklysms.com/api/v2/contacts/{encoded_phone}",
headers={"X-Api-Key": "trk_your_api_key_here"}
)
data = response.json()
print(f"Phone: {data['phone_number']}")
print(f"Carrier: {data['carrier']}")
print(f"Lists: {len(data['lists'])}")
for membership in data["lists"]:
print(f" {membership['list_number']} - Active: {membership['active']}")
const phoneNumber = "+14155559876";
const encodedPhone = encodeURIComponent(phoneNumber);
const response = await fetch(
`https://api.tracklysms.com/api/v2/contacts/${encodedPhone}`,
{
method: "GET",
headers: {
"X-Api-Key": "trk_your_api_key_here",
},
}
);
const data = await response.json();
console.log(`Phone: ${data.phone_number}`);
console.log(`Carrier: ${data.carrier}`);
console.log(`On ${data.lists.length} list(s)`);
{
"phone_number": "+14155559876",
"carrier": "T-Mobile",
"line_type": "mobile",
"timezone": "America/Los_Angeles",
"is_valid": true,
"country": "US",
"lists": [
{
"list_id": 42,
"list_number": "+18005551234",
"active": true,
"signup_date": "2025-03-15T14:30:00",
"unsub_reason": null,
"unsub_date": null,
"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",
"unsub_reason": "message",
"unsub_date": "2025-02-01T11:15:00",
"custom_fields": {},
"send_count": 5,
"click_count": 0
}
]
}
{
"error": "Invalid E.164 phone number format",
"code": "invalid_phone"
}
{
"error": "Contact not found",
"code": "not_found"
}
Contacts (v2)
Get Contact
Retrieve detailed contact information and list memberships by phone number.
GET
/
v2
/
contacts
/
{phone_number}
curl -X GET "https://api.tracklysms.com/api/v2/contacts/%2B14155559876" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
from urllib.parse import quote
phone_number = "+14155559876"
encoded_phone = quote(phone_number, safe="")
response = requests.get(
f"https://api.tracklysms.com/api/v2/contacts/{encoded_phone}",
headers={"X-Api-Key": "trk_your_api_key_here"}
)
data = response.json()
print(f"Phone: {data['phone_number']}")
print(f"Carrier: {data['carrier']}")
print(f"Lists: {len(data['lists'])}")
for membership in data["lists"]:
print(f" {membership['list_number']} - Active: {membership['active']}")
const phoneNumber = "+14155559876";
const encodedPhone = encodeURIComponent(phoneNumber);
const response = await fetch(
`https://api.tracklysms.com/api/v2/contacts/${encodedPhone}`,
{
method: "GET",
headers: {
"X-Api-Key": "trk_your_api_key_here",
},
}
);
const data = await response.json();
console.log(`Phone: ${data.phone_number}`);
console.log(`Carrier: ${data.carrier}`);
console.log(`On ${data.lists.length} list(s)`);
{
"phone_number": "+14155559876",
"carrier": "T-Mobile",
"line_type": "mobile",
"timezone": "America/Los_Angeles",
"is_valid": true,
"country": "US",
"lists": [
{
"list_id": 42,
"list_number": "+18005551234",
"active": true,
"signup_date": "2025-03-15T14:30:00",
"unsub_reason": null,
"unsub_date": null,
"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",
"unsub_reason": "message",
"unsub_date": "2025-02-01T11:15:00",
"custom_fields": {},
"send_count": 5,
"click_count": 0
}
]
}
{
"error": "Invalid E.164 phone number format",
"code": "invalid_phone"
}
{
"error": "Contact not found",
"code": "not_found"
}
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
Contact phone number in E.164 format. Must be URL-encoded in the request path (e.g.,
%2B14155559876 for +14155559876).Response Fields
Mobile carrier name (e.g.,
T-Mobile, Verizon, AT&T). null when the number has never been validated for your account.Phone line type. Values:
mobile, landline, voip, toll_free, unknown, premium_rate. null when the number has never been validated for your account, when the number carries no classification, or when flagged as an invalid number (a fake/invalid-number verdict stores line_type: null and sets is_valid to false).Whether the phone number passed carrier validation and is deliverable.
null if the number has never been validated for your account.ISO 3166-1 alpha-2 country code.
null if the number has never been validated for your account.Array of list membership objects representing every list this contact appears on within your account.
Show List membership properties
Show List membership properties
Reason for the most recent unsubscribe on this list (e.g.,
message, bad_response, invalid_contact, manual, complaint, api (set by the Delete Contact endpoint), or a replied stop ... string when the contact texted a STOP keyword). null if the contact has never unsubscribed or has since resubscribed.ISO 8601 UTC timestamp of the most recent unsubscribe on this list.
null if the contact has never unsubscribed or has since resubscribed.Examples
curl -X GET "https://api.tracklysms.com/api/v2/contacts/%2B14155559876" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
from urllib.parse import quote
phone_number = "+14155559876"
encoded_phone = quote(phone_number, safe="")
response = requests.get(
f"https://api.tracklysms.com/api/v2/contacts/{encoded_phone}",
headers={"X-Api-Key": "trk_your_api_key_here"}
)
data = response.json()
print(f"Phone: {data['phone_number']}")
print(f"Carrier: {data['carrier']}")
print(f"Lists: {len(data['lists'])}")
for membership in data["lists"]:
print(f" {membership['list_number']} - Active: {membership['active']}")
const phoneNumber = "+14155559876";
const encodedPhone = encodeURIComponent(phoneNumber);
const response = await fetch(
`https://api.tracklysms.com/api/v2/contacts/${encodedPhone}`,
{
method: "GET",
headers: {
"X-Api-Key": "trk_your_api_key_here",
},
}
);
const data = await response.json();
console.log(`Phone: ${data.phone_number}`);
console.log(`Carrier: ${data.carrier}`);
console.log(`On ${data.lists.length} list(s)`);
{
"phone_number": "+14155559876",
"carrier": "T-Mobile",
"line_type": "mobile",
"timezone": "America/Los_Angeles",
"is_valid": true,
"country": "US",
"lists": [
{
"list_id": 42,
"list_number": "+18005551234",
"active": true,
"signup_date": "2025-03-15T14:30:00",
"unsub_reason": null,
"unsub_date": null,
"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",
"unsub_reason": "message",
"unsub_date": "2025-02-01T11:15:00",
"custom_fields": {},
"send_count": 5,
"click_count": 0
}
]
}
{
"error": "Invalid E.164 phone number format",
"code": "invalid_phone"
}
{
"error": "Contact not found",
"code": "not_found"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_phone | The phone number in the path is not a valid E.164 number. |
| 401 | invalid_credentials | Missing or invalid X-Api-Key header. |
| 403 | account_suspended | Your account is suspended. Resolve outstanding billing or contact support. |
| 404 | not_found | The contact does not exist or is not on any sending list owned by your account. |
| 500 | internal_error | An 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