Bulk Activities - Export Contacts Endpoint

Use this endpoint to create asynchronous background jobs that exports the members of a specified contact list to a comma separated value (CSV) file.

Methods:

Click a method to view its documentation

POST

DescriptionTOP

Privileges required: contacts:write

Export the members of a contact list to a RFC 4180 compliant .CSV file. In the JSON request body you need to specify the following properties:

  • lists array
  • file_type
  • sort_by
  • export_date_added
  • export_added_by
  • column_names

See the Structure section for details and values for these properties.

column_names array

The column_names array lists the contact properties to include in the exported file. See the JSON Structure table below for valid column names to use. If the first contact does not have a valid email address, then the request fails and no contacts are exported. "Email" must be included in column_names, or the activity will fail.  

Deprecated column_names

The following columns names have been deprecated for export as of the May 5, 2014 update:

  • SUB ZIP/POSTAL CODE
  • MIDDLE NAME
  • US STATE/CA PROVINCE

Existing integrations using these column names will not return errors, but the API ignores these columns.

Export system generated lists

You can export the following system generated contact lists that are filtered by contact status by specifying them as follows in the lists array (include only a single list in the array):

  • active
  • opted-out
  • removed

View contact status definitions here.

Activity status

You can poll the URI returned in the response's location header to monitor the status of the export activity. You must include the access_token and api_key when making a GET call to the activity status report endpoint:

https://api.constantcontact.com/v2/activities/<activity_id>?api_key=<api_key>

The activity has finished once the status is returned as either COMPLETE or ERROR. The activity status response structure is detailed here

How to get the exported file

Once the activity completes processing (status = COMPLETE or ERROR in the activity status report), the status report will also include the file_name property, which is the URL where the file is hosted. The value of this property is a URI that points to the location of the exported file. To retrieve the file, make a GET call to the URI, be sure to include the access_token and api_key in the call. 

GET <file_name>?api_key=<api_key>

POST: https://api.constantcontact.com/v2/activities/exportcontacts

name

type

default

description

api_key

query

REQUIRED; The API key for the application

Example JSON Request BodyTOP

{
"file_type": "CSV",
	"sort_by": "EMAIL_ADDRESS",
	"export_date_added": true,
	"export_added_by": true,
	"lists": [
		"6"
	],
	"column_names": [
		"Email",
		"First Name",
		"Last Name",
		"Job Title",
		"Company Name",
		"Work Phone",
		"Home Phone",
		"Address Line 1",
		"Address Line 2",
		"Address Line 3",
		"City",
		"State",
		"Country",
		"Zip/Postal Code",
		"Custom field 1",
		"Custom field 3",
		"Custom field 6",
		"Custom field 15"
	]
}

Response CodesTOP

code

description

201

Request was successful

400

Bad Request; Error in validating a contact

401

Authentication failure

429

We cannot complete your request because you have too many requests in progress.

500

Internal server error occurred

StructureTOP

property

type(max length)

description

column_names

array

REQUIRED. Contains a list of the contact properties (column names) to include in the exported file. Valid column names are as follows, and are case sensitive:

  • Email
  • First Name
  • Last Name
  • Job Title
  • Company Name
  • Work Phone
  • Home Phone
  • Address Line 1 to 3
  • City
  • State
  • Country
  • Zip/Postal Code
  • Custom field 1 to 15

export_added_by

boolean

If set to true, this property adds a column showing who added/removed the contact to/from the list

export_date_added

boolean

If set to true, this property adds a column showing the date that each contact was added to list

file_type

string

REQUIRED. Specifies the format of the export file; CSV is only supported value at this time.

lists

array

REQUIRED. Although this is an array, only one listId is supported. Specifies the contact list to export by listId or by on of the following system generated list names:

  • active
  • opted-out
  • removed
List names are case-insensitive.

sort_by

string

REQUIRED. Defines the sort order of the export file, as follows:

  • EMAIL_ADDRESS - ascending a to z sort by email address
  • DATE_DESC - descending numerical sort by date contact was added to the list

Response StructureTOP

property

type(max length)

description

contact_count

string

Displays the number of contacts that were processed, and is meaningful only after the activity is completed; the value is not predictable if the activity has not yet been processed. (Read Only)

error_count

string

Displays the number of errors encountered, and is meaningful only after the activity is completed; the value is not predeictable if the activity has not yet been processed. (Read Only)

id

string

Unique ID for the activity (Read Only)

type

string

EXPORT_CONTACTS - export contacts to a supported file type (Read Only)

Example ResponseTOP

{
"id": "a07e1ilb9z7hdeo0iin",
"type": "EXPORT_CONTACTS",
"error_count": 0,
"contact_count": 1350
}