webservices

Creating an Export Contacts Activity

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

A new Activity is created by making an HTTP POST to the activity collection URI:

 

https://api.constantcontact.com/ws/customers/USERNAME/activities

 

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.  There is no need to specify a column for email address, since the database always exports the email addresses of contacts as column 1 in an export acitivty.

 

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

application/x-www-form-urlencoded Parameters

 

 

NameAllowed valuesDescription
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.

 

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>