Hello user1988680,

Thank you for reaching out to Constant Contact API Developer Support. My team is here to assist outside software developers with questions about building into Constant Contact's API.

In order to obtain an Access Token, you’ll need to configure one of our available OAuth2 authorization flows. Below I’m including overview documentation for each of these flows, along with written instructions on setting up the Authorization Code flow and adding contacts, which some users find helpful.

OAuth2 Overview:

https://developer.constantcontact.com/api_guide/auth_overview.html

OAuth2 Authorization Code Flow:

https://developer.constantcontact.com/api_guide/server_flow.html

Sorry for any difficulty getting started with authorization, I know the process can seem a little daunting when first getting started. While our expertise is with our API itself as opposed to its implementation within any particular programming language, we are happy to answer any questions pertaining to Constant Contact’s API endpoints, functionality, and documentation.

I will start with clarifying the steps for the Authorization Code Flow and then will also include info on how to add contacts. While we don’t have any complete sample code libraries available at this time, most of our calls include samples.

You should be able to fully automate your integration with the exception of the initial Authorization Request screen and redirect, which can only be accessed/authorized via a browser window and cannot be bypassed, but you should only need to authorize each connected account once.

The Authorization Request screen is only for connecting a Constant Contact account to the integration, so for example if you are making a sign-up form or integration that only connects to one Constant Contact account, only you would access the Authorization Request screen one initial time to connect your account, it wouldn't be visible to people using the form/integration. When your users are accessing the integration, it will use the token set generated when you initially granted permission to access the connection. The only time other people would access the Authorization Request screen is if you are designing an integration that needs to connect to other Constant Contact accounts, as each account needs to grant permission to the integration.

To get started with the V3 API, you’ll want to start by going through the V3 API OAuth2 Authorization Code Flow. Please note, after step 1, you should set up step 4 before proceeding, because the authorization code from steps 2 and 3 only has a lifespan of 5 minutes.

Here is how your initial Authorization Request URL should be formatted:

GET https://authz.constantcontact.com/oauth2/default/v1/authorize?client_id=________________&scope=________________&response_type=code&state=________________&redirect_uri=________________

Step 1: Create an Authorization Request

https://v3.developer.constantcontact.com/api_guide/server_flow.html#step-1-create-an-authorization-request

Before getting the Authorization Code, we want to set up Step 4 (Get the Access Token and Refresh Token) ahead of time, because the Auth Code expires after 5 min and can only be used once.

Here is how the token request should be formatted:

POST

https://authz.constantcontact.com/oauth2/default/v1/token?code={auth_code}&redirect_uri=https://localhost&grant_type=authorization_code

Additionally, for this endpoint, you’ll need the following headers. (If you haven’t already, for the Authorization header, you’ll want to include the string “key:secret” encoded with Base64, which you can do here: https://www.base64encode.org/ )

Headers:

“Content-Type” : “application/x-www-form-urlencoded”

“Authorization” : “Basic ______“

Step 4: Get the Access Token and Refresh Token

https://v3.developer.constantcontact.com/api_guide/server_flow.html#step-4-get-the-access-token-and-refresh-token

Now that we have that set up, we’ll take our Authorization Request URL and paste it into a browser, where it will have you log in, grant access, and then will provide you with the Authorization Code in the URL that you are redirected to.

Take the Authorization Code and put it where {auth_code} is in the Token request example I provided before.

Once you have your first set of tokens, you’ll want to set the access token and the refresh token as values for corresponding variables in your application, so that when your program runs through step 8 of the OAuth2 Authorization Code Flow

to get the new set of tokens it can assign the updated values to those variables to maintain an authenticated connection.

You can either have the application refresh the tokens on a timer based on the life of the access token (access token lifetime is a static 24 hours), or you can check to see if the access token is still active before each submission, and then use the refresh token to generate a new set of tokens if not.

In order to parse the JWT access token for the expiration date/time and/or granted scopes, I'd suggest looking for a standalone JWT decoder tool or setting up a decoder within your program’s code so that it can programmatically verify the remaining lifetime of the access token before attempting to refresh.

[3rd party resource] JWT Decoder Tool Examples: https://jwt.io/#debugger-io  https://developer.pingidentity.com/en/tools/jwt-decoder.html

[3rd party resource] Epoch & Unix Timestamp Conversion Tool Example: https://www.epochconverter.com/

If you want your application to parse the JWT programmatically in your program’s code (the example we currently offer in the documentation is only in Java at this time), you can find instructions online regarding how to do this in different languages.

The OpenID Foundation maintains a list of libraries implementing JWT and JOSE specs, which may be a good starting point. Their list can be found here: https://openid.net/developers/jwt/

Next, make sure you are able to successfully refresh your token set. This cal is also to the token endpoint, but uses the refresh token instead of the code. You will want the same headers as we used when getting the first token set:

POST https://authz.constantcontact.com/oauth2/default/v1/token?refresh_token={refresh_token}&grant_type=refresh_token

Step 8: Refresh the Access Token

https://v3.developer.constantcontact.com/api_guide/server_flow.html#step-8-refresh-the-access-token

Once authentication and token variables are set up, and you’re able to complete Step 8 (Refresh the Access Token), you can then use your current Access Token variable value to make calls to the API endpoints using the authorization header 'Authorization: Bearer {access_token}'.

Next, you’d want to decide how you want to add contacts to the account. The three methods listed below each offer a different way to add contacts via the API, depending on how your integration is configured:

[[Option 1 (uses one API call, preferred endpoint for sign-up forms):]]

Use the sign-up form endpoint, to add a new contact to an account or update an existing contact based on their email address. Only use this method when a contact gives you their explicit permission to send them emails.

Create or Update a Contact Using a Single Method (less recommended)

https://v3.developer.constantcontact.com/api_guide/contacts_create_or_update.html

[[Option 2 (uses two API calls, allows you to overwrite/remove data for individual contacts):]]

Use this flow to add/update your contacts either via a sign-up form or other integration type which incorporates three contact endpoints:

Step 1: Check to see if the contact exists in the account using the email query parameter to search for a contact using a specific email address.

GET Contacts Collection

https://v3.developer.constantcontact.com/api_reference/index.html#!/Contacts/getContacts

Step 2: If the contact comes back as non-existent, use POST to create the contact:

POST (create) a Contact

https://v3.developer.constantcontact.com/api_reference/index.html#!/Contacts/createContact

Step 3: If the contact comes back as already existing in the account. You need to append the returned data with the desired list memberships and send that back with PUT to update the contact:

**When Updating a contact, we need to append the new information to the old information and send all of it back in the request, because when you update a contact using a PUT, all properties are updated, overwriting all existing property values. Any properties left blank or not included in the PUT will be overwritten with a null value.

PUT (update) a Contact

https://v3.developer.constantcontact.com/api_reference/index.html#!/Contacts/putContact

[[Option 3 (uses one API call, but can use two to verify activity completed successfully, use for syncing contacts between two systems):]]

You can use our bulk activity endpoints to import new contacts and update existing contacts when syncing local data with Constant Contact. These endpoints use the email addresses you provide in the import to determine if each contact is new or not. When you import an existing contact, these endpoints only update the contact properties you include in the import request.

Import Contacts Using Bulk Activity Endpoints

https://v3.developer.constantcontact.com/api_guide/import_contacts.html

Additionally, you can utilize our API Reference Page to find schemas & values for endpoint calls and JSON request bodies (in the right-hand column for each call), as well as test the functionality of our available endpoints to see how they will work once programmed within your application:

https://v3.developer.constantcontact.com/api_reference/index.html

While our expertise is with our API itself as opposed to its implementation within any particular programming language, we are happy to answer any questions pertaining to Constant Contact’s API endpoints, functionality, and documentation.

Please have a look and let us know if you have any other questions!

Regards,

Get token

The world's largest virtual email marketing conference. November 12-13th.