Tips, Tricks and Known Issues Using the WebServices APIs

Getting Started

--1. Get your Developer API key. The Developer API key identifies the person or organization who built the application. It is confidential information and should not be shared with your application end users.
--2. Find out which APIs exist. See this reference.
--3. Construct your access credentials. Your access credentials are constructed from the Developer API Key, the Constant Contact login name for the data you want to access and the Constant Contact password for that Constant Contact user. The API Username is a concatenation of your API User Key, the "%" character and the Constant Contact login name like so: {API Key}%{UserName}
--4. Reference the top level document for your domain. In many cases this may be the service description, which is held here: https://api.constantcontact.com/ws/customers/{UserName}/
where {UserName}/ is the user name of the Constant Contact account holder.
--5. Navigate the response document to get a reference to the next level of details.

Using RESTClient

RESTClient is a great tool to test your XML and the way you are using Constant Contact APIs. It gives you a simple way to test individual calls outside of your program to check if you are calling APIs correctly, and if not, it provides detailed error messages that the server returns. We created a user guide to help you use this helpful tool.

Combining Several Constant Contact APIs

Constant Contact supports several APIs. While the APIs can be combined as needed, the capabilities, usage model and limitations of the APIs vary. For an overview of the available Constant Contact APIs, see this page.

FAQs and API Known Issues

There are a number of things you might want to know about the API, including:

• Question: Do you have a list of common Error Codes and their cause?
• Answer: Please see this Error Codes page.
• Question: Do Contacts added via the API trigger Autoresponder email sequences (ie. If I add someone via the API will they get my AutoResponder sequence)?
• Answer: It depends on which API you are using, and what parameters you use in the API. Please see this FAQ for details.
• Question: Is it possible to opt-out and then re-opt-in a Contact (Similarly, "Can I use the API to move a contact from the "Do Not Mail" list to some Active List)?
  Answer: You cannot re-opt-in contact. That is a fundamental principle of how Constant Contact manages Opt-outs. Once a contact is "Opted Out", only the contact themselves can opt back in.
  However, you can "Remove" and Re-add Contacts. A contact that is Removed is valid in every way except they are not on any Contact Lists and thus they will not receive any emails.
  To 'Remove' a contact, you simply update (PUT) their atom entry with an empty ContactLists tag.
  They will not get any emails.
  To 'Re-add' the contact, simply update (PUT) their entry back with the Contact List or Lists you want.
• Contact List Display Issue: Newly created Contact Lists do not appear in the UI until the Constant Contact User has logged out of, and back into, their account (Issue: 28339).
• Incorrect (500) Error Code Issue: In some cases you may receive an HTTP Server Error (Error Code = 500) for issues which are not server issues. For example, you will generally get a server error for non well-formed XML request documents. A POST to create a contact list which uses the wrong Content-type will also cause a 500 error (Issues: 27633 and 28337). A Contacts Collection GET which uses the email query parameter will generally return a 500 (rather than an empty set), when the email address provided does not exist.
• Updated Tag Contents Issue: The Updated (last updated field) property for all resources always returns a new date, rather than the true last updated value for that resource (Issue: 25261)
• Contact List Does Not Exist Issue: When a Contact is Added to a Contact List that is not included on the Signup form for the Account Owner, the Contact entry must include the <OptInSource>ACTION_BY_CUSTOMER</OptInSource> tag within the Contact part of the entry (in addition to being required within the ContactList parts of that same entry).
• You may also be interested in taking a look at this set of Site Visitor API Frequently Asked Questions.