GET Contacts Collection
Use this method to return a collection of contacts. Use the query parameters to search for contacts that match specific contact properties and sub-resource properties as criteria. For example, you can search using the contact's email address, lists memberships, and by the date range that a contact was created or updated. Use the limit query parameter to limit the number of results returned per page. Use the include query parameter to include contact sub-resources in the response and include_count to include the total number of contacts that meet your specified search criteria.
By default, this method returns all contacts that are not deleted. Use the status query parameter with the value all to return all contacts including deleted contacts.
Query parameters
Use the status query parameter to search for contacts by status. This parameter accepts one or more comma separated values: all, active, deleted, not_set, pending_confirmation, temp_hold, and unsubscribed.
Use the email query parameter to search for a contact using a specific email address.
Use the lists query parameter to search for contacts that are members of one or more specified lists. Use a comma to separate multiple list_id values, up to a maximum of 25.
Use to get contacts that meet the segment criteria for a single specified segment_id. This query parameter can only be combined with the limit query parameter. When using the segment_id query parameter, the V3 API may return a 202 response code instead of a 200 response. The 202 response code indicates that your request has been accepted, but not fully completed. Retry sending your API request to return the completed results and a 200 response code.
Use to get contact details for up to 50 specified tags. Use a comma to separate each tag_id.
Use updated_after to search for contacts that have been updated after the date you specify. To search for updated contacts within a date range, specify both updated_after and updated_before dates. Accepts ISO-8601 formatted dates.
Use updated_before to search for contacts that have been updated before a specified date. To search for updated contacts within a date range, specify both updated_after and updated_before dates. Accepts ISO-8601 formatted dates.
Use created_after to search for contacts created after a specified date. To search for contacts created within a date range, specify both created_after and created_before dates. Accepts ISO-8601 formatted dates.
Use created_before to search for contacts created before a specified date. To search for contacts created within a date range, specify both created_after and created_before dates. Accepts ISO-8601 formatted dates.
Use optout_after to search for contacts that unsubscribed after a specified date.
Use optout_before to search for contacts that unsubscribed before a specified date.
Use include to specify which contact sub-resources to include in the response. Use a comma to separate multiple sub-resources. Valid values: custom_fields, list_memberships, taggings, notes,phone_numbers, street_addresses.
Use to get contacts by their SMS status. This parameter accepts one or more comma separated values: all, explicit, unsubscribed, pending_confirmation, not_set.
Set include_count=true to include the total number of contacts (contacts_count) that meet all search criteria in the response body.
Specifies the number of results displayed per page of output in the response, from 1 - 500, default = 50.
Response
Request successful
Example response
{
"contacts": [
{
"contact_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
"email_address": {
"address": "dlang@example.com",
"permission_to_send": "implicit",
"created_at": "2016-03-03T10:53:04-05:00",
"updated_at": "2016-03-03T10:56:29-05:00",
"opt_in_source": "Contact",
"opt_in_date": "2016-01-23T13:48:44.108Z",
"opt_out_source": "Contact",
"opt_out_date": "2016-01-23T13:48:44.108Z",
"opt_out_reason": "I am no longer interested in this service.",
"confirm_status": "confirmed"
},
"first_name": "Debora",
"last_name": "Lang",
"job_title": "Musician",
"company_name": "Acme Corp.",
"birthday_month": 11,
"birthday_day": 24,
"anniversary": "2006-11-15",
"update_source": "Contact",
"create_source": "Account",
"created_at": "2016-01-23T13:48:44.108Z",
"updated_at": "2016-01-23T13:48:44.108Z",
"deleted_at": "2016-07-08",
"custom_fields": [
{
"custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
"value": "Tesla S 2017",
"choice_ids": [
"000001"
]
}
],
"phone_numbers": [
{
"phone_number_id": "6eec28a6-1cf5-11ea-859f-fa163e56c9b0",
"phone_number": "+1-555-555-5555",
"kind": "home",
"created_at": "2016-03-03T10:53:04-05:00",
"updated_at": "2016-03-03T10:56:29-05:00",
"update_source": "Account",
"create_source": "Account"
}
],
"street_addresses": [
{
"street_address_id": "977a9a2e-3e00-11ea-804b-fa163e56c9b0",
"kind": "home",
"street": "123 Kashmir Valley Road",
"city": "Chicago",
"state": "Illinois",
"postal_code": "60609",
"country": "United States",
"created_at": "2016-03-03T10:53:04-05:00",
"updated_at": "2016-03-03T10:56:29-05:00"
}
],
"list_memberships": [
"07936f78-662a-11eb-af0a-fa163e56c9b0"
],
"taggings": [
"e7ddac60-51da-11eb-b3a4-fa163e6b01c1"
],
"notes": [
{
"note_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2021-05-12T13:48:44.108Z",
"content": "This contact resubscribed on 2021-05-12."
}
],
"sms_channel": {
"sms_channel_id": "3fa85f64-5712-6245-b3fc-2c963f66bfc6",
"sms_address": "7815551212",
"dial_code": "1",
"country_code": "US",
"update_source": "Contact",
"create_source": "Account",
"sms_channel_consents": [
{
"sms_consent_permission": "explicit",
"consent_type": "promotional_sms",
"opt_in_date": "2016-01-23T13:48:44.108Z",
"opt_out_date": "2016-01-23T13:48:44.108Z",
"advertised_frequency": "1",
"advertised_interval": "monthly",
"created_at": "2016-01-23T13:48:44.108Z",
"updated_at": "2016-01-23T13:48:44.108Z"
}
]
}
}
],
"contacts_count": 3249,
"_links": {
"next": {
"href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}