To get started using the Constant Contact V3 API, complete the steps that follow.
STEP 1: Sign up
A V3 Constant Contact developer account allows you to create and manage applications in our V3 API ecosystem. When you sign up, a trial Constant Contact account is created that you can use for developing and testing your application integration. In order to use the V3 API, you also need to call into an account that has granted access to the application you are building.
To sign up for a new Constant Contact developer account:
- Open the V3 API Developer Portal .
- Under the My Applications tab, click Sign up.
- Provide the following required account information:
- Password
- First Name
- Last Name
- Organization Name
- Phone Number
- Click Get Started.
STEP 2: Register Your First Application
After logging in to the V3 Developer Portal using your new developer account, create, register, and manage your Constant Contact V3 API integrations (applications).
- Click New Application.
- In the New Application dialog box, enter the name to use to identify your application to Constant Contact users. This is the name that will display when Constant Contact users are prompted to grant access to your application.
- Applications that integrate with Constant Contact using the V3 API, must use the OAuth2 authorization protocol to securely authenticate a Constant Contact user account, and to be granted access to that user’s data. For details about choosing an OAuth2 flow, see OAuth2 Overview.
Choose the OAuth2 setting this application will use to authenticate.
- Authorization Code Flow and Implicit Flow
- Proof Key for Code Exchange (PKCE) Flow
- Device Authorization Flow
- Choose which refresh token method to use. Use refresh tokens to extend the lifespan of an access token by exchanging it for a new access and refresh token. This eliminates having to request that users log back in to re-authenticate their Constant Contact accounts or reauthorize your application to access their data.
For details about choosing which refresh method to use, see OAuth2 Overview.
- Rotating Refresh tokens are recommended for use with most applications because they are most secure.
- Long Lived Refresh Tokens
- Click Create, the My Applications page displays and lists your newly registered application under Applications.
- To get the API Key (also referred to as a client ID) required for your application to make V3 API calls, click edit next to the new application’s name and the API Key displays in the default Details view.
- If the authentication method you use requires a client secret to use to authenticate requests made to the Authorization Server, click Generate Client Secret. Copy the secret to a secure location. The secret only appears once, when you first request to generate it. Regenerating the secret would require you to update your application.
- Click Save to save any changes to your application.
You can return to the applications details page at anytime to get the API key, add or change details, and to generate a client_secret
when you’re ready to start developing or making test calls using an HTTP client such as Postman.
STEP 3: Make Your First API Call
Now you’re ready to make your first API call using the API Reference. The API Reference is a comprehensive, interactive reference of all the V3 endpoints, methods, properties and parameters. You can also make authenticated API calls to your Constant Contact account right in the API Reference. Learn more.
Get All Contacts in Your Account
Your first API call will retrieve all the contacts currently in your Constant Contact account. A new account is populated with your contact information upon creation.
- Navigate to the GET Contacts Collection page in the API Reference.
- Review the description, parameters, response sample and schema for this endpoint and method.
- Scroll down to the Try button just after the parameters section.
- Authenticate - in order to make a call, you have to grant the API Reference access to your account. Click to authenticate and grant access to the API Reference. You’re authenticated if the button reads “signout”.
-
Click . If yours is a brand new Constant Contact account, you should only see one contact in the response - you!
If you see a 401 Unauthorized response, you need to authenticate by clicking .
Next Step - Add Contacts
The next step is to add contacts to your Constant Contact account. We’re going to add contacts by importing a CSV file with the contact information exported from your email application. You will need to the following to import contacts to your account using a CSV file:
- a properly formatted CSV file
- a
list_id
to which the imported contacts will be added
Export Contacts to a CSV File
- Export a set of contacts from your email tool to a comma separated value formatted file. If you use Gmail, export to an Outlook CSV formatted file.
- Clean up the CSV file to fit the requirements for column names and contact data that we accept. Learn more.
Get a list_id for the import
You’ll need to specify a list to which to add the new contacts when importing. Here we’ll retrieve a list_id
from your account to use.
- Go to the GET Lists Collection endpoint in the API Reference. Click . You should still be authenticated to your account - check the button - if it reads signout, you’re authenticated.
- Copy the
list_id
value to your clipboard.
Import the CSV File
Now you have everything you need for the import.
- Go to the Import Contacts Using a CSV File endpoint in the API Reference.
file
parameter - Choose the CSV file with the contact data you’re importing.list_ids
parameter - Paste thelist_id
you just copied into thelist_ids
parameter field.- Make sure you’re still authenticated, then click .
- Response - Importing contacts is an asynchronous process, so the response payload is the initial activity report.
Follow the Import Status and Check Results
To follow the status of the job, poll the Activity Status endpoint:
- Copy the
activity_id
in the response payload. - Go to the GET an Activity Status endpoint in the API Reference.
- Paste the
activity_id
value into the parameter field. - Click
. The current activity status is returned. Watch for when the
percent_done
field reads 100 and thecompleted_at
field is included in the response. Notice if there were any errors in processing the job. - Once the job is complete, go ahead and verify the import activity results by making a GET Contacts Collection call to see the contacts that you just imported. Use the
include=list_memberships
to see the list_id the contacts are members of.list_membership
is one of four contact subresources that you need to specify to include them in the response payload. Learn more.
STEP 4: Learn, Discover, Troubleshoot
- Migrating from V2 - Information and tools that will help ease the process of migrating your existing integration to our V3 API.
- OAuth 2.0 Authorization - learn how to implement OAuth 2 in your app.
- API Functionality & Endpoints - the API Reference offers detailed descriptions of properties, parameters, and responses for all V3 API endpoints. Make calls to your developer account using the API tester.
- Working with Contacts - learn best practices for creating, importing, and managing contacts with the V3 API.
- Using Bulk Activity Endpoints - manage large numbers of contacts using a single API call.
- V3 API Schema - download the V3 API schema to accelerate your development and testing cycles.