A new Activity is created by making an HTTP POST to the activity collection URI, below.
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') or just LF (i.e. '%0A').
2. The parameter name is separated from the value by `=' and name/value pairs are separated from each other by `&'.
3. To use parameter 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 |
EMAIL ADDRESS, 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
|
|---|
| 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. |
|---|
*SUB POSTAL CODE will be ignored if supplied. It is now unsupported and is a read-only field.
Currently, we can add up to 1.9MB of encoded data in the string (about 2 million characters). Larger data strings should be broken up and added in batches.
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 should maintain the following format:
EMAIL ADDRESS, 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
|
|---|
| 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 Contacts List 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> <updated>2008-04-29T19:35:54.923Z</updated>
</entry>
