Hi there, I'm designing an integration with our crm system and have a few questions about adding and updating Contacts.
Adding new Contacts.
For small numbers of contacts a POST request to the contacts resource should be used. Is there a limit on the number of these requests? Would it be acceptable to submit 250 contacts in 10 batches of 25?
What does the response to an add contacts POST requests contain?
What are the differences between the bulk activity types ADD_CONTACTS, SV_ADD & ADD_CONTACT_DETAIL?
When a bulk add activity has completed will it return any information on the the new contacts added. Their URI or id for example?
How long should we expect to wait for a bulk add activity to run with say 5000 contacts?
To update contacts there are a few options.
Store the contacts id locally in our system and make multiple PUT requests one for each contact update. Is there a limit to the number of PUT requests?
Don't store the contacts id locally but lookup the contacts by email address to get their ids and then perform multiple puts as above.
Is it possible to bulk update contacts with an activity?
For more than a few contact adds at a time, it would be best to use the bulk uploader (activities) method, not the individual add method. You will be POSTing each contact individually in one request to our server each otherwise, whereas using the bulk feature you can make one request.
We would give you a 201 Created or 200 OK response to the POST contact request, if successful.
The bulk activity types is determined by our system no matter what you set the value to, but it is basically determined on our side based on how much data is being given to us.
For 5000 contacts, I would expect that activity to be complete within 5-10 minutes.
There isn't a limit on the number of PUT requests, but similar to the POST operation, you can do this via the bulk (activities) method. Any new information for an existing contact will be added, and if you include fields that are already set for the contact (for example, their first name), the new information will override the old.
You could also use the contact ID and store it locally, or search for an email to get the ID to do a PUT request individually for your contacts (as you mentioned). I would use the bulk method when you have more than a few contacts to update.
Let me know if you have any other questions!
API Support Specialist
Hi Shannon, thanks for the reply.
One more question. Can a bulk add Contacts activity return the ids of the contacts it created?
As of now, we don't have the capability to return the new contact id's automatically after the request is made. You would have to do a GET on the contacts collection. The results will show the most recently added contacts in your account, with their id's, and also a link to the next 50 records (contacts) in your account, sorted newest to oldest.
API Support Specialist
I am now developing a script to synchronise from our system to Constant Contact using bulk activities to add and update contact details and have a few more questions!
The asynchronous nature of bulk activities will need some form of polling to determine when activities have completed and the contacts added or failed due to contact validation errors.
I can see from the "Contacts Collection and Resource" that Email, StateCode and CountryCode are validated. Is there any other validation applied when creating Contacts?
If multiple bulk add Activities are created will they run in parallel or serially and is there a limit on the number of activities that can run in parallel per account?
I note that activities cannot be deleted, the number of these will increase over time and this may impact managing the activity list.
Is the activities list returned in a consistent order?
I can't see activity list on the PHP API wrapper. Is this missing/going to be added?
For updates contacts will be found with email address search then updated with bulk activities. I understand that the update must include a "ContactLists" element with all the contacts lists. I'm not clear from the documentation if the results from email address search include "ContactLists" or if detail will need to be loaded for each to get the "ContactLists"
And finally can bulk update be used to opt contacts out of email?
We only validate the 3 fields you mentioned, but you are limited to a certain number of characters in each field (usually no more than 50), and special characters like & may cause issues, though we aren't validating the contents per se.
You can have activities that run in parallel, but you will most likely see a maximum of two activities running at the same time in one account (as of now). As I'm sure you're aware, this means that there is a possibility of creating activity 1, then activity 2, and having something in activity 1 override what activity 2 did (say, if the same contact was updated in both activities and contained different information). Most likely, activity 1 would complete first, but that is not guaranteed.
The activities list should return the most recently added activities first.
We haven't had too many requests for an activities list in our wrappers, and that wasn't on the roadmap, but I will pass that feedback on. What information would you want returned from us regarding activities? The status of the activity and a title for each?
If you do a get by email address, the result will not include the lists for that contact, but if you get contact by ID, that result will give you the current lists that the contact is on.
You could bulk upload your contacts into the Do Not Mail or Removed lists, yes. You would want to use activityType=REMOVE_CONTACTS_FROM_LISTS to remove contacts, and you could send contacts to the do not mail list by making them go into the list with this URI:
Let me know if you have any follow up questions.
API Support Specialist
Hi Shannon, thanks for all the answers. I have another question!
When adding Contacts with a bulk activity a "lists" parameter specifies one or more lists to which the contacts will be added. I had assumed that the lists param would need to contain all the lists that the contact was a member of in a similar way to the ContactLists element on the Contact resource. I think this is incorrect and wanted to confirm. I have found that bulk updating a contact with a single lists parameter adds the contact to that list and leaves existing list memberships unchanged. Can you confirm this is correct?
You're quite welcome. Good catch there. The way most people update contacts is one at a time as opposed to using the bulk function, and with one at a time contact updates (GETting and PUTting the modified XML back into Constant Contact), you do need to specify ALL lists the contact should be on or they will be removed from their previous lists.
The bulk method, however, leaves old information in place if it's not overriden. For example, when doing a bulk import, if you supply one new list for the contact, and the contact was previously on another list, the contact will be on both lists after the update. If a contact had some information in "Custom Field 1", and you update that contact via the bulk method without supplying anything for Custom Field 1, the contact will retain that information. If, however, you supply something for Custom Field 1, the old information will be overridden. I hope that's clear.
The short answer is yes, if you add a contact to a new list via a bulk import, they will retain their old lists.
API Support Specialist
Suppose If we add Email, First Name and Last Name using bulk Add And
If we add comma or | symbol in Firsr Name (e.g Shan,Ras) and try to add that contact using bulk add then the string after comma is added in Last Name.
In this case how we add comma and | characters in our contact
In order to add characters that might otherwise change the format of comma separated data you will need to place quotes around the data. For example:
First Name, Last Name
"test, name", Name
Submitting the data formatted like that will allow you to add characters to a name htat would otherwise not work. If you do run into issues with this process, you can reply to this post and I'll be happy to help out!
Tier 2 Support
View API documentation, code samples, get your API key.Visit Page
We want to hear from customers like you about your favorite features and how they have helped your business or organization. Tell us by answering a few questions in...Read More