How to export contacts to a CSV file using the activity endpoint.

Export contacts to a CSV file using the /activities/contact_exports endpoint. The request body defines which contacts and contact properties to export.

Building the JSON Request Body

The JSON request body defines the contacts (the rows in the CSV file), and the contact properties (the columns in the CSV file) being exported.

Define the Contacts to Export

There are three mutually exclusive ways of specifying which contacts to export using this endpoint:

  1. By Contact ID - you can specify up to 500 individual contacts to export by including an array of contact_ids.
  2. By List ID - you can export the contacts that are members up to 50 contact lists, by including an array of up to 50 list_ids.
  3. All contacts in the account - If you do not use any of the first three methods to specify which contacts to export, all contacts in the user’s account will be exported.

Use only one of these options in each request.

Filter Contacts by Status

After specifying the contacts to export, you can use the optional status property to filter and export only the contacts with a specific status value; status accepts one of the following values:

  • active
  • unsubscribed
  • removed

Define the Contact Fields to Export

You must specify at least one of the following fields to include in the exported file; the request will fail otherwise:

  • first_name
  • last_name
  • email_address
  • email_lists
  • phone_number
  • company_name
  • job_title
  • social_profiles
  • website
  • tag
  • notes
  • street
  • city
  • state
  • zip
  • country
  • anniversary
  • birthday
  • birthday_day
  • birthday_month
  • source_name
  • created_at
  • updated_at
  • email_optin
  • email_permission

Refer to the contact object definition in the API Reference section of the portal for details about each property.

Example Request Body

This request exports the email_address, first and last names, and the updated_at fields for the 3 contacts listed in the contact_ids array:

  "contact_ids": [
  "fields": [


    "activity_id": "993d7bc0-c3e5-11e7-a1be-90b11c34fb55",
    "state": "initialized",
    "created_at": "2017-11-07T13:00:54-05:00",
    "updated_at": "2017-11-07T13:00:54-05:00",
    "percent_done": 1,
    "activity_errors": [],
    "status": {},
    "_links": {
        "self": {
            "href": "/v3/activities/993d7bc0-c3e5-11e7-a1be-90b11c34fb55"

Check the Activity Status

Check on the activity status using link to the activity status provided in the _links section of the response. The activity_id for your request is provided in the href link. To retrieve the status, make the following GET call:


Endpoint Requirements

Authorization scopes: contact_data

Accessing the Export File

Once the activity completes processing (status = COMPLETE or ERROR in the activity status report), the status report provides the URL to the export file in the _links -> results section. To retrieve the file, make a GET call to the URI.

"_links": {
    "self": {
      "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
    "results": {
      "href": "/v3/activities/contacts_exports/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"

Example Request


Endpoint Requirements

Authorization scopes: contact_data


$request = new HttpRequest();

  '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 \
  '{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()
  .addHeader("Accept", "text/csv")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .addHeader("Cache-Control", "no-cache")

Response response = client.newCall(request).execute();

Example Response

    "activity_id": "{activity_id}",
    "state": "initialized",
    "created_at": "2017-11-07T13:00:54-05:00",
    "updated_at": "2017-11-07T13:00:54-05:00",
    "percent_done": 1,
    "activity_errors": [],
    "status": {},
    "_links": {
        "self": {
            "href": "/v3/activities/{activity_id}"