Creating a Contact - need clarification

Regular Participant

Creating a Contact - need clarification

Hello again.

I have a few questions regarding "Creating a Contact" (


1. "The server does not check for uniqueness when creating a contact because a new unique ID will be created anyway"

I found that if I submit a new/valid email, the contact is created and your service responds with "1" -- if I submit a duplicate, the server doesn't respond at all. I can't tell if something was (re)created or not.


2. "The following XML describes the minimal XML body required to create a new contact."

The XML sample includes a <ContactList> tag. It seems that including this tag, along with a valid list_id, will actually place the new contact on the specified list. The exception to that rule is if the email address already exists on another list; in that case, nothing is returned (per #1) and the contact is not added to the list. Is this the behavior I should expect?


3. How do I get the created contact's ID? Do I have to do a separate lookup so that I can make additional calls for this contact? It does not appear to be returned.


#2 seems to be show stopper for me. My application is built to help marketers collect email addresses via SMS campaigns. If their Constant Contact account has multiple lists and an existing email address interacts with a new SMS campaign, their email address will never get created/add to the Constant Contact account.


Please help, thank you.




It seems like a couple of these questions are arising because you are trying to use the 'create a new contact' documentation while trying to update existing contacts in some cases.  If you are trying to update a contact, the process should be a bit different than adding one.  When creating a new contact, you want to POST the contact, and when you want to update a contact, you should first GET their details, and then PUT the contact using the XML that has been modified to add or take away lists (and make any other modifications to the contact).  Here is our documentation for updating contacts.


1.  You are correct, you do not need to specify a unique contact ID when creating a contact because a new one will be created for a new email address.  If you try to submit a duplicate email address (or one that was previously in the account), the server will respond with an error.  It sounds like your code may not be passing back the error message in the response from our server.


2.  The problem arises when you try to update an existing contact.  When you PUT the existing contact using the XML, the system will keep ONLY the lists specified in the most recent PUT for that contact.  If you don't specify any lists in the contactList nodes, the contact will not be in any lists.  The behavior you're describing does not sound to be consistent with that.  If you put the contact into only 1 list, it should go into that list, and you should be able to verify that in the account.  Let me know if you have continued issues with that or can reproduce the contact not getting added to any lists when you put them into one or more.


3.  Yes, you do need a separate call to get a contact's unique ID once the contact exists in the system.  You can do a GET by email address to get the contact's ID.  The contact's ID will also be returned in the response back from the server once the contact is created.  I don't think you're seeing the responses from the server as you should be.  


I checked to make sure our responses are behaving normally this morning, so you may want to download and use RESTclient for troubleshooting purposes.  You can do simple get, post, put, and deletes to your account and see the responses that come back from the server in the body tab in RESTclient.  You will also see the response codes that come back from the server, such as 201 created, 409 duplicate entry, etc.


I hope that helps.  Let me know if you want any clarification.



Best Regards,

Shannon W.

API Support Specialist

So let's focus on just #1. I'm not trying to update a contact right now. At some point our application will need to add email addresses to lists, which means I'll need to do the update. But for now, let's focus on "Creating a Contact"


The documentation ( shows these 3 lines in the XML:


        <ContactList id="$username/lists/$list_id" />

It would appear I can't create a contact without putting them on a list. (A) Is that correct behavior? I tried the XML without those 3 lines and it does not add the contact (it appears to fail).

(B) Is there a way to add a contact without putting them on a list?


(C) Is it possible to Create a Contact (using the required <ContactList> element) and actually remove that contact from other lists? There are too many test cases for me to try and reproduce this action, your advice is appreciated.





A) You are correct, the contact will not get created if it is not on at least one contact list.  That is the way the API was designed, and you will get errors if you try to add a contact without putting it on an active list.


B) There is no way to add a contact to an account without adding them to an active contact list in the account.  You could, however, do two steps, where you add a contact to a list (perhaps using ACTION_BY_CUSTOMER) to suppress the welcome email from getting sent, and then in the next step do a PUT to put the contact on the removed (inactive) list.  You can't add a contact to the removed list until it exists in the account, however.


C) If a contact is on a list in your account, you wouldn't be 'creating' them, just updating.  That said, you can most definitely update an existing contact and remove them from their existing list subscriptions.  Our API keeps no record of what lists a contact was on, so once you do a PUT for an existing contact, the API ONLY looks at what contactLists are in the XML and only puts the contact into those lists (thus removing them from their previous lists).  As I mentioned above, there isn't a way to directly create a contact and remove them from all lists simultaneously.


I hope that helps!



Best Regards,

Shannon W.

API Support Specialist

Wow, that's really bad. Sorry to be critical, but this is a mess.


Did I read somewhere that you all have a new version of your API coming out?

Thank you.

We are working on a new version of the API.  The list requirement is actually something our product enforces as a whole.  A Contact must be a member of one or more lists.  Our product doesn't actually support creating a Contact that isn't part of a list today, though that's also something we're working on.


Can you describe what you're trying to accomplish through our product that would need a Contact to be created and not on a mailing list?  Additional information would be great as currently our product works completely off of lists.  Without a Contact being on a list, we don't provide any value to having them a member of your account. 

Dave Berard
Senior Product Manager, Constant Contact



Your feedback is valid.  I personally haven't seen any other requests from developers that a contact get created and put into no lists to start with, but I will submit that feedback to our engineering team.  I think the question would be, why is the contact going into no lists to start with, and if we make this a capability, how much feedback will we get that a developer intended a contact to start getting mail, but accidentally didn't add them to any lists upon creating them?  Again though, I will submit your feedback.  


The ability for that to happen (adding a new contact into no lists) really has to do with Constant Contact's architecture: if a contact is active, by definition they are active in at least one list, and active contacts are counted towards billing tiers (for email marketing, we bill based on the number of active contacts).  Our teams would need to decide if it's fair to charge for "active" contacts who are on no lists, or change the way we count active contacts.  This is just to give you some idea as to the complexity of the request.  Many teams would need to be involved in the decision, clearly; it's not something we could just enable in the API and be done with.  That being said, I know the contacts team is working on a new system for storing contacts, and it's more flexible than the way we do this now, so you may see increased functionality there in the near future (maybe early next year).


Also, you heard correctly, we are developing version 2 of our API, and it is in the beta version.  If you would like to participate and give feedback for the new API, just email us at and we will give you access to the beta API.


Best Regards,

Shannon W.

API Support Specialist

Thank you both for your responses.


I do actually have contacts in my platform that don't belong to a list. If you look at my account, I have 2 "active" contacts that both belong to lists and 4 "removed" contacts that don't belong to a list. So I know there is a way for contacts to exist without being linked to a list.


My app is built to add contacts to lists, so I'm not looking to add contacts without a list. My problem is how your "Create a Contact" reacts when an email address already exists in the account.


Example: pretend exists on list-id #2. If my app tries Creating (and since I *have* to declare a list, I use list-id #5), the API doesn't really do anything. I now have to create logic on my side to look at the Create a Contact API call and decide what to do next. I understand you have your systems in place, but from perspective this logic is broken. I expect to end up on list-id #5 regardless of their status on any other lists.


The same example applies if the contact I'm trying to create is a 'removed' contact.


To say it another way:

 - if an email address does not exist on the account, Create a Contact API creates them AND adds to the list

 - if an email address does exist on the account, Create a Contact API does nothing

The inclusion of the list-id is irrelevant if the contact exists, but is required if the contact does not.


I understand the legacy architecture issue. It still seems broken from my end-user point of view.


To your credit, the best part of your API is this forum and your responses :)

Thanks for the clarification on what you're doing and the positive feedback on our support team.  They work very hard to try to help our developer communty, I'll make sure to pass the feedback on to support management.


A Contact in our product today is unique based on email address, so once you've created a Contact that has once, you can never create them again (unless you changed their email address to something else).  Our API actually retuns a 409 Conflict HTTP error code if you try to create a Contact that already exists, it sounds like the code you're using likely is hiding HTTP error responses from your application.  This could mean you are using our PHP library, which has a bug our support team is currently working to resolve that causes error exceptions to not be thrown back up the stack.


In order to update list memberships for an existing Contact, you would need to do an update request (PUT on the Contact record if you're using our raw API and not a wrapper library).  This is a complete update, not an append, so if your goal is to append the Contact lists instead of orverwrite, you will need to do a GET on the Contact first to get their existing list memberships.


All of these points are things we're looking to improve in our next version of our API.  We certainly understand that it ends up becoming excessively complicated to do a simple task (update list memberships) due to our REST architecture.  Definitely know that this is on the top of our team's priority list to solve in version 2.  We have some possible solutons but nothing available for beta testing yet. 

Dave Berard
Senior Product Manager, Constant Contact
Developer Portal

View API documentation, code samples, get your API key.

Visit Page