Question about best practice in syncing new and existing customers:


Question about best practice in syncing new and existing customers:

Our desktop app. is typically the collection source for all new email addresses that are uploaded to Constant Contact.  However, for many of our clients that are already using Constant Contact, those email addresses may already exist in CC.  In come cases the email address exists in both systems but there is no direct link between the two (In that I don’t yet have the Customer ID# in the app).  In other cases the email address only exists in Constant Contact and not in our app, but the email does belong to an existing customer in our app. 


So the big question becomes how to sync both systems such that additions and changes made in CC and in our app. get updated in both locations.


So let’s say that our client adds or modifies 25+ customers in our app, some are brand new customers being added to lists, others are existing customers being added or removed from lists, and now it’s time sync all those changes.


The rough algorithm I’m currently using goes as follows: 


For Each Customer

    Do we have an ID# for this customer in our app?



             Get Customer Detail XML


             Search CC by Email Address

                 Was it Found?


                            Get Customer Detail XML using retrieved Customer ID


                            Create Empty XML Structure


       Update customer XML Structure and Post/Put back to CC


Next Customer


So the question is, is this the best way to do this?


Also, if I loop through this process more than 25 times am I violating the Terms of Service agreement?  I’m thinking not because each submission only deals with one Customer.  Still, if there are many hundreds of customers to process, I could see this taking a really, really long time.


If I were to take this same information and place it in the Activity structure for performing bulk uploads, how would CC treat rows where:


   A. there is no customer ID#

   B. an email address either does or doesn't already exist

   C. some customers are being added to one list and other customers are being added to other lists? (From what I see I’d still have to submit individual bulk jobs, one for each list.)

   D. If a problem is found with one row (invalid email or email had been opted out) does it reject the entire job, or does each row get returned a response associated with it?


I guess I just want to make sure I’m on the right track here and I’m not missing something obvious.


Thanks for any comments or suggestions.


Chris Campbell


Hi Chris,


Great question and one that many of our integrated partners and application developers ask.  The answer depends a lot on the user flow and how the behavior is expected to be for an end user.  Let me explain the two user flows and the best ways to accomplish each, I think this will give you the answer you're looking for.


Realtime User Interaction Usecase: This scenario is identified as having direct input from a user (either a subscriber or the user of a 3rd party application).  In this scenario, a single contact is generally added or modified and the user experience would be instant gratification.   For this flow, you would use our Contacts API to do all of the manipulation real time.  The steps would be:


1. Check if Contact exists (search by email)

2. If Contact does not exist, create the contact (Create Contact API)

3. If Contact does exist, either

    a. (Subscriber Option) Present some security flow to verify a subscriber is who they are before allowing them to update information

    b. (User Option) Present the user with the ability to update information

4. Present the response (success/failure) to the subscriber/user


Non-Realtime/Bulk Usecase: This scenario is one where the responses to the user and the updates are not done in realtime.  Generally speaking, this is for bulk syncing, batch processing (such as through a query wizard) or any other scenario where the volume or user flow would result in excessive wait times or there is no user involved in the actual processing.  The flow in this scenario is much simpler, though because it involves batch processing on our end, the responses will not be realtime.  Generally speaking, the batch jobs take upwaards of 1-5m, with large uploads and peak time waits being in the 10-20m range.


1. Run query/script to collect all Contacts to be updated/created

2. Create a bulk activity request to upload/create all contacts (contacts will be updated/created based on collision detection, only criteria for collision is exact match email address)

3. One bulk activity request is created, an activity resource will be returned

4. Monitor the status of the activity resource periodically (or allow user interaction to query a check on the status), see the documnetation on Bulk Activities for full list of status codes

5. Once activity resource status is set to Complete, a list of errors will be provided for presentation back to the user


Hope this clears up any confusion on which method to use!


Dave Berard
Senior Product Manager, Constant Contact

Hi Dave,


Thanks for your reply. 


I understand everything you are saying in your reply but you didn’t really answer one important question. 


In our case, users are not updating CC in real time.  It’s similar to the bulk process you described.  The method I described above involves processing (syncing) each contact/email as a separate job using the REST Api.  Even though I may have few or many email addresses to sync, I’m only populating and submitting the xml structure with one contact/email at a time.  I do this so that I can provide a progress bar to the user asI cycle through the process and keep them informed of where in the process they are (our users are big on process feedback).  After the process has completed I present them with the results.


So getting back to my original question:  if I cycle through this process more than 25 times am I violating the Terms of Use agreement? 


I also have some questions about how the whole BULK activity works.  In reading through the docs I see that jobs are submitted asynchronously.  So what is this response telling me? “If the new activity is created successfully, the server will return an HTTP status of 201 Created”.  Is it telling me that the job was “submitted” correctly or is it the response I get after the job has “completed”?  Also , if I submit a lengthy job and the user decides to exit our app and go to lunch, how do I check to see if the job has completed or not?  Is there some sort of job ID I can check in the API or am I just looking for a returned file?






Sorry about missing that point in your initial question, oversight on my part.  It is not a violation of the T&C.  The only concerns are user experience on your end.


You're right in your understanding, it is a "your job has been submitted successfully" message.  This will include an ID for the job you created.  You can then monitor that ID (which will exist for 60 days after creating as part of our historical data) to check the status (submitted, pending, queued, running or complete) and, once it is complete, the errors and warnings (if any) that occured.  You can find the details on pulling a list of all activities and the details of specific activities here:


Sorry again for the miss on one of your initial questions.

Dave Berard
Senior Product Manager, Constant Contact

No worries.  Thanks again for your assistance.



Developer Portal

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

Visit Page