Contacts are central to everything a Constant Contact user can do using the product or the API. Customers are usually billed according to the number of active contacts they have in their account.
Contact Object and Subresources
The contact resource is composed of core properties and subresources. By default, contact resource request and response payloads only include core properties. To include subresources in response payloads use the include={subresource}
query parameter in each request. This streamlines the size of response payloads when retrieving collections of contacts. Learn more.
contact_id
values are formatted as UUIDs (Universally Unique IDentifier) format, 8-4-4-4-12 for a total of 36 characters (32 alphanumeric characters and four hyphens). The V2 format was string.Search for Contacts
You can search for contacts in a user’s account using the following criteria:
- include - use 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
,sms_channel
. - status - retrieve contacts with one or more of the following status:
all
,active
,deleted
,not_set
,pending_confirmation
,temp_hold
, andunsubscribed
. - exact email address
- list membership - retrieve all contacts that are members of one or more lists.
- tag ID - retrieve all contacts that are tagged with one or more specified tags (
tag_id
). - segment ID - retrieve all contacts to which a specified segment’s criteria applies. 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. - updated date - retrieve all contacts with properties updated after (
updated_after
) date or before (updated_before
) a specified date and time. To search for updated contacts within a date range, specify bothupdated_after
andupdated_before
dates. Accepts ISO-8601 formatted dates. - created date - retrieve all contacts created after (
created_after
) date or (created-before
) a specified date and time. To search for contacts created within a date range, specify bothcreated_after
andcreated_before
dates. Accepts ISO-8601 formatted dates. - optout date - retrieve all contacts that opt out after or before (
optout_after
,optout_before
) a specified date and time. Accepts ISO-8601 formatted dates. - SMS status - use the
sms_status
parameter to retrieve only those contacts that have a specified SMS status. Valid values includeall
,explicit
,unsubscribed
,pending_confirmation
, andnot_set
. This parameter accepts one or more comma separated values.
Custom Fields
The V3 API supports the same flexible custom_fields
naming rules as in the product UI. Custom fields are no longer required to use the restrictive custom_fieldn
naming format in order to be accessible through the API. Also, the V3 API is not limited in the number of custom_fields it can show for a contact.
custom_fields
are a subresource of the contact object. Use include=custom_fields
to include them in a response payload.Create New Contacts
There are different ways to create contacts with the V3 API:
-
Create new contacts one at a time by making a POST call to the
/contacts
endpoint. For more information, see Create a Contact. -
If a contact has given you explicit permission to send them emails, use the
/contacts/sign_up_form
endpoint to create a contact or update an existing contact based on their email address. This means you do not need to make a separate API call to check if the contact email address already exists in the user account. For more information, see Create or Update a Contact. -
Use one of the import contacts bulk activity endpoints to create up to 39,999 contacts in a single API call. For more information, see Add Many Contacts.
Delete Contacts
You can delete contacts one at time by making a DELETE call to the /contacts/contact_id
endpoint. Or delete 500 or more contacts using the delete contacts bulk activity endpoint.
Add and Remove Contacts from Lists
Add and remove contacts from lists using the list management bulk activity endpoints.
Get Contact Consent Counts
To gain insights about the current consent state of all contacts in your account, make a GET call to the contacts/counts
endpoint. Optionally, to include the total number of new subscribers in the results, specify new_subscribers
in the include
query parameter.
Get Contact SMS Engagement History
To get SMS engagement details for a contact, such as SMS consent and advertising frequency details, make a GET call to the /contacts/sms_engagement_history/{contact_id}
endpoint.