Export Contacts to a CSV File

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 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: `first_name` `last_name` `contact_id` `email_address` `email_lists` `phone_number` `company_name` `job_title` `social_profiles` `website` `tag` `notes` `street` `street_1` `street_2` `city` `state` `intl_state` `zip` `country` `anniversary` `birthday` `birthday_day` `birthday_month` `source_name` `created_at` `updated_at` `email_optin` `email_permission` `email_update_source` `email_optin_source` `email_optin_date` `email_optout_date` `email_optout_source` `email_optout_reason` `sms_number` `sms_consent_date` `sms_status` 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`. 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`.

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:writeAuthorization 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.

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:writeAuthorization 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.

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!

Tagsbulk_activity file_export Segments