Overview of V3 contacts functionality

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.

New contact_id Format in V3
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:

  • by status - retrieve contacts with one or more of the following status: active, deleted, not_set, pending_confirmation, temp_hold, and unsubscribed.
  • by exact email address
  • updated_after - retrieve only contacts who properties have been updated after a given date/time.
  • by list membership - retrieve all contacts that are members of one or more lists

Try it!

Custom Fields

The V3 API supports the same flexible custom_field 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.

Learn more.

Create New Contacts

There are several different ways to create contacts with the V3 API:

  • Create new contacts one by one 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 by one by making a DELETE call to the /contacts/contact_id endpoint. Or delete 500 or more contacts using the delete contacts bulk activity endpoint.

Learn more.

Add and Remove Contacts from Lists

Add and remove contacts from lists using the list management bulk activity endpoints.

Learn more.