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, PATCH). 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.2 and AES encryption or better for all API calls. You do not need an SSL certificate to make calls into the API.
HTTP Methods
The V3 API supports the following 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, such as /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. |
PATCH | Make a PATCH request to only change a part of the resource. For example, to change the resource name . This method, unlike PUT , is not idempotent; successive identical PATCH requests may have different effects. |
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.
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 | The content-type must be unspecified when making calls to the activities/contacts\_file\_import bulk activity endpoint. |
|
empty | 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 and 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
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).