API Data Formats & more

API General Considerations

Please review the general information provided here to learn more about the Constant Contact v2 API and the following topics:

RESTful API

The Constant Contact v2 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. Error messages are presented as an array of "error_code", "error_message" objects.

[
   {
       "error_key": "error_code",
       "error_message": "message"
   }
] 

SSL required

The Constant Contact API v2 requires the use of SSL with TLS v1.2 and AES encryption or better for all API calls. The leading URI for all API endpoints is https://api.constantcontact.com/v2/. You are not required to have an SSL certificate to make calls into the API. 

NOTES:

• As of September 30, 2018, we are ending support for TLS v1.0 and TLS v1.1 when establishing a secure connection to our system.
• As of November 21, 2014, we ended support for SSL v3.0 and the RC4 cipher suite in TLS v1.0 when establishing a secure connection to our system.

Parameter types

The Constant Contact API v2 has two types of parameters associated with API endpoints:

• Path parameters - REQUIRED - used to specify a particular resource 
• Query parameters - OPTIONAL* - used to specify additional information about a resource.

NOTE: The api_key query parameter is required for all API calls.

An API endpoint can have 0 or more path or query parameters associated with it. Path parameters are required when making a call to the API endpoint, or the call will return a 400 error message. Query parameters are optional, The path and query parameters available for each endpoint and method are provided in the API documentation pages in a table like this one:

Path parameters are identified in the Method & Endpoint by {}, as shown above for {listId}. 

URL encoding

We strongly recommend that you follow established best practices and URL encode all query parameter values. This will prevent anomalous behavior when reserved characters need to be included as part of a query parameter value. You can read this brief, well written Wikipedia article on Percent-encoding.

URI fragments not supported

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

Endpoint methods

The Constant Contact v2 API supports the following methods for use with the API endpoints. Each endpoint may support only a subset of available methods.

Read-only properties

Some of API object properties are read-only; if these properties are included in a PUT or POST call the API ignores them . Some of these properties are generated automatically when the record was created, Read only properties are identified in the JSON Structure definition table for each endpoint and method by a (Read Only) at the end of the Description field for the modified_date and last_run_date properties below:

Read Only tags are not shown in the documentation for GET methods, only PUT, POST, and PATCH.

Required properties

Some API object properties must be used when making a PUT or POST call, and they are identified as REQUIRED in the JSON Structure table description field, as shown above for the subject property.  A 400 error is thrown if a required property is not included in an API call.

NOTE: the api_key query parameter is REQUIRED for all API calls.

HTTP headers

Our API accepts the following header values:

Making PUT calls

PUT calls modify existing objects in the account. The Constant Contact API v2 does not support partial PUT calls, unless otherwise noted. This means when making a PUT call the entire object is updated with the property values included in the PUT; any properties (except Read Only properties) that had data previously but were not included in the PUT will be overwritten with a null value. 

Paginated output

In the response to GET calls that support the limit query parameter to define the number of entries listed per page of output, the next_limit parameter value at the top of the JSON response body is a link to use to retrieve the next page of output. See the Paginated Output topic for details. 

Date formats

Our 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).

The ISO-8601 standard format we use:

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

where:

YYYY = four-digit year
MM = two-digit month (01=January, etc.)
DD = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23) (am/pm NOT allowed)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
s = one or more digits representing a decimal fraction of a second
Z = UTC time zone designator

Date-time formats the API accepts and how they are resolved:

Unsupported date-time input formats:

• YYYYMMDD - 19991101
• YYYYMM - 199901
• YYYYWww – 1999W50
• HH:MM:SS.sss - 15:16:02.254
• THHMMSS.sss - T151602.254
• YYYYWwwD – 2014W361
• YYYYDDD - 2014136

User roles and endpoint privileges

In order to support user roles, the majority of API endpoints are configured so that only users with the appropriate privileges can access them. The privileges required to access each endpoint are shown in the description section for each method an endpoint supports. You can learn more about user roles in Constant Contact here.

In order to optimize the user experience of each user role in your integration, you should consider modifying the user interface to show only functionality available to each user. You can retrieve the list of API endpoint privileges for a specific user using the user privileges endpoint.