Use this quick start guide to help you get started using the Constant Contact V3 API. In this guide you will:
- Sign up for a Constant Contact developer account or log in using an existing account.
- Register an application and get an API key.
- Get your contacts and make your first API calls to your Constant Contact account.
- Learn about the next steps to take in building an integration.
Step 1: Sign Up or Log In
Go to the My Applications section of the V3 portal to sign up for a developer account. The developer account allows you to create and manage applications in our V3 API ecosystem. We also create a trial Constant Contact account that you can use in developing & testing your integration. In order to use the API, you need to call into an account that has granted access to the application that you are building.
If you already have a Constant Contact account, click Log in, otherwise click Sign up to get started. All you need to sign up is:
- email address
- first & last name
- organization name
- phone number
Step 2: Register an Application
After you log in, the My Applications page displays. Use the My Applications page to manage your integrations (applications) with the Constant Contact V3 API. As a new developer, you’re prompted to register an application. Registering an application generates an API key you will use to make authenticated calls into our V3 API. You only need an App name to register. We’ll add a default redirect URL that you can change at anytime.
- Click Register or . The App Name box displays.
- Enter the name of your application - remember, end-users will see the app name during the grant access flow.
- Click Save. The App Details page displays.
- We’re not going to add or modify anything here right now, so go ahead and click Save in the top right.
Your first application is saved. You can return here to grab the API key, add or change details, and generate a
client_secret once you’re ready to start developing or making test calls using an HTTP client such as Postman.
Step 3: 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 info 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 .
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
list_idto 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 authenticated to your account - check the button - if it says signout you’re authenticated.
- Copy the
list_idvalue 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.
fileparameter - Choose the CSV file with the contact data you’re importing.
list_idsparameter - Paste the
list_idyou just copied into the
- 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_idin the response payload.
- Go to the GET an Activity Status endpoint in the API Reference.
- Paste the
activity_idvalue into the parameter field.
. The current activity status is returned. Watch for when the
percent_donefield reads 100 and the
completed_atfield 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_membershipsto see the list_id the contacts are members of.
list_membershipis one of four contact subresources that you need to specify to include them in the response payload. Learn more.
Step 4: Learn, Discover, Troubleshoot
- What’s new in V3 - See what’s new in the V3 API.
- Migrating from V2 - Information and tools that will help ease the process of migrating your existing integration to our V3 API.
- 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.
- OAuth 2.0 Authorization - learn how to implement OAuth 2 in your app.
- 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.