webservices

Searching for Contacts by Last Updated Date (Synchronizing Contacts)

by Administrator on ‎03-25-2011 09:52 AM

This functionality allows you to keep your contacts database up-to-date with the latest information from the Constant Contact database by querying only the updated contacts since your specified date.  The last updated date of a contact will change if any of its details have been updated or its contact list membership has changed.  Please note, however, that the search results do not specify what kind of updates have been made to each contact; we just know that they have been updated since the time you specified and return correspoding contacts accordingly.

 

If you plan to keep your database in sync with our database, we recommend running this API periodically to ensure that your database is up-to-date and the number of contacts you need to deal with is not very large.

The query can be run against a particular list type or a particular list.

 

To run the search for a particular list type, you need to use the GET method on the contacts collection withe following parameter:

 

https://api.constantcontact.com/ws/customers/{username}/contacts?updatedsince={date}&listtype={list-...   

To run the search for a particular list, you need to use listid instead of listtype parameter.  For listid, you must specify the numeric value of the list you are interested in searching.  For example, if <id> of the list you are trying to search is http://api.constantcontact.com/ws/customers/joesflowers/lists/1, the you need to specify 1 as listid parameter.

 

https://api.constantcontact.com/ws/customers/{username}/contacts?updatedsince={date}&listid={numeric-list-id}

The date has to be in UTC in the format specified by the Atom spec (i.e. 2008-07-23T14:21:06.407Z).  The supported list types are active, removed and do-not-mail.  The subscriber list type queries contacts that have subscribed to one or more of your contact lists; removed type queries contacts that have been manually removed from all lists, and do-not-mail type queries contacts that have opted out of receiving your emails.

Here's an example of what the URI might look like:

 

https://api.constantcontact.com/ws/customers/joesflowers/contacts?updatedsince=2009-12-01T01:00:00.000Z&listtype=active

In this example, you are looking for any contacts that have been updated since December 1st of 2009 after 1AM UTC and are still in active status.  If a contact has opted out since the date, the contact will not be returned in the result.

 

If the query is successful, it will return a list of contacts that have been updated since the date you used in your query parameter.  The contacts are returned in multiple pages, 50 contacts at a time, in order to improve query performance.  In fact, all collections return their data 50 entries at a time.  If there are no contacts that match the search criteria, you will get no contacts returned.

 

Please note that this search does not include contacts that have been removed from a list.  For example, if you query for updated Active contacts, it will not return contacts that have been ubsubscribed and now belong to Do-Not-Mail.


Here's an example of what the query might return as a result:

 

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom">
<id>http://api.constantcontact.com/ws/customers/joesflowers/contacts</id>
<title type="text">Contacts for Customer: joesflowers</title>
<link href="contacts" />
<link href="contacts" rel="self" />
<author>
<name>joesflowers</name>
</author>
<updated>2009-12-09T17:13:14.663Z</updated>
<link href="/ws/customers/joesflowers/contacts?next=23654&amp;updatedsince=2009-12-01T20%3A18%3A25.503Z&amp;
listtype=active&amp;ous=2009-12-01T01%3A00%3A00.000Z" rel="next" />
<link href="/ws/customers/joesflowers/contacts?updatedsince=2009-12-01T01%3A00%3A00.000Z&amp;listtype=active"
rel="first" />
<link href="/ws/customers/joesflowers/contacts?updatedsince=2009-12-01T01:00:00.000Z&amp;listtype=active"
rel="current" />
<entry>
<link href="/ws/customers/joesflowers/contacts/23647" rel="edit" />
<id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/23647</id>
<title type="text">Contact: test_user1@example.com</title>
<updated>2009-12-01T20:16:34.482Z</updated>
<author>
<name>Constant Contact</name>
</author>
<content type="application/vnd.ctct+xml">
<Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
com/ws/customers/joesflowers/contacts/23647">
<Status>Active</Status>
<EmailAddress>test_user1@example.com</EmailAddress>
<EmailType>HTML</EmailType>
<Name>Test User 1</Name>
<OptInTime>2009-12-01T20:16:34.482Z</OptInTime>
<OptInSource>ACTION_BY_CONTACT</OptInSource>
<FirstName>Test</FirstName>
<MiddleName></MiddleName>
<LastName>User 1</LastName>
<JobTitle>API Writer</JobTitle>
<CompanyName>CTCT</CompanyName>
<HomePhone>555-555-5555</HomePhone>
<WorkPhone>555-555-5555</WorkPhone>
<Addr1>1601 Trapelo Road</Addr1>
<Addr2>3rd Floor</Addr2>
<Addr3>Suite 300</Addr3>
<City>Waltham</City>
<StateCode>MA</StateCode>
<StateName>Massachusetts</StateName>
<CountryCode>us</CountryCode>
<CountryName>United States</CountryName>
<PostalCode>02154</PostalCode>
<SubPostalCode>1781</SubPostalCode>
<Note></Note>
<CustomField1></CustomField1>
<CustomField2></CustomField2>
<CustomField3></CustomField3>
<CustomField4></CustomField4>
<CustomField5></CustomField5>
<CustomField6></CustomField6>
<CustomField7></CustomField7>
<CustomField8></CustomField8>
<CustomField9></CustomField9>
<CustomField10></CustomField10>
<CustomField11></CustomField11>
<CustomField12></CustomField12>
<CustomField13></CustomField13>
<CustomField14></CustomField14>
<CustomField15></CustomField15>
<Confirmed>false</Confirmed>
<LastUpdateTime>2009-12-01T20:16:34.482Z</LastUpdateTime>
</Contact>
</content>
</entry>
<entry>
<link href="/ws/customers/joesflowers/contacts/23648" rel="edit" />
<id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/23648</id>
<title type="text">Contact: test_user2@example.com</title>
<updated>2009-12-01T20:16:35.713Z</updated>
<author>
<name>Constant Contact</name>
</author>
<content type="application/vnd.ctct+xml">
<Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
com/ws/customers/joesflowers/contacts/23648">
<Status>Active</Status>
<EmailAddress>test_user2@example.com</EmailAddress>
<EmailType>HTML</EmailType>
<Name>Test User 2</Name>
<OptInTime>2009-12-01T20:16:35.713Z</OptInTime>
<OptInSource>ACTION_BY_CONTACT</OptInSource>
<FirstName>Test</FirstName>
<MiddleName></MiddleName>
<LastName>User 2</LastName>
<JobTitle>API Writer</JobTitle>
<CompanyName>CTCT</CompanyName>
<HomePhone>555-555-5555</HomePhone>
<WorkPhone>555-555-5555</WorkPhone>
<Addr1>1601 Trapelo Road</Addr1>
<Addr2>3rd Floor</Addr2>
<Addr3>Suite 300</Addr3>
<City>Waltham</City>
<StateCode>MA</StateCode>
<StateName>Massachusetts</StateName>
<CountryCode>us</CountryCode>
<CountryName>United States</CountryName>
<PostalCode>02154</PostalCode>
<SubPostalCode>1781</SubPostalCode>
<Note></Note>
<CustomField1></CustomField1>
<CustomField2></CustomField2>
<CustomField3></CustomField3>
<CustomField4></CustomField4>
<CustomField5></CustomField5>
<CustomField6></CustomField6>
<CustomField7></CustomField7>
<CustomField8></CustomField8>
<CustomField9></CustomField9>
<CustomField10></CustomField10>
<CustomField11></CustomField11>
<CustomField12></CustomField12>
<CustomField13></CustomField13>
<CustomField14></CustomField14>
<CustomField15></CustomField15>
<Confirmed>false</Confirmed>
<LastUpdateTime>2009-12-01T20:16:35.713Z</LastUpdateTime>
</Contact>
</content>
</entry>
</feed>

Please note that the resulting entries are actually different from the contact details you would get when you ran a Get method against a specific contact.  In fact, the results do not include <ContactLists> elements to indicate the contact list subscriptions.  In order to get contact list subscription information, you need to query individual contacts by using the link provided for each contact under <link> tag with attribute rel="edit".  Please note that you cannot use these search results as the basis for updating a contact's information.  You need to get a contact's detail information first, and then use the resulting XML as your starting point.

 

In order to traverse these pages to get to the next set of contacts, look for <link> tag with attribute rel="next" to build your URL for the next page.  The above example shows an example of this next link even though technically it should not be there because there are less than 50 contacts.  Note that the link is XML-encoded (i.e. & is represented as &amp;).  In order to use the link, you must decode it first (i.e. convert &amp; to &), then URL-encode to form a proper URL.