Working with Contacts

Here we provide you with DO's and DON'Ts on using the Contacts endpoints so that you can build a great integration that provides your users a great experience.

Contacts Do's and Don'ts

The following best practices are intended to give your users the best experience possible, and make your integration as efficient as possible. 

Creating a new contact

This process uses 2 API calls to add a contact to Constant Contact, one to determine if it already exists, and one to add it. It is fine to use this process if you are adding a fairly small number of contacts. Keep in mind that API keys have a limit on the number of API calls that can be made per day, and per second. See API Keys for info. If you are adding a large number of contacts, it's best to use the batch import methods described below. 

The action_by query parameter tells the system who initiated an action, the contact or the account owner. Whenever a contact subscribes to a contact list by entering their email address and clicking Subscribe me, action_by=ACTION_BY_VISITOR.

DO Use this workflow to create a new contact and prevent receiving a 409 response for trying to create a contact that already exists.

1. Verify whether or not the contact already exists in the user's contact collection:
   Search for the contact in the user's contact collection by email address:
   
   GET: https://api.constantcontact.com/v2/contacts?email=<new_contact@email.com>
   
   
2. If the contact does not exist (the call returns an empty results set), then create it. 
3. If the new contact has subscribed themselves to a mailing list using an online sign up form, for example, then the POST call to the Contact collection endpoint must include the query parameter/value action_by=ACTION_BY_VISITOR. See Contact Status for more information.

New contacts and autoresponder/confirm opt-in messages

A new contact is sent an auto-responder welcome email when the POST call to the contacts collection includes the query parameter action_by=ACTION_BY_VISITOR. If the contact is added with action_by=ACTION_BY_OWNER, a welcome message is not sent. Additionally, if Confirmed Opt-in is enabled for the account, any contacts added with action_by=ACTION_BY_VISITOR must confirm their subscription. The Confirmed Opt-in setting is available in the product UI, and not via the API.

Updating contacts

Updating small numbers of contacts

This process uses 2 API calls to update a contact, one to get the current contact properties, and one to put the updated properties. It is fine to use this process if you are updating a fairly small number of contacts. Keep in mind that API keys have limits on the number of calls that can be made per day, and per second. See API Keys for info. If you are updating a large number of contacts, it's best to use the batch import methods. 

HOW Make a PUT call to the Individual Contact endpoint.

DO Make a GET call to retrieve all the properties for a contact prior to updating it. All updates (PUTs) are full replacements of the contact properties. That means you need to include the original content that is not changing, plus the new and changed content in the PUT. Otherwise, all properties not specified in the PUT will be overwritten with a null set.

If you are have a large number of contacts that you need to compare and update, see Updating many contacts efficiently.

Adding or updating large numbers of contacts efficiently

The bulk activity endpoints allow you to add or update up to 20,000 contacts by making 1 or 2 API calls.

DO Add and Update up to 20,000 contacts with a single API call

The process described here imports all contacts in your local application or database to Constant Contact, regardless of whether they are:

• a new contact
• an existing contact whose information has changed locally
• an existing contact whose information is unchanged

This single-step process does not require you to compare contact data in Constant Contact with your local data. However, if you are making updates to an existing contact list, it assumes that your local data is being synced with Constant Contact data on a regular basis. This is important because this method will overwrite any preference changes made by a contact in the Constant Contact data, such as list subscriptions, that are not recorded in the local data. For example, if a contact removed themselves for the "Weekly Specials" campaign sent to list_id=2, and the bulk import/update call specifies adding all the contacts to lists 2, 3, and 4, that subscriber will now be resubscribed to list_id=2. This is likely to raise the ire of at least some of these contacts.

DON'T update an existing list without having synced the local data with Constant Contact.

Do This is the best way to populate a new list.

1. Collect the contacts you are looking to import from your local application or database.  Make sure to then format these contacts into one of the supported file formats.
2. Import the contacts by sending them to Constant Contact in the multipart batch import request.

When executed, all contacts are imported into Constant Contact:

• Any new contacts are added to the appropriate list(s).
• Any existing contacts whose information has changed locally is updated in Constant Contact.
• All existing contacts whose data was unchanged locally, remain unchanged in Constant Contact.

DO Add and Update a maximum of 20,000 contacts using 2 API calls

This process updates only new contacts or existing contacts whose information has changed using only 2 API calls, one to export the contacts from Constant Contact, and one to import them back in.

1. Export all contacts from Constant Contact using the Export contacts bulk activity endpoint.
2. Diff the exported contact data with the data in the local application. Create an import file with only the new or updated contacts.
3. Import the contacts by sending them to Constant Contact in the multipart bulk import request.

DON'T Perform brute force list updates.

A brute force update occurs when an integration first removes all contacts from an existing list using the Clear Contacts bulk activity endpoint. Then, it immediatlely repopulates the list using the Import Contacts (JSON or Multipart) bulk activity endpoint with the contact data stored on in the local CRM or other contact/customer manangement application. Wiping out a list and then adding local contact data that has not been synced with Constant Contact to the now empty list will ignore any preference changes that a contact made to their profile. You risk adding contacts to a list that they have already unsubscribed from, something that should be avoided at all times.

Contact status

This table summarizes the possible status values for a contact.

Delete vs Remove a contact from all lists

Deleting a contact is very different from removing a contact from all lists.

Removing contacts from all lists

A contact that has been removed from all contact lists by the account owner has a status=REMOVED. To remove a contact from all lists, update the contact with an empty lists array. The contact can be added back to a list at anytime. 

DELETE/OPTOUT a contact

Deleting a contact using the DELETE Contact method changes their status to OPTOUT, placing them on the Unsubscribed list; the account owner cannot add them to any of their contact lists and cannot contact them. See Opting Contacts Back in to learn how a contact can change their status from OPTOUT to ACTIVE.

Opting contacts back in

All contacts with status=OPTOUT have unsubscribed from all contact lists, and are on the Unsubscribed list. Contacts on the Unsubscribed list cannot be subscribed to any list by a Constant Contact account owner (action_by=ACTION_BY_OWNER), EVEN IF the account owner unsubscribed the contact (accidentally or purposefully). The contact must re-subscribe themselves to a contact list in order to be removed from the Unsubscribed list.

When an existing unsubscribed contact subscribes to a contact list, the PUT call that updates their record must include the query parameter action_by=ACTION_BY_VISITOR. Also, they must be added to a contact list when adding them to the contact collection. The action_by parameter defines who initiated the action of adding the contact.

It is a violation of US and Canadian anti-spam laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

Syncing contacts

Sync based on modified_since

Use the modified_since query parameter to streamline contact syncing betweeen Constant Contact and other applications. The modified_since parameter allows you to sync only the contacts that have been modified since the last contact sync activity by specifying the date and time of the last sync. modified_since is updated to reflect when any of the following contact properties are modified in the API or the product UI:

Sync using tracking activities

You can use the contacts tracking API to sync contacts based on their activities, such as opting out, unsubscribing, or clicking links in email campaigns using the created_since query parameter. For example, you may want to sync all contacts who have unsubscribed from a newsletter since the beginning of the quarter. 

Adding contacts to lists

DO Because we know our customers rate this feature highly, we stongly encourage all Constant Contact integrations allow users to upload contacts to a contact list of the user's choosing. For an even better user experience, allow users to create a new contact list to add contacts to. It may seem like a small thing, but Constant Contact users depend on being able to create lists to segment their contacts.