You can import contacts from another source into a Constant Contact account using a CSV payload or a JSON payload. The CSV import endpoint is POST /activities/contacts_file_import
. The JSON import endpoint is POST /activities/contacts_json_import
.
You can use these endpoints to import new contacts and update existing contacts when syncing local data with Constant Contact. These endpoints use the email addresses you provide in the import to determine if each contact is new or not. When you import an existing contact, these endpoints only update the contact properties you include in the import request.
For more information on syncing contact data, see the Guidelines for Importing Contacts.
Import Limitations
The following limitations apply to the import methods:
- File size: The size of the imported CSV file or JSON payload must be less than 4 megabytes (MB).
- Number of contacts: The total number of rows in the CSV import file cannot exceed 40,000 (39,999 contact rows plus a headings row). The total number of contacts in the JSON payload cannot exceed 40,000.
If the file size exceeds 4 MB, only the contacts contained in the first 4 MB (and in lines ≤40k) are processed.
About permission_to_send and Imported Contacts
Permission to send signifies the type of relationship an account owner has with a contact. It is important for compliance with US and international anti-spam law. See Constant Contact’s Email Permission Policy for complete information.
When importing contacts:
permission_to_send
is set toImplicit
for all new contacts created in an import activity.permission_to_send
is not changed for any existing contacts included in an import activity.
Import Contacts from a CSV file
Make a POST call to the /activities/contacts_file_import
multipart/form-data endpoint to import contacts into Constant Contact using a CSV file. This method requires a multipart/form-data request body that contains the file
and list_ids
properties.
- file - The contacts you are importing as a CSV file containing contact data.
- list_ids - The contact lists you want to add all imported contacts to as an array of contact
list_id
values. You must include at least onelist_id
value and cannot include more than 50list_id
values.
CSV File Content
The import file must be in comma-separated value (CSV) format. Create the CSV file adding contact properties to the CSV header and your contact data as rows in the CSV. You can also include custom fields in the CSV file. The CSV file must contain an email
header. This method identifies each unique contact using their email address.
You can use the following contact properties in the CSV file:
Header Column Name | Column Attributes | Description |
---|---|---|
first_name |
optional, Max. Length:50 | The first name of the contact. |
last_name |
optional, Max. Length:50 | The last name of the contact. |
job_title |
optional, Max. Length:50 | The job title of the contact. |
company_name |
optional, Max. Length:50 | The name of the company where the contact works. |
anniversary |
optional | The anniversary date for the contact. For example, this value could be the date when the contact first became a customer of an organization in Constant Contact. Valid date formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or M-DD-YYYY. The year must be greater than 1900 and cannot be more than 10 years in the future (with respect to the current year). |
birthday_month |
optional, minimum 1, maximum 12 | The month value for the contact’s birthday. Valid values are from 1 through 12. You must use this column with birthday_day . |
birthday_day |
optional, minimum 1, maximum 31 | The day value for the contact’s birthday. Valid values are from 1 through 31. You must use this column with birthday_month . |
phone |
optional, Max. Length:50 | The phone number for the contact. |
street |
optional, Max. Length:255 | Line one of the street address for the contact. |
street2 |
optional, Max. Length:255 | Line two of the street address for the contact. This value is automatically appended to the street value. |
city |
optional, Max. Length:50 | The name of the city where the contact lives. |
state |
optional, Max. Length:50 | The name of the state or province where the contact lives. |
zip |
optional, Max. Length:50 | A zip or postal code for the contact. |
country |
optional, Max. Length:50 | The name of the country where the contact lives. |
cf:custom_field_name |
optional, Max. Length:255 | This header column name is the name of an existing custom field prefixed with cf: . For example, enter cf:first_name if you have a custom field named “first_name”. As long as you use the cf: prefix, you can import custom fields that use the same name as the contact properties. You can add up to 25 different custom field headings for each contact. |
CSV File Example
Click here to download an example CSV file.
Import Contacts Using JSON
Make a POST call to the /activities/contacts_json_import
endpoint to import contacts using a JSON request payload. This method requires a JSON request body that contains the import_data
and list_ids
arrays.
-
import_data - The contacts you are importing as an array of objects containing contact data.
-
list_ids - The contact lists you want to add all imported contacts to as an array of contact
list_id
strings. You must include at least onelist_id
value and cannot include more than 50list_id
values.
Contact Import Data Format
You can use the following contact properties with each object in the import_data
array:
Property Name | Property Attributes | Description |
---|---|---|
email |
required, string, Max. Length:50 | The email address of the contact. This method identifies each unique contact using their email address. |
first_name |
string, optional, Max. Length:50 | The first name of the contact. |
last_name |
string, optional, Max. Length:50 | The last name of the contact. |
job_title |
string, optional, Max. Length:50 | The job title of the contact. |
company_name |
string, optional, Max. Length:50 | The name of the company where the contact works. |
anniversary |
string, optional, | The anniversary date for the contact. For example, this value could be the date when the contact first became a customer of an organization in Constant Contact. Valid date formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or M-DD-YYYY. The year must be greater than 1900 and cannot be more than 10 years in the future (with respect to the current year). |
birthday_month |
integer, minimum 1, maximum 12, optional | The month value for the contact’s birthday. Valid values are from 1 through 12. You must use this property with birthday_day . |
birthday_day |
integer, minimum 1, maximum 31, optional | The day value for the contact’s birthday. Valid values are from 1 through 31. You must use this property with birthday_month . |
phone |
string, required, Max. Length:50 | The primary phone number for the contact. Default type = home |
home_phone |
string, optional, Max. Length:50 | The home phone number for the contact. Type = home |
work_phone |
string, optional, Max. Length:50 | The work phone number for the contact. Type = work |
other_phone |
string, optional, Max. Length:50 | Another phone number for the contact. Type = other |
street |
string, optional, Max. Length:255 | Line one of the street address for the contact. Default, type = home |
street2 |
string, optional, Max. Length:255 | Line two of the street address for the contact. This value is automatically appended to the street value. Default, type = home |
other_street |
string, optional, Max. Length:255 | Line one of the another street address for the contact. Type = other |
other_street2 |
string, optional, Max. Length:255 | Line two of the other street address for the contact. This value is automatically appended to the other_street value. Type = other |
home_street |
string, optional, Max. Length:255 | Line one of the home street address for the contact. Type = home |
home_street2 |
string, optional, Max. Length:255 | Line two of the street address for the contact. This value is automatically appended to the home_street value. Default type = home |
work_street |
string, optional, Max. Length:255 | Line one of the work street address for the contact. Type = work |
work_street2 |
string, optional, Max. Length:255 | Line two of the street address for the contact. This value is automatically appended to the work_street value. Type = work |
city |
string, optional, Max. Length:50 | The primary city name for the contact. Default, type home |
home_city |
string, optional, Max. Length:50 | The name of the city where the contact lives. Type = home |
work_city |
string, optional, Max. Length:50 | The name of the city where the contact works. Type = work |
other_city |
string, optional, Max. Length:50 | The name of another city where the contact is located. Type = other |
state |
string, optional, Max. Length:50 | The primary name of the state or province for the contact. Default type = home |
other_state |
string, optional, Max. Length:50 | Another name of a state or province for the contact. Type = other |
home_state |
string, optional, Max. Length:50 | The name of the home state or province where the contact lives. Type = home |
work_state |
string, optional, Max. Length:50 | The name of another state or province where the contact works. Type = work |
zip |
string, optional, Max. Length:50 | The primary zip or postal code for the contact. Default, type = home |
home_zip |
string, optional, Max. Length:50 | A zip or postal code for where the contact’s home is located. Type = home |
work_zip |
string, optional, Max. Length:50 | A zip or postal code for where the contact’s works. Type = work |
other_zip |
string, optional, Max. Length:50 | A zip or postal code for another location where the contact is located. Type = other |
country |
string, optional, Max. Length:50 | The name of the country where the contact lives. Default, type = home |
home_country |
string, optional, Max. Length:50 | The name of the country where the contact lives. Type = home |
work_country |
string, optional, Max. Length:50 | The name of the country where the contact works. Type = work |
other_country |
string, optional, Max. Length:50 | Another name of the country where the contact is located. Type = other |
cf:custom_field_name |
string, optional, Max. Length:255 | A contact custom field. The name of this property is dynamic based on the custom fields that you want to import. Use a key-value pair where the key is an existing custom field name prefixed with cf: , and the value is a custom field string value. As long as you use the cf: prefix, you can import custom fields that use the same name as the contact properties. You can import up to 25 custom fields in each contact. |
Import JSON Request Sample
POST https://api.cc.email/v3/activities/contacts_json_import
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/activities/contacts_json_import');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
'Postman-Token' => '23afb38f-650d-4e5c-9eac-798f2a6a10e2',
'cache-control' => 'no-cache',
'Authorization' => 'Bearer {access_token}',
'Content-Type' => 'application/json',
'Accept' => 'application/json'
));
$request->setBody('{
"import_data": [
{
"email": "jjones@example.com",
"first_name": "Joe",
"last_name": "Jones",
"job_title": "Chief Innovation Officer",
"company_name": "RelativeGravity, Inc.",
"birthday_month": 11,
"birthday_day": 24,
"anniversary": "2006-11-15",
"phone": "556-555-5555",
"street": "123 Maple Lane",
"street2": "Apt. 337",
"zip": "60609",
"country": "United States",
"cf:first_name": "Joey",
"cf:vehicle_make_and_model_year": "Tesla S 2017"
},
{
"email": "A.test@example.com",
"first_name": "Anton",
"last_name": "tester",
"job_title": "Software Engineer",
"company_name": "CTCT",
"create_source": "Contact",
"birthday_month": 4,
"birthday_day": 1,
"anniversary": "04/01/2014",
"cf:vehicle_make_and_model_year": "Honda Ridgeline Sport 2014"
}
],
"list_ids": [
"2e73c594-78be-11e9-bfd0-fa163e6b01c1","3a192c16-5ade-11e9-a67b-fa163e6b01c1"
]
}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
curl -X POST \
https://api.cc.email/v3/activities/contacts_json_import \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 188daafb-9ee2-4380-9010-e7f3b4c45e56' \
-H 'cache-control: no-cache' \
-d '{
"import_data": [
{
"email": "jjones@example.com",
"first_name": "Joe",
"last_name": "Jones",
"job_title": "Chief Innovation Officer",
"company_name": "RelativeGravity, Inc.",
"birthday_month": 11,
"birthday_day": 24,
"anniversary": "2006-11-15",
"phone": "556-555-5555",
"street": "123 Maple Lane",
"street2": "Apt. 337",
"zip": "60609",
"country": "United States",
"cf:first_name": "Joey",
"cf:vehicle_make_and_model_year": "Tesla S 2017"
},
{
"email": "A.test@example.com",
"first_name": "Anton",
"last_name": "Smith",
"job_title": "Software Engineer",
"company_name": "RelativeGravity, Inc.",
"birthday_month": 4,
"birthday_day": 1,
"anniversary": "04/01/2014",
"cf:vehicle_make_and_model_year": "Honda Ridgeline Sport 2014"
}
],
"list_ids": [
"2e73c594-78be-11e9-bfd0-fa163e6b01c1","3a192c16-5ade-11e9-a67b-fa163e6b01c1"
]
}'
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"import_data\": [\n {\n \"email\": \"jjones@example.com\",\n \"first_name\": \"Joe\",\n \"last_name\": \"Jones\",\n \"job_title\": \"Chief Innovation Officer\",\n \"company_name\": \"RelativeGravity, Inc.\",\n \"birthday_month\": 11,\n \"birthday_day\": 24,\n \"anniversary\": \"2006-11-15\",\n \"phone\": \"556-555-5555\",\n \"street\": \"123 Maple Lane\",\n \"street2\": \"Apt. 337\",\n \"zip\": \"60609\",\n \"country\": \"United States\",\n \"cf:first_name\": \"Joey\",\n \"cf:vehicle_make_and_model_year\": \"Tesla S 2017\"\n },\n {\n \"email\": \"A.test@example.com\",\n \"first_name\": \"Anton\",\n \"last_name\": \"tester\",\n \"job_title\": \"Software Engineer\",\n \"company_name\": \"CTCT\",\n \"create_source\": \"Contact\",\n \"birthday_month\": 4,\n \"birthday_day\": 1,\n \"anniversary\": \"04/01/2014\",\n \"cf:vehicle_make_and_model_year\": \"Honda Ridgeline Sport 2014\"\n }\n ],\n \"list_ids\": [\n \"2e73c594-78be-11e9-bfd0-fa163e6b01c1\",\"3a192c16-5ade-11e9-a67b-fa163e6b01c1\"\n ]\n}");
Request request = new Request.Builder()
.url("https://api.cc.email/v3/activities/contacts_json_import")
.post(body)
.addHeader("Accept", "application/json")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access_token}")
.addHeader("cache-control", "no-cache")
.addHeader("Postman-Token", "b95d402e-93a7-466d-8dbb-db1afb91a7f2")
.build();
Response response = client.newCall(request).execute();
Response
{
"activity_id": "3c472a68-8218-11e9-b1a7-fa163e56c9b0",
"state": "initialized",
"created_at": "2019-05-29T09:47:01-04:00",
"updated_at": "2019-05-29T09:47:01-04:00",
"source_file_name": "csv_from_json_2019-05-29T09_47_01-04_0020190529-31124-1mhsxhe.csv",
"percent_done": 1,
"activity_errors": [],
"status": {},
"_links": {
"self": {
"href": "/v3/activities/3c472a68-8218-11e9-b1a7-fa163e56c9b0"
}
}
}
Checking the Activity Status for Job Complete
After you send an import request, the V3 API returns a response body that includes an activity_id
and the current status of the import activity. Send a GET request to the /activities/{activity_id} endpoint endpoint to determine when the V3 API has finished importing your contacts. You can also use the URL that the V3 API returns in the href
response body property to send the request.
GET https://api.cc.email/v3/activities/{activity_id}
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data