Home › Constant Contact Web Service APIs › REST API Reference

Bulk Activity: Collection of Activities

Tue, 04/15/2008 - 12:45 — webservices

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). To manage individual contacts or small sets of contacts, use the Contacts Collection API resource. (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">
  <link href="/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz" rel="edit" />
  <id>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>

Creating an Add Contacts/Remove Contacts Activity

A new Activity is created by making an HTTP POST to the activity collection URI. In contrast to the Contact List, the Activity POST body is not an Atom Entry. Instead it is several named parameters encoded with one of the HTML FORM content types, either application/x-www-form-urlencoded or multipart/form-data. So the data passed in the POST body is the same as that produced by a FORM with the ENCTYPE attribute set to that type.

Constructing an application/x-www-form-urlencoded Request

The basics of how to construct an application/x-www-form-urlencoded request are simple:

  1. Parameter names and values are escaped. Space characters are replaced by `+', and then reserved characters are escaped as described in [RFC1738], section 2.2: Non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A').
  2. The parameter name is separated from the value by `=' and name/value pairs are separated from each other by `&'.
  3. To use paramter values that contain delimiter characters, such as a comma, you need to enclose the value in double quotes, then encode the value.  For example, to use a parameter value of 'Boston, MA', you need to use '%22Boston%2C%20MA%22'. 

Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an application/x-www-form-urlencoded request are in the HTML specification.

The following example shows the parameters used to upload the Email Address, First Name and Last Name of three contacts (Fred Test, Joan Test and Ann Test) to two Contact Lists in the joesflowers account. Note that the three contacts are submitted in a single invocation of the Activities resource.

  activityType=SV_ADD
  &data=Email+Address%2CFirst+Name%2CLast+Name%0A
  wstest3%40example.com%2C+Fred%2C+Test%0A
  wstest4%40example.com%2C+Joan%2C+Test%0A
  wstest5%40example.com%2C+Ann%2C+Test
  &lists=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F2
  &lists=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F5

application/x-www-form-urlencoded Parameters

Name Allowed values Description
activityType ADD_CONTACTS, SV_ADD, ADD_CONTACT_DETAIL, REMOVE_CONTACTS_FROM_LISTS The type of activity to create. NOTE: When adding subscribers, the system will determine, based upon the data being uploaded, whether the Activity is an ADD_CONTACTS (which=SV_ADD) or ADD_CONTACT_DETAIL, but a type must still be specified.
data string The data to be uploaded. This will usually include data for multiple contacts. (If you are submitting a single contact, please see the Contacts Collection resource). The uploaded data for the Activities resource may be in Notepad (.TXT), or Other (.CSV) format. MS Excel (.XLS) file data must be uploaded using multipart/form-data. The format of the upload data is described in a support FAQ.
lists URI (one or more) The list to which data is uploaded. The list should be a list id URI as referenced in the Contact Lists collection.

Constructing a multipart/form-data Request

When using FORMs, you must use enctype="multipart/form-data" when using <input type="file">. Similarly, when uploading a complete file of data, particularly binary data like MS Excel spreadsheets, you must use a multipart/form-data request. Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an multipart/form-data request are in the HTML specification and RFC 2388.

multipart/form-data Parameters

Name Allowed values Description
activityType ADD_CONTACTS, SV_ADD, ADD_CONTACT_DETAIL, REMOVE_CONTACTS_FROM_LISTS The type of activity to create. NOTE: When adding subscribers, the system will determine, based upon the data being uploaded, whether the Activity is an ADD_CONTACTS (which=SV_ADD) or ADD_CONTACT_DETAIL, but a type must still be specified.
dataFile file The data to be uploaded. This will usually include data for multiple contacts. (If you are submitting a single contact, please see the Contacts Collection resource). The uploaded data for the Activities resource may be in Notepad (.TXT), or Other (.CSV) format. MS Excel (.XLS) file data must be uploaded using multipart/form-data. The format of the upload data is described in a support FAQ.
lists URI (one or more) The list the data is to uploaded to. The list should be a list id URI as referenced in the Contact Lists collection.

If the new activity 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 activity, and the entity body returned will be the minimal entry for the activity, including server-generated values like ids and links: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz</id>
  <title type="text"></title>
  <updated>2008-04-29T19:35:54.923Z</updated>
</entry>

Creating a Clear Contacts Activity

A new Activity is created by making an HTTP POST to the activity collection URI. In contrast to the Contact List, the Activity POST body is not an Atom Entry. Instead it is several named parameters encoded with one of the HTML FORM content types, either application/x-www-form-urlencoded or multipart/form-data. So the data passed in the POST body is the same as that produced by a FORM with the ENCTYPE attribute set to that type.

The "Clear Contacts" function works like the "Remove" function, except that you don't have to provide a list of email addresses that you wish to remove.  Select the lists you wish to clear carefully. If you clear contacts from all lists, you will not have any contacts left in your Constant Contact account.

You should refrain from additional operations on the list you are clearing until the job is complete. For example, adding contacts to the list before the clear contacts activity is complete may result in those new contacts being cleared when the activity is run.

Constructing an application/x-www-form-urlencoded Request

The basics of how to construct an application/x-www-form-urlencoded request are simple:

  1. Parameter names and values are escaped. Space characters are replaced by `+', and then reserved characters are escaped as described in [RFC1738], section 2.2: Non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A').
  2. The parameter name is separated from the value by `=' and name/value pairs are separated from each other by `&'.
  3. To use paramter values that contain delimiter characters, such as a comma, you need to enclose the value in double quotes, then encode the value.  For example, to use a parameter value of 'Boston, MA', you need to use '%22Boston%2C%20MA%22'.

Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an application/x-www-form-urlencoded request are in the HTML specification.

The following example shows the parameters used to clear two contact lists, identified by ID's 2 and 5. Note that two contact lists are submitted in a single invocation of the Activities resource.

  activityType=CLEAR_CONTACTS_FROM_LISTS
  &lists=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F2
  &lists=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F5

application/x-www-form-urlencoded Parameters

Name Allowed values Description
activityType CLEAR_CONTACTS_FROM_LISTS The type of activity to create.  When clearing subscribers from the list, they will not be deleted, only removed from the list(s) specified. NOTE:  "Named" lists cannot be cleared. These incldude "Do-Not-Mail", "Removed", "Awaiting Confirmation", "All" and "Active". If an attempt to clear one of these lists (or another non-existant list) is made, the request will fail with a "400 Bad Request"
lists URI (one or more) The list to clear The list should be a list id URI as referenced in the Contact Lists collection.

Constructing a multipart/form-data Request

When using FORMs, you must use enctype="multipart/form-data" when using <input type="file">. Similarly, when uploading a complete file of data, particularly binary data like MS Excel spreadsheets, you must use a multipart/form-data request. Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an multipart/form-data request are in the HTML specification and RFC 2388.

multipart/form-data Parameters

Name Allowed values Description
activityType CLEAR_CONTACTS_FROM_LISTS The type of activity to create.  When clearing subscribers from the list, they will not be deleted, only removed from the list(s) specified. NOTE:  "Named" lists cannot be cleared. These incldude "Do-Not-Mail", "Removed", "Awaiting Confirmation", "All" and "Active". If an attempt to clear one of these lists (or another non-existant list) is made, the request will fail with a "400 Bad Request"
lists URI (one or more) The list to clear. The list should be a list id URI as referenced in the Contact Lists collection.

If the new activity 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 activity, and the entity body returned will be the minimal entry for the activity, including server-generated values like ids and links: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz</id>
  <title type="text"></title>
  <updated>2008-04-29T19:35:54.923Z</updated>
</entry>

Creating an Export Contacts Activity

A new Activity is created by making an HTTP POST to the activity collection URI. In contrast to the Contact List, the Activity POST body is not an Atom Entry. Instead it is several named parameters encoded with one of the HTML FORM content types, either application/x-www-form-urlencoded or multipart/form-data. So the data passed in the POST body is the same as that produced by a FORM with the ENCTYPE attribute set to that type.

Constructing an application/x-www-form-urlencoded Request

The basics of how to construct an application/x-www-form-urlencoded request are simple:

  1. Parameter names and values are escaped. Space characters are replaced by `+', and then reserved characters are escaped as described in [RFC1738], section 2.2: Non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A').
  2. The parameter name is separated from the value by `=' and name/value pairs are separated from each other by `&'.
  3. To use paramter values that contain delimiter characters, such as a comma, you need to enclose the value in double quotes, then encode the value.  For example, to use a parameter value of 'Boston, MA', you need to use '%22Boston%2C%20MA%22'.

Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an application/x-www-form-urlencoded request are in the HTML specification.

The following example shows the parameters used to export the Email Address, First Name and Last Name of three contacts (Fred Test, Joan Test and Ann Test) from a list in the joesflowers account.

    activityType=EXPORT_CONTACTS&fileType=CSV&exportOptDate=true&exportOptSource=true
    &exportListName=true&sortBy=DATE_DESC
    &columns=EMAIL%20ADDRESS&columns=FIRST%20NAME&columns=LAST%20NAME
    &listId=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F2

application/x-www-form-urlencoded Parameters

Name Allowed values Description
activityType EXPORT_CONTACTS The type of activity to create.
listId URI The list the data is exported from. The list should be a list id URI as referenced in the Contact Lists collection. System defined lists, such as 'do-not-mail' are supported.
fileType CSV, TXT Type of file to be exported
exportOptDate true, false true to include the Add/Remove Date in the export file, false to not include it
exportOptSource true, false true to include the Added/Removed By (source of add or remove) in the export file, false to not include it
exportListName true, false true to include the List Name in the export file, false to not include it
sortBy EMAIL_ADDRESS, DATE_DESC EMAIL_ADDRESS to sort the list by email address in ascending order. DATE_DESC will sort the contacts by the Date in descending order
columns FIRST NAME, MIDDLE NAME, LAST NAME, JOB TITLE, COMPANY NAME, WORK PHONE, HOME PHONE, ADDRESS LINE 1, ADDRESS LINE 2, ADDRESS LINE 3, CITY, STATE, STATE/PROVINCE (US/CANADA), COUNTRY, POSTAL CODE, SUB POSTAL CODE, CUSTOM FIELD 1, CUSTOM FIELD 2, CUSTOM FIELD 3, CUSTOM FIELD 4, CUSTOM FIELD 5, CUSTOM FIELD 6, CUSTOM FIELD 7, CUSTOM FIELD 8, CUSTOM FIELD 9, CUSTOM FIELD 10, CUSTOM FIELD 11, CUSTOM FIELD 12, CUSTOM FIELD 13, CUSTOM FIELD 14, CUSTOM FIELD 15 URL encoded, multi-valued list of which optional fields to include in the exported file. (EMAIL ADDRESS is always included in the exported file). The names are the same as those used in files for upload. See the support FAQ for details. Note that the field names include spaces, which must be properly encoded in the request. Comma-separated list of all the fields to be included in the exported file.

Constructing a multipart/form-data Request

When using FORMs, you must use enctype="multipart/form-data" when using <input type="file">. Similarly, when uploading a complete file of data, particularly binary data like MS Excel spreadsheets, you must use a multipart/form-data request. Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an multipart/form-data request are in the HTML specification and RFC 2388.

multipart/form-data Parameters

Name Allowed values Description
activityType EXPORT_CONTACTS The type of activity to create.
listId URI The list the data is exported from. The list should be a list id URI as referenced in the Contact Lists collection. System defined lists, such as 'do-not-mail' are supported.
fileType CSV, TXT Type of file to be exported
exportOptDate true, false true to include the Add/Remove Date in the export file, false to not include it
exportOptSource true, false true to include the Added/Removed By (source of add or remove) in the export file, false to not include it
exportListName true, false true to include the List Name in the export file, false to not include it
sortBy EMAIL_ADDRESS, DATE_DESC EMAIL_ADDRESS to sort the list by email address in ascending order. DATE_DESC will sort the contacts by the Date in descending order
columns FIRST NAME, MIDDLE NAME, LAST NAME, JOB TITLE, COMPANY NAME, WORK PHONE, HOME PHONE, ADDRESS LINE 1, ADDRESS LINE 2, ADDRESS LINE 3, CITY, STATE, STATE, STATE/PROVINCE (US/CANADA), COUNTRY, POSTAL CODE, SUB POSTAL CODE, CUSTOM FIELD 1, CUSTOM FIELD 2, CUSTOM FIELD 3, CUSTOM FIELD 4, CUSTOM FIELD 5, CUSTOM FIELD 6, CUSTOM FIELD 7, CUSTOM FIELD 8, CUSTOM FIELD 9, CUSTOM FIELD 10, CUSTOM FIELD 11, CUSTOM FIELD 12, CUSTOM FIELD 13, CUSTOM FIELD 14, CUSTOM FIELD 15 URL encoded, multi-valued list of which optional fields to include in the exported file. (EMAIL ADDRESS is always included in the exported file). The names are the same as those used in files for upload. See the support FAQ for details. Note that the field names include spaces, which must be properly encoded in the request.

If the new activity 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 activity, and the entity body returned will be the minimal entry for the activity, including server-generated values like ids and links.

After the system has finished processing the Export activity, retrieving the activity entry will return a complete entry that includes the status of the job. If the job completed successfully, it will also contain a link to the exported file. See the example below: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp</id>
  <title type="text">EXPORT_CONTACTS: http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1...
  <updated>2008-06-27T13:10:59.944Z</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/a07e1gpfcd3fhysynnp">
      <Type>EXPORT_CONTACTS</Type>
      <Status>COMPLETE</Status>
      <FileName>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp.csv</FileName>
      <TransactionCount>0</TransactionCount>
      <Errors></Errors>
      <RunStartTime>2008-06-27T13:10:59.321Z</RunStartTime>
      <RunFinishTime>2008-06-27T13:10:59.944Z</RunFinishTime>
      <InsertTime>2008-06-27T13:10:57.349Z</InsertTime>
    </Activity>
  </content>
  <link href="http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp.csv" rel="edit-media" />
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/activities</id>
    <title type="text">Activity Collection for customer: joesflowers</title>
    <link href="" />
    <link href="" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2008-06-27T16:29:26.723Z</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.