Make a POST request to the /activities/contact_exports
endpoint to create a CSV export activity. You can choose to export all contacts in your account (default) or choose to from parameters to filter which contacts to export. After Constant Contact finishes processing the activity, use the results
object in the response body to retrieve the CSV file.
Step 1:Create an Export Activity
Use the JSON request body to define the contacts (rows in the CSV file) and the contact properties (columns in the CSV file) you want to export.
Request Body Schema
Schema Property | Data Type | Description |
---|---|---|
contact_ids |
Array[string] Max Items: 500 | Exports up to 500 contacts using an array of contact_id values. This property is mutually exclusive all other filtering criteria except status . |
list_ids |
Array[string] Max Items: 50 | Exports all contacts inside up to 50 contact lists using an array of list_id values. This property is mutually exclusive all other filtering criteria except status and exclude . |
segment_ids |
integer Max Items: 1 | Exports all contacts that for a single segment using the segment_id value. This property is mutually exclusive with all other filtering criteria. |
tag_ids |
integer | Exports contacts assigned one or more of the specified tags (tag_id ). This property is mutually exclusive with all other filtering criteria. |
new_subscriber |
boolean | Exports all contacts that subscribed within the last 30 days. This property is mutually exclusive with all other filtering criteria except list_ids and exclude . |
fields |
Array[string] | Restricts the export to only include specific contact fields. By default, this method exports all contact fields including custom fields. Possible field values include:
email_address to successfully export email_optin_source , email_optin_date , email_optout_source , email_optout_date , or email_optout_reason .
For more information on the behavior of each contact field, see the Contacts API Reference.
|
status |
string | Allows you to export only contacts that have a specific status. Possible status values are active , unsubscribed , or removed . Applicable alone or with either contact_ids or list_ids . |
exclude |
Array[string] | Excludes up to 50 contacts (contact_id ) from being exported. Applicable alone or with either new_subscriber or list_ids . |
- Invalid
contact_id
orlist_id
values result in the activity entering afailed
state when Constant Contact processes the CSV export activity. - Invalid values in the
fields
array are omitted from the exported CSV file. For example, if you use thefields
array to only export the fields "email_address" and "example_invalid_field", Constant Contact will export a CSV file that only contains the column "email_address".
Example POST CSV Export Request
POST https://api.cc.email/v3/activities/contact_exports
User privileges: contacts:write
Authorization scopes: contact_data
This example request exports the email_address
, first_name
, last_name
, and updated_at
fields for the three contacts in the contact_ids
array.
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/activities/contact_exports');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
'Authorization' => 'Bearer {access_token}',
'Content-Type' => 'application/json',
'Accept' => 'application/json'
));
$request->setBody(' {
"contact_ids": [
"04fe9a97-a579-43c5-bb1a-58ed29bf0a6a",
"af424130-f968-11e8-9c64-fa163e6b01c1",
"d8061a00-eda7-11e8-ae8d-fa163e6b01c1"
],
"fields": [
"email_address", "first_name", "last_name", "updated_at"
],
"status": "active"
}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
curl -X POST \
https://api.cc.email/v3/activities/contact_exports \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d ' {
"contact_ids": [
"04fe9a97-a579-43c5-bb1a-58ed29bf0a6a",
"af424130-f968-11e8-9c64-fa163e6b01c1",
"d8061a00-eda7-11e8-ae8d-fa163e6b01c1"
],
"fields": [
"email_address", "first_name", "last_name", "updated_at"
],
"status": "active"
}'
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, " { \r\n \"contact_ids\": [\r\n \"04fe9a97-a579-43c5-bb1a-58ed29bf0a6a\",\r\n \"af424130-f968-11e8-9c64-fa163e6b01c1\",\r\n \"d8061a00-eda7-11e8-ae8d-fa163e6b01c1\"\r\n ],\r\n \"fields\": [\r\n \"email_address\", \"first_name\", \"last_name\", \"updated_at\"\r\n ],\r\n \"status\": \"active\"\r\n}");
Request request = new Request.Builder()
.url("https://api.cc.email/v3/activities/contact_exports")
.post(body)
.addHeader("Accept", "application/json")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access_token}")
.build();
Response response = client.newCall(request).execute();
Step 2:Retrieve the CSV File
After you successfully create a CSV export activity, the response body returns a _links
object that contains a self link and a results link.
- Use the
self
object link to check the state of the activity and confirm that it iscompleted
. For more information, see Get the Status of a Bulk Activity. - Use the
results
object link to retrieve the CSV file.
POST CSV Export Example Response Body
{
"activity_id": "118e461a-0c9e-11ea-b1f5-fa163e6b01c1",
"state": "completed",
"created_at": "2019-11-21T15:32:42-05:00",
"updated_at": "2019-11-21T15:32:42-05:00",
"percent_done": 100,
"activity_errors": [],
"status": {
"items_total_count": 149,
"items_completed_count": 149
},
"_links": {
"self": {
"href": "/v3/activities/118e461a-0c9e-11ea-b1f5-fa163e6b01c1"
},
"results": {
"href": "/v3/contact_exports/118ceeaa-0c9e-11ea-b1f5-fa163e6b01c1"
}
}
}
After Constant Contact finishes processing the activity and it returns a completed
state, use the link in the results
object to make a GET request and retrieve the CSV file.
Example GET CSV Request
GET https://api.cc.email/v3/contact_exports/{file_export_id}
User privileges: contacts:write
Authorization scopes: contact_data
This example GET request retrieves a CSV file after a successful CSV export activity. The example response body uses the same rows and columns specified in the example POST CSV export activity.
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contact_exports/{file_export_id}');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
'Accept' => 'text/csv',
'Content-Type' => 'application/json',
'Authorization' => 'Bearer {access_token}',
'Cache-Control' => 'no-cache'
));
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
curl -X GET \
'https://api.cc.email/v3/contact_exports/{file_export_id}' \
-H 'Accept: text/csv' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Cache-Control: no-cache'
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.cc.email/v3/contact_exports/{file_export_id}")
.get()
.addHeader("Accept", "text/csv")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access_token}")
.addHeader("Cache-Control", "no-cache")
.build();
Response response = client.newCall(request).execute();
Get CSV Example Response Body
First name,Last name,Email address - other,Updated At
Dipali,Nipperdipper,ddipper@example.com,2018-11-29 15:10:15 -0500
Jake,Dodge,jdodge@jdogepancakes.com,2019-11-25T16:29:13.057 -0500
Jack,Smith,jacksbbq@example.com,2019-11-25T16:29:13.057 -0500