Developer Web Site

The Contact Lists collection is used to list, create, modify and delete Contact Lists. Contact Lists are names for groups of Contacts. The Contact Lists collection manipulates the lists themselves. It does not perform any operations on a list's member Contacts.

Retrieving a Collection

To retrieve the collection of contact lists for the UserName joesflowers, you perform an HTTP GET on the collection URI, http://api.constantcontact.com/ws/customers/joesflowers/lists in this example, which returns the following XML document: 

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/lists</id>
  <title type="text">Contact Lists</title>
  <link href="" />
  <link href="" rel="self" />
  <author>
    <name>Constant Contact Web Services</name>
  </author>
  <updated>2008-04-16T13:07:13.453Z</updated>
  <link href="lists?next=6" rel="next" />
  <link href="lists" rel="first" />
  <link href="lists" rel="current" />
  <entry>
    <link href="/ws/customers/joesflowers/lists/1" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/lists/1</id>
    <title type="text">General Interest</title>
    <updated>2008-04-16T13:07:14.057Z</updated>
    <content type="application/vnd.ctct+xml">
      <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/" 
          id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1">
        <OptInDefault>false</OptInDefault>
        <Name>General Interest</Name>
        <ShortName>General Interest</ShortName>
        <SortOrder>1</SortOrder>
      </ContactList>
    </content>
  </entry>
  <entry>
    <link href="/ws/customers/joesflowers/lists/2" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/lists/2</id>
    <title type="text">Recent Signups</title>
    <updated>2008-04-16T13:07:14.061Z</updated>
    <content type="application/vnd.ctct+xml">
      <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/" 
          ?id="http://api.constantcontact.com/ws/customers/joesflowers/lists/2">
        <OptInDefault>false</OptInDefault>
        <Name>Recent Signups</Name>
        <ShortName>Recent Signups</ShortName>
        <SortOrder>2</SortOrder>
      </ContactList>
    </content>
  </entry>
</feed>

The response is made up of a feed element which contains some metadata about the feed followed by a series of entry elements. Each entry is made up of some metadata followed by a content element. Inside the content element is a ContactList element which describes the attributes of a particular contact list. The structure of the Atom elements is described in detail by RFC 4287. The structure of the ContactList element is described below.

Retrieving an Individual List

An individual list entry may be retrieved by issuing an HTTP GET to the entry's URI. The URI may be obtained from the Location header after creating a new entry or from the link element with rel="edit" attribute in an existing entry. A typical entry looks like this: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/lists/1" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/lists/1</id>
  <title type="text">General Interest</title>  
  <updated>2008-04-16T18:39:35.710Z</updated>
  <content type="application/vnd.ctct+xml">
    <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/" 
        id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1">
      <OptInDefault>false</OptInDefault>
      <Name>General Interest</Name>
      <ShortName>General Interest</ShortName>
      <SortOrder>1</SortOrder>
    </ContactList>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/lists</id>
    <title type="text">Contact Lists</title>
    <link href="" />
    <link href="" rel="self" />
    <author>
      <name>Constant Contact Web Services</name>
    </author>
    <updated>2008-04-16T18:39:35.717Z</updated>
  </source>
</entry>

Creating a New List

A new Contact list is created by making an HTTP POST to the collection URI. The POST body must contain an Atom entry element that includes the content for the new list.   The Content-Type of the request must be set to application/atom+xml.  Here is a representative entry: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>data:,</id>
  <title/>
  <author/>
  <updated>2008-04-16</updated>
  <content type="application/vnd.ctct+xml">
    <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/">
      <OptInDefault>false</OptInDefault>
      <Name>A New List</Name>
      <SortOrder>99</SortOrder>
    </ContactList>
  </content>
</entry>

Note that the id, title, author and updated elements must be present in the XML in order to conform to the Atom specification, even though their values will be replaced by the server. The <id> element must have an acceptable format (<id>data:,<id> will work). The title and author elements may be empty. The id must contain a URI, but since the value is not used by the server, any URI will work. The server does not check for uniqueness. The updated element must contain a date or date/time value, but again the value is not used by the server.

If the new list is created successfully, the server will return an HTTP status of 201 Created. The HTTP Location header in the response will contain the URI of the newly created List, and the entity body returned will be the entry for the list, including server-generated values like ids and links: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/lists/15</id>
  <title type="text">A New List</title>
  <author />
  <updated>2008-04-16T15:28:09.757Z</updated>
  <content type="application/vnd.ctct+xml">
    <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/" 
        id="http://api.constantcontact.com/ws/customers/joesflowers/lists/15">
      <OptInDefault>false</OptInDefault>
      <Name>Test list 5</Name>
      <SortOrder>1</SortOrder>
      <ShortName>Test list 5</ShortName>
    </ContactList>
  </content>
  <link href="/ws/customers/joesflowers/lists/15" rel="edit" />
</entry>

Updating a List

A Contact List is updated by issuing an HTTP PUT to the entry's URI. The PUT body must contain an Atom entry element with the changed content for the list.

The Atom entry must include an <id> tag and that id must reflect the URI of the list you are updating, for example, if you want to update the list in the 'Create' example above, this line is required:
<id>http://api.constantcontact.com/ws/customers/joesflowers/lists/15</id>

As a general rule, your "PUT" entry should include all of the content you receive in "GET" for the resource you are updating. It may be simplest to "GET" the resource you would like to update, then change only the fields you want to update and "PUT" the updated resource back. The API will ignore read only fields (such as update time) and your entry will be complete.

Clearing All Contacts From a List

To clear all contacts from a list, you need to create a bulk activity to do.  Please refer to the bulk activity documentation for more details.

Deleting a List

A Contact List is deleted by issuing an HTTP DELETE to the entry's URI. The call will return 204 No Content if it succeeds.

Contact List Data Format