Bulk Activity: Collection of Activities

webservices · ‎03-25-2011

Constant Contact encourages the use of asynchronous background jobs to manage large collections of data. The Bulk Activity collection is used to create and manage those jobs, called Activities. Currently, the collection allows you to create jobs to add, remove and download contacts from contact lists. It also allows you to check the status of a customer's activities and to see when an activity is completed and whether it succeeded or failed. A single "call" to the "Activities" resource generally operates on a set of contacts. The data for that set of contacts is held in a formatted file, described below.

The Activities resource is designed to be used only with large sets of contacts (ie. 25 or more). (As discussed in the Constant Contact API Terms and Conditions, intentional and unintentional misuse of this bulk API to frequently manage individual contacts or small sets of contacts is subject to API access or account termination).

Retrieving a Collection of Activities

To retrieve the collection of activities for the UserName joesflowers, you perform an HTTP GET on the collection URI https://api.constantcontact.com/ws/customers/joesflowers/activities. For the fictional joesflowers in this example, this returns the following XML document, showing a single activity:

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities</id>
  <title type="text">Bulk Activity</title>
  <link href="" />
  <link href="" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2008-04-29T19:31:00.545Z</updated>
  <entry>
    <link href="/ws/customers/joesflowers/activities/a07e1ffaxjxffmvj6qd" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjxffmvj6qd</id>
    <title type="text"></title>
    <updated>2008-04-29T19:30:15.637Z</updated>
    <content type="application/vnd.ctct+xml">
      <Activity xmlns="http://ws.constantcontact.com/ns/1.0/"
        id="http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjxffmvj6qd">
        <Type>ADD_CONTACT_DETAIL</Type>
        <Status>COMPLETE</Status>
        <Errors>
          <Error>
            <LineNumber>3</LineNumber>
            <EmailAddress>test2@test.com</EmailAddress>
            <Message>Unknown US/Canadian state/prov "Test2"</Message>
          </Error>
          <Error>
            <LineNumber>4</LineNumber>
            <EmailAddress>test3@test.com</EmailAddress>
            <Message>Unknown US/Canadian state/prov "Test3"</Message>
          </Error>
        </Errors>
        <FileName></FileName>
        <TransactionCount>1</TransactionCount>
        <RunStartTime>2008-06-25T15:48:01.615Z</RunStartTime>
        <RunFinishTime>2008-06-25T15:48:03.040Z</RunFinishTime>
        <InsertTime>2008-06-25T15:47:37.199Z</InsertTime>
      </Activity>
    </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 Activity element which describes the attributes of a particular activity. The structure of the Activity element is described below.

Retrieving the Details of an Individual Activity

An individual activity 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">
http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz</id>
  <title type="text"></title>
  <updated>2008-04-29T19:36:10.948Z</updated>

  <content type="application/vnd.ctct+xml">
    <Activity xmlns="http://ws.constantcontact.com/ns/1.0/"
      id="http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz">
      <Type>ADD_CONTACT_DETAIL</Type>
      <Status>COMPLETE</Status>
      <Errors>
        <Error>
          <LineNumber>3</LineNumber>
          <EmailAddress>test2@test.com</EmailAddress>
          <Message>Unknown US/Canadian state/prov "Test2"</Message>
        </Error>
        <Error>
          <LineNumber>4</LineNumber>
          <EmailAddress>test3@test.com</EmailAddress>
          <Message>Unknown US/Canadian state/prov "Test3"</Message>
        </Error>
      </Errors>
      <FileName></FileName>
      <TransactionCount>1</TransactionCount>
      <RunStartTime>2008-04-29T19:36:08.894Z</RunStartTime>
      <RunFinishTime>2008-04-29T19:36:10.948Z</RunFinishTime>
      <InsertTime>2008-04-29T19:35:54.923Z</InsertTime>
    </Activity>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/activities</id>
    <title type="text">Bulk Activity</title>
    <link href="" />
    <link href="" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2008-04-29T19:45:24.131Z</updated>
  </source>
</entry>

Updating an Activity

Activity updates are not currently permitted.

Deleting an Activity

Activity deletes are not currently permitted.

Activity Data Format

Name	Allowed values	Description
Type	ADD_CONTACTS, ADD_CONTACT_DETAIL, REMOVE_CONTACTS_FROM_LISTS, EXPORT_CONTACTS, CLEAR_CONTACTS_FROM_LISTS	The type of activity.
Status	UNCONFIRMED, PENDING, QUEUED, RUNNING, COMPLETE, ERROR	The current status of the activity.
FileName	string	The file name associated with the activity (may be empty).
TransactionCount	integer	For completed jobs, the number of addresses processed.
Error	string
RunStartTime	Date/Time	The time the activity started to run.
RunFinishTime	Date/Time	The time the activity completed its run.
InsertTime	Date/Time	The time the activity was created.