v1
latestOpenAPI 3.1.02026-07-2671538.5 KBContacts
List contacts
Retrieve a paginated list of contacts. Optionally filter by email, phone number, or consent status.
Required scope: contacts_read
get/contacts
Query parameters
pageinteger
Page number (starts at 1).
per_pageinteger
Number of results per page.
emailstring email
Filter by exact email address.
phone_numberstring
Filter by exact phone number (E.164 format).
email_consent'subscribed' | 'unsubscribed' | 'never_subscribed' | 'suppressed' | 'compliance_suppressed'
Filter by email consent status. subscribed matches both explicit and implicit opt-in. suppressed matches merchant-suppressed contacts only; compliance_suppressed matches system/compliance-suppressed contacts.
sms_consent'subscribed' | 'unsubscribed' | 'never_subscribed' | 'single_opt_in' | 'pending'
Filter by SMS consent status.
Response
A paginated list of contacts.
Example response
{
"data": [
{
"id": "cus_a1b2c3d4e5f6g7h8",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane@example.com",
"email_consent": "subscribed",
"phone_number": "+15551234567",
"sms_consent": "subscribed",
"tags": [
"vip",
"repeat-buyer"
],
"custom_fields": {
"loyalty_tier": "gold",
"referral_code": "JANE2024"
},
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-03-20T14:22:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total_count": 142,
"total_pages": 6
}
}