Describes V3 API technical specs including payload and data formats, headers, and more.

The Constant Contact V3 API is designed for developers, engineers, or anyone else who’s comfortable creating custom-coded solutions and integrating with RESTful APIs.

RESTful API

The Constant Contact V3 API employs a REST-based resource structure with JSON support for all payloads. This includes full support for JSON schema validation and enhanced error messages in a predictable JSON format.

Resources

The API resources are nouns (contacts, contact_lists, custom_fields, etc.) that you take actions on using supported HTTP verbs (POST, PUT, GET, DELETE). The V3 API schema showing all resources and subresources is available in YAML format for download here.

Each resource is divided into a resource/{resource_id} format. For example, to retrieve information about contacts, make a GET request to https://api.cc.email/v3/contacts. To access an individual contact, make a GET request to https://api.cc.email/v3/contacts/{contact_id}.

Resource Identifiers

The V3 API uses the universally unique identifier (UUID) format for resource IDs, 32 hexadecimal (base 16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 alphanumeric characters and four hyphens). Learn more.

Authentication

The V3 API only supports the OAuth2.0 authentication method, including the client (two-legged) and server (three-legged) authorization flows. The server flow uses refresh tokens. Learn more.

SSL

The Constant Contact V3 API requires the use of SSL with TLS v1.1 and AES encryption or better for all API calls. You do not need an SSL certificate to make calls into the API.

The leading URI for all API endpoints is https://api.cc.email/v3/.

HTTP Methods

The V3 API supports 4 HTTP methods:

METHOD Description
GET Make a GET request to retrieve data. GET requests are idempotent - they do not cause an update or change to your data.
POST Use a POST request to create new resources. For example, make a POST request to a collection endpoint (like /contacts) where the JSON request body creates a new object, in this a new contact.
PUT Use a PUT request to create or update a resource, for example when syncing contact/subscriber data. PUT requests are considered idempotent, issuing the same PUT request multiple times on the same resource will not alter the resource beyond the original PUT request.
DELETE Make a DELETE request to remove a resource such as a contact list or custom field.
Deleted contacts are treated differently than other resources, learn more.

The API Reference shows the methods available for each resource.

JSON

The Constant Contact V3 API only accepts JSON-formatted request payloads, and all API responses are JSON.

Parameters

There are four parameter categories used in the V3 API: path, query, request body, and response body.

Path Parameters

An API URL includes resource names and unique identifiers. Resource names are immutable, but resource identifiers are required, so you need to replace them with real values from your CTCT account. Here’s an example of how path parameters are expressed in the code samples:

https://api.cc.email/v3/contact_lists/{list_id}

Replace the {list_id} path parameter with real data, and it looks like this:

https://api.cc.email/v3/contact_lists/04545ea0-451c-45e8-b0ca-d4ae45450c45

See Resource Identifiers for information on the resource ID format.

Query Parameters

Query parameters are always optional. They are used for filtering, pagination, and partial responses. The format for query string parameters is the full resource URL followed by a question mark and the optional parameters, each separated by an ampersand (&):

https://api.cc.email/v3/contacts?status=unsubscribed&updated_after=2018-3-31&include=list_memberships&limit=50&include_count=false

Filtering Responses

The API Reference shows you the filters available for GET calls to each resource collection, and how to include it in your URL query string. The above example uses the status and updated_after query parameters to filter the contacts returned in the response.

When multiple filters are included in a request, we only return resources that match all filters.

Paginated Output

Paginate your API requests to limit response results and make them easier to work with by using the limit query parameter. Each page of the response includes the link to retrieve the next page of results, as shown here:

"_links": {
    "next": {
      "href": "/v3/contacts?cursor=bGltaXQ9NSZuZXh0PTImc3RhdHVzJTVCJTVEPWFsbA=="

Partial Response - Contact Subresources

Use the include query parameter to cut down on data transfers by limiting which contact subresources the API returns. For example, you may not need the full details for a contact, and you can instead pass a comma-separated list of specific fields you want to include. For example, the following URL uses the include query parameter to only include the custom_fields and list_membership subresources in the response:

https://api.cc.email/v3/contacts?include=custom_fields,list_memberships

Request Body

PUT and POST requests require a request body in JSON format. The API Reference shows all the available request parameters for each endpoint, and which ones are required fields. A comprehensive Body Schema is provided for each PUT and POST method in the API Reference.

Response Body

Responses from the v3 API include HTTP headers and an optional JSON-formatted body.

DELETE requests return only headers without a JSON body.

A comprehensive Response Schema is provided for each endpoint/method in the API Reference.

HTTP Headers

The V3 API accepts the following header values:

Header Accepted Values Comment
Authorization Bearer {access_token} The access_token generated during the grant access leg of the OAuth2 flow
Accept application/json  
Content-Type application/json  
  */*  
  unspecified content-type must be unspecified when making calls to the activities/contacts_file_import bulk activity endpoint.
  empty NOTE: Many clients replace an empty value with a default value of html/text, which the API does not accept.

Read-only Properties

Some API object properties are read-only; any read-only properties included in a PUT or POST call are ignored by the API. Read only properties are identified in the Body and Response schema for each endpoint and method in the interactive API Reference.

Code Examples

We provide code examples in Java, PHP, and cURL in the API Docs to illustrate the step-by-step instructions we provide for API use case examples. Check out some examples here.

API Definition and Schema

The v3 API schema showing all resources and subresources is available in YAML format for download here.

Errors

API Errors are identified using standard HTTP response codes and JSON-formatted error message array:

[
  {
    "error_key": "contacts.api.not_found",
    "error_message": "contact_id is in an invalid format."
  }
]

URL Encoding

We strongly recommend that you follow established best practices and URL encode all query parameter values in order to prevent anomalous behavior when reserved characters are included as part of a query parameter value. Read this brief, well-written Wikipedia article on Percent-encoding for more information.

URI fragments not supported

The API does not currently support the use of URI fragments.

Date Format

V3 API accepts dates formatted in the ISO-8601 standard. We convert all dates sent to us with local timezone offsets to UTC, and we return them in UTC (no local timezone offset).

ISO-8601 standard format:

YYYY-MM-DDThh:mm:ss.sZ –> 2013-03-29T19:20:30.00Z

Learn more.

API Status and Support

The Constant Contact V3 API has a 99.9% uptime. If we do have downtime, we’ll tweet information from @ConstantContact or @CTCT_API.

Have questions? Email us at Webservices@constantcontact.com and we’ll help you figure it out (generates a support case).