Make a POST request to the /activities/contact_exports endpoint to create a CSV export activity. After Constant Contact finishes processing the activity, use the results object in the response body to retrieve the CSV file.

You can choose to export all contacts in your account (default) or you can use one of the following contact sources: contact IDs (up to 500 contact_ids), contact lists (up to 50 list_ids), or segment ID (one segment_id).

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 with list_ids, segment_ids, and all_active_contacts.
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 with contact_ids, segment_ids, and all_active_contacts.
segment_ids integer Exports all contacts for a single segment using the segment_id value. This property is mutually exclusive with list_ids, contact_ids, and all_active_contacts.
all_active_contacts boolean Exports all contacts with active as the contact status. This property is mutually exclusive with list_ids, contact_ids, and segment_ids.
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:
  • first_name
  • last_name
  • email_address
  • email_lists
  • phone_number
  • company_name
  • job_title
  • social_profiles
  • website
  • notes
  • street
  • city
  • state
  • zip
  • country
  • anniversary
  • birthday
  • birthday_day
  • birthday_month
  • source_name
  • created_at
  • updated_at
  • email_optin
  • email_permission
  • email_optin_source
  • email_optin_date
  • email_optout_date
  • email_optout_source
  • email_optout_reason
You must export 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.
The initial POST CSV export request may return a 201 success response even if there are errors in your request body:
  • Invalid contact_id or list_id values result in the activity entering a failed 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 the fields 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 is completed. 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

Try it!