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&updatedsince=2009-12-01T20%3A18%3A25.503Z&
listtype=active&ous=2009-12-01T01%3A00%3A00.000Z" rel="next" />
<link href="/ws/customers/joesflowers/contacts?updatedsince=2009-12-01T01%3A00%3A00.000Z&listtype=active"
rel="first" />
<link href="/ws/customers/joesflowers/contacts?updatedsince=2009-12-01T01:00:00.000Z&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 &). In order to use the link, you must decode it first (i.e. convert & to &), then URL-encode to form a proper URL.
