The Constant Contact V3 API is a REST-ful API that provides a consistent developer experience across all services and endpoints, improved security, performance, reliability, and mobile-friendly request payloads.
The following lists some of the features and enhancements that are available in the V3 API that are NOT available in the V2 API. Click to expand a section of interest to view related features and enhancements.
Contacts
Simplified and flexible custom fields management
You no longer need to recreate a custom field to rename the field. The V3 API now supports renaming custom fields. The V3 API now supports up to 100 custom fields per account. This allows you to store even more personal data about a contact. Having more personal data from which to choose, provides you with greater flexibility when inserting personalized content in an email campaign.Learn more: Custom Fields Overview
Try it! POST Custom Fields
Advanced contact filtering options
The V3 API provides more contact search options, including searching by:
- 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 the opt-out before or after (
optout_before
andoptout_after
) a specified date and time. Accepts ISO-8601 formatted dates. - SMS status - retrieve all contacts that have a specified status. Valid values include:
all
,explicit
,unsubscribed
,pending_confirmation
,not_set
). - sms_channel - to retrieve contact SMS channel and consent details, use
sms_channel
in theinclude
query parameter.
Try it! GET Contacts Collection
Learn more: Contacts Overview
Get SMS channel and consent details
To return SMS channel and consent details in the response, make a GET call to the following endpoints and set the include
query parameter to sms_channel
:
- GET
/contacts
- GET
/contacts/{contact_id}
Try it! GET Contacts Collection
Learn more: Contacts Overview
Segmentation
Use segmentation to improve campaign results, reduce the number of contact lists to maintain, and increase contact engagement. Segments are used to target a subset of contacts based on contact attributes that you specify as criteria. Criteria can include attributes related to tracking activities, contact details, list memberships, and tags. Unlike static lists, segments are dynamic.
Learn more: Segments Overview
Try it! POST a Segment
Autoresponder improvements
V3 API now supports the birthday and anniversary properties in the contact request payload. This means you can take advantage of autoresponder messages to send birthday and anniversary email campaigns.Learn more: Autoresponder and Confirmed Opt-in Emails
Contact tags
Tags let you easily categorize and group contacts for the purpose of sending targeted messages without having to add contacts to new contact lists. For example, you can categorize tags based on the information you collect from surveys, membership registration, and sign-up forms.The new contact tagging activity endpoints allow you to manage a large number of tags and contact taggings.
Learn more: Tags Overview
Try it! POST a Tag
Get faster API responses by using contact subresources to reduce the size of the response payload.
New contact query options allow you to get more targeted contact results in the response payload and get faster API responses. - Use the `segment_id` query parameter to get a list of contacts that currently meet the criteria for the specified segment ID. Use the results to verify the criteria returns the results you expect. - Use the `tags` query parameter to get a list of all contacts to which any of the tag(s) apply. - Use the `include_count` parameter to include the total number of contacts in the results. - Use the `include` query parameter to filter contacts using the following sub-resource options: - custom_fields - taggings - Notes - Phone_numbers - Street_addressesLearn more: Contacts Overview
Try it! Get Contacts Collection
Improved contact details included during export
When exporting contact details to a file, you can now use the request body fields array to add contact IDs to the CSV response.Learn more: Export Contacts to a CSV File
Try it! Export Contacts to a File
Quickly delete multiple custom fields from an account
Make a POST call to the new/activities/custom_fields_delete
endpoint to create an asynchronous
activity used to remove up to 100 custom fields from contacts and deletes the custom fields from an account.
Try it! Delete Custom Fields Activity
Quickly create or update existing contacts
V3 API provides a new endpoint that allows you to create a new contact or update an existing contact based on an email address. If the email address you provide is new, this method creates a new contact. If the email address belongs to an existing contact, it updates the contact's details. This eliminates the need to make a separate API call to check if the contact already exists in the account.Learn more: Create or Update a Contact Using a Single Method
Try it! Create or Update a Contact
More contact list query options
The following new query parameters are available when making a GET call to the/contacts_lists
endpoint:
name
: Use to enter the full name of a contact list to get details about that list.status
: Use to return only list details for lists that have a specific status. Options include,all
,active
,deleted.
Learn more: Contacts Lists Overview
Try it! Get List Collection
Get the total contact consent counts for each consent state
Getting contact insights helps you interpret the bigger picture of contact engagement and list growth. To get the current contact consent state for all contacts in your account, make a GET call to thecontacts/counts
endpoint to get the total contact consent counts for each consent state; explicit
, implicit
, pending
, and unsubscribed
.
Optionally, to include the total number of new subscribers in the results, specify new_subscribers
in the include
query parameter.
Learn more: Get Contact Consent Counts
Try it! GET /contacts/counts
Quickly delete multiple contact lists
Make a POST call to the/activities/list_delete
endpoint and in the request body, specify up to one hundred
contact lists (list_id
) to delete from an account.
For example:
"list_ids": [
"08936f78-662a-11eb-af0a-fa163e56c9b0","205947ac-3f74-11ed-a450-074013d9081f"
]
Try it! Get List Collection
Email Campaigns
Support for custom code emails
The V3 API now supports a new type of custom code email (format_type 5). New custom code emails support:- Sending emails to segments.
- Using personalization tags.
- Adding your CSS declarations in a style tag in addition to supporting inline CSS.
Learn more: Create an Email Campaign
Try it! POST (Create) a New Email Campaign
Resend a campaign activity to Non-openers
To avoid over-sending to contacts and having them opted out, use the new Resend to Non-openers endpoint to target only contacts that did not open or were not sent the initial email campaign activity.Learn more: POST (Schedule) a Resend to Non-openers Email Campaign Activity
Try it! POST a Resend to Non-openers Campaign Activity
Reporting
Get email campaign statistics for campaign and campaign activities
You can now get statistics about your email campaigns at both the campaign and campaign activity levels. This allows you to gather important campaign information such as the campaign's success, how often contacts interacted with it, and the type of devices used to interact with it.Learn more: Email Reporting Overview
Try it! GET an Email Campaign Stats Report
Try it! GET an Email Campaign Activity Stats Report
Migration
Easy data migration path from V2 to V3.
Unlike the V2 API, which uses sequence identifiers for resources, the V3 API uses Universally Unique Identifier (UUID) format for resource identifiers to your local user's data. The UUID is used when making calls to the V3 API to allow your users to use their existing account data with the V3 API version of your application with minimal, if any, disruption or action on their part.
Learn more: Data Migration Overview
Support
The V2 API is being deprecated. The V3 API provides a higher level of support and actively addresses issues, requests, and feedback pertaining to the V3 API functionality.
Performance and Scalability
Enhanced performance, stability, scalability
The V3 API is cloud-hosted for enhanced stability, performance, and scalability.
Payload optimization
To optimize the amount of data sent, you choose which additional fields to include. You have more control over the size and complexity of payloads sent back and forth on API calls. Testing has shown a 40% decrease in the size of contacts payloads when subresources are not included.
Security
OAuth2
In compliance with the current industry standards for secure public APIs, the V3 API uses the most current OAuth2 security methods. This includes:- Using encrypted JSON Access Tokens (JWT)
- Short-lived access tokens
- CORS support
- PKCE support for public OAuth2 clients
Learn more: OAuth2 Overview
Oauth2 supports the Device Flow. Use this flow if your application runs on a device that is input constrained. For example, a command line application that cannot provide a web browser to users. Learn more: Device Flow.
Scopes
Scopes allow you to limit your application's access to user data and to the V3 API endpoints. Scopes also allow Constant Contact to communicate to the users of your application what type of data and functionality your application is requesting.</details>
--- ## Technology Partners
Webhooks
The V3 API now supports partner webhooks. As a partner, you can choose to subscribe to billing event notifications from Constant Contact. Partner webhooks eliminate the need for your integration to poll partner API methods for billing changes. Instead, after you subscribe your application to partner webhooks, you can start receiving automatic billing and account notifications by making a single API request.
Filter on managed or unmanaged client accounts
When making aGET
call to the /partner/accounts
endpoint, you can now choose to filter your results to return all managed or all un-managed client accounts using the new account_type
parameter and specify either managed
or unmanaged
.
Make V3 API calls on behalf of your managed client accounts
Many technology partners do all or some of the marketing on behalf of their managed client accounts. As a technology partner, you can now make V3 API calls on behalf of your managed client accounts. This allows you greater flexibility for performing marketing tasks and allows your managed client accounts to focus on their local clients and businesses.
Single Sign On
Technology partners can now use Constant Contact's Single Sign On (SSO) solution to allow their customers to access their integrated Constant Contact account without having to sign in with a separate username and password. SSO uses SAML 2.0 standards. Learn More about using SSO.
[titlepage]: titlepage [tocpage]: tocpage [index]: index.html [v3_features]: v3_features.html [v3_technical_overview]: v3_technical_overview.html [developer_portal]: developer_portal.html [getting_started]: getting_started.html [rate_limits]: rate_limits.html [migration_overview]: migration_overview.html [v3_v2_contact_deltas]: v3_v2_contact_deltas.html [v3_v2_list_deltas]: v3_v2_list_deltas.html [v3_v2_email_campaign_deltas]: v3_v2_email_campaign_deltas.html [apps_create]: apps_create.html [auth_update_apps]: auth_update_apps.html [auth_overview]: auth_overview.html [server_flow]: server_flow.html [pkce_flow]: pkce_flow.html [device_flow]: device_flow.html [client_flow]: client_flow.html [scopes]: scopes.html [user_privileges]: user_privileges.html [account_services_overview]: account_services_overview.html [account_details_get]: account_details_get.html [account_details_put]: account_details_put.html [account_address_get]: account_address_get.html [account_address_put]: account_address_put.html [account_post_emails]: account_post_emails.html [account_get_emails]: account_get_emails.html [account_get_privileges]: account_get_privileges.html [bulk_activities]: bulk_activities.html [activity_status]: activity_status.html [import_contacts]: import_contacts.html [export_contacts]: export_contacts.html [deleting_contacts]: deleting_contacts.html [add_list_membership]: add_list_membership.html [remove_list_membership]: remove_list_membership.html [delete_lists]: delete_lists.html [delete_custom_fields_activity]: delete_custom_fields_activity.html [add_tagging_activity]: add_tagging_activity.html [remove_tagging_activity]: remove_tagging_activity.html [delete_tagging_activity]: delete_tagging_activity.html [contacts_overview]: contacts_overview.html [contacts_subresources]: contacts_subresources.html [contacts_create]: contacts_create.html [contacts_create_or_update]: contacts_create_or_update.html [contacts_counts]: contacts_counts.html [contacts_autoresponder]: contacts_autoresponder.html [contacts_delete]: contacts_delete.html [contacts_sync]: contacts_sync.html [contacts_re-subscribe]: contacts_re-subscribe.html [contacts_sms_engagement]: contacts_sms_engagement.html [custom_fields]: custom_fields.html [create_custom_fields]: create_custom_fields.html [get_custom_fields]: get_custom_fields.html [delete_custom_fields]: delete_custom_fields.html [add_custom_field_data]: add_custom_field_data.html [lists_overview]: lists_overview.html [lists_get_single]: lists_get_single.html [lists_get_all]: lists_get_all.html [lists_post]: lists_post.html [lists_put]: lists_put.html [lists_delete]: lists_delete.html [tags_overview]: tags_overview.html [tags_get_single]: tags_get_single.html [tags_get]: tags_get.html [tags_create]: tags_create.html [tags_update]: tags_update.html [tags_delete]: tags_delete.html [contact_reporting_overview]: contact_reporting_overview.html [activities_summary]: activities_summary.html [activity_details]: activity_details.html [open_and_click_rates]: open_and_click_rates.html [email_campaigns_overview]: email_campaigns_overview.html [email_campaign_create]: email_campaign_create.html [design_code_emails]: design_code_emails.html [email_campaigns_collection]: email_campaigns_collection.html [email_campaign_id]: email_campaign_id.html [email_campaigns_activity_id]: email_campaigns_activity_id.html [email_campaign_activity_update]: email_campaign_activity_update.html [email_campaign_create_schedule]: email_campaign_create_schedule.html [email_campaigns_activity_get_schedules]: email_campaigns_activity_get_schedules.html [email_campaign_activity_delete_schedule]: email_campaign_activity_delete_schedule.html [email_campaign_activity_preview]: email_campaign_activity_preview.html [email_campaign_activity_test_send]: email_campaign_activity_test_send.html [email_campaigns_rename]: email_campaigns_rename.html [email_campaigns_sends_history]: email_campaigns_sends_history.html [email_campaigns_delete]: email_campaigns_delete.html [email_campaigns_resend_non_openers_post]: email_campaigns_resend_non_openers_post.html [email_campaigns_resend_non_openers_get]: email_campaigns_resend_non_openers_get.html [email_campaigns_resend_non_openers_delete]: email_campaigns_resend_non_openers_delete.html [email_campaigns_ab_test_overview]: email_campaigns_ab_test_overview.html [email_campaigns_ab_test_get]: email_campaigns_ab_test_get.html [email_campaigns_ab_test_post]: email_campaigns_ab_test_post.html [email_campaigns_ab_test_delete]: email_campaigns_ab_test_delete.html [email_reporting_overview]: email_reporting_overview.html [email_summary_sends_report]: email_summary_sends_report.html [email_summary_opens_report]: email_summary_opens_report.html [email_summary_unique_opens_report]: email_summary_unique_opens_report.html [email_summary_clicks_report]: email_summary_clicks_report.html [email_summary_non_opens_report]: email_summary_non_opens_report.html [email_summary_forwards_report]: email_summary_forwards_report.html [email_summary_optouts_report]: email_summary_optouts_report.html [email_links_report]: email_links_report.html [email_summary_bounces_report]: email_summary_bounces_report.html [email_campaign_stats_report]: email_campaign_stats_report.html [email_campaign_activities_stats_report]: email_campaign_activities_stats_report.html [email_bulk_campaign_summary_report]: email_bulk_campaign_summary_report.html [segments_overview]: segments_overview.html [segment_create]: segment_create.html [segment_get_all]: segment_get_all.html [segment_get]: segment_get.html [segment_delete]: segment_delete.html [segment_update]: segment_update.html [segment_rename]: segment_rename.html [lp_reports_overview]: lp_reports_overview.html [lp_reports_unique_contact_clicks]: lp_reports_unique_contact_clicks.html [lp_reports_contact_opens]: lp_reports_contact_opens.html [lp_reports_unique_contact_opens]: lp_reports_unique_contact_opens.html [lp_reports_unique_contact_adds]: lp_reports_unique_contact_adds.html [lp_reports_unique_contact_sms_optins]: lp_reports_unique_contact_sms_optins.html [lp_reports_unique_contact_updates]: lp_reports_unique_contact_updates.html [partners_overview]: partners_overview.html [partners_dev_accts]: partners_dev_accts.html [partners_reg_creds]: partners_reg_creds.html [partners_auth]: partners_auth.html [partner_sso_config]: partner_sso_config.html [partners_accts_create]: partners_accts_create.html [partners_accts_get]: partners_accts_get.html [partners_plans_get]: partners_plans_get.html [partners_plans_update]: partners_plans_update.html [partners_plans_cancel]: partners_plans_cancel.html [partners_master_token]: partners_master_token.html [partner_webhook_overview]: partner_webhook_overview.html [webhook_single]: webhook_single.html [webhook_collection]: webhook_collection.html [webhook_put]: webhook_put.html [webhook_delete]: webhook_delete.html [webhooks_post]: webhooks_post.html [webhook_authenticity]: webhook_authenticity.html [glossary_responses]: glossary_responses.html [v3api_schema]: v3api_schema.html [titlepage]: titlepage [tocpage]: tocpage [titlepage]: titlepage [tocpage]: tocpage [faqs]: faqs.html [faqs_migrate]: faqs_migrate.html [faqs_manage_applications]: faqs_manage_applications.html [faqs_contacts]: faqs_contacts.html [mydoc_hyperlinks.html#automatedlinks]: mydoc_hyperlinks.html#automatedlinks [mydoc_hyperlinks.html#bookmarklinks]: mydoc_hyperlinks.html#bookmarklinks [mydoc_pages.html#someIdTag]: mydoc_pages.html#someIdTag [developer_portal.html#api_reference]: developer_portal.html#api_reference [developer_portal.html#my-applications]: developer_portal.html#my-applications [import_contacts.html#importing-contacts-from-a-csv-file]: import_contacts.html#importing-contacts-from-a-csv-file [news]: news [mydoc_introduction]: mydoc_introduction.html [p1_landing_page]: p1_landing_page.html [p2_landing_page]: p2_landing_page.html