Constant Contact Bulk Activities API
Bulk activities endpoints are used to manage large numbers of contacts, lists, and tags.
Bulk activities endpoints are used to manage large numbers of contacts, lists, and tags.
swagger: '2.0'
info:
description: The Constant Contact, Inc. V3 public API, for building integrations with Constant Contact, the leading small-business email marketing platform.
version: 3.0.149
title: AppConnect V3 Account Services Bulk Activities API
contact:
name: webservices@constantcontact.com
license:
name: Private
url: https://www.constantcontact.com/legal/terms-of-use
host: api.cc.email
basePath: /v3
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Bulk Activities
description: Bulk activities endpoints are used to manage large numbers of contacts, lists, and tags.
paths:
/activities:
get:
tags:
- Bulk Activities
summary: GET Activity Status Collection
description: This endpoint returns a collection of activities. Use the state query parameter to include only activities with a specific status (processing, completed, cancelled, failed, or time_out). Use the limit query parameter to define the number of activities returned per page. Learn [more](/api_guide/activity_status.html).
operationId: getActivityStatusCollection
consumes:
- application/json
produces:
- application/json
parameters:
- name: limit
in: query
description: Specifies the number of results displayed per page of output, from 1 - 500, default = 50.
required: false
type: integer
default: 50
maximum: 500
minimum: 1
x-example: 25
- name: state
in: query
description: 'Use this parameter to filter the response to include only activities in one of the following states: cancelled, completed, failed, processing, or timed_out.'
required: false
type: string
enum:
- processing
- completed
- cancelled
- failed
- timed_out
x-example: processing
responses:
'200':
description: Request Successful
schema:
$ref: '#/definitions/Activities'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: The requested resource was not found.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: getAllActivities
/activities/{activity_id}:
get:
tags:
- Bulk Activities
summary: GET an Activity Status
description: This endpoint returns an activity status report.
operationId: getActivity
consumes:
- application/json
produces:
- application/json
parameters:
- name: activity_id
in: path
description: The unique ID of the activity to GET
required: true
type: string
x-example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a
responses:
'200':
description: Request Successful
schema:
$ref: '#/definitions/Activity'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: Resource not found for the activity_id provided
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: getActivityById
/activities/contact_exports:
post:
tags:
- Bulk Activities
summary: Export Contacts to a File
description: Use this method to create an activity that exports contacts and contact details to a CSV file. You can choose to export all contacts in your account (default) or you can use parameters to filter on which contacts to export. After Constant Contact finishes processing the activity, use the `results` link in the response body to retrieve the CSV file.
operationId: postContactsExport
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: A JSON payload that specifies the contacts (rows in the CSV file) and contact properties (columns in the CSV file) you want to export.
required: true
schema:
$ref: '#/definitions/ContactsExport'
responses:
'201':
description: Request successful, queued for processing.
schema:
$ref: '#/definitions/ActivityExportStatus'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: The requested resource was not found.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createExportActivity
/contact_exports/{file_export_id}:
get:
tags:
- Bulk Activities
summary: Retrieve Exported Contacts File
description: "Use this endpoint to retrieve (GET) a CSV file containing exported contacts by providing the `activity_id` of a completed CSV export activity. \n"
operationId: getContactsExport
consumes:
- application/json
produces:
- text/csv
parameters:
- name: file_export_id
in: path
description: 'The unique ID of the exported file provided in the results: section of the export contacts activity response.'
required: true
type: string
x-example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a
responses:
'200':
description: Request Successful
schema:
$ref: '#/definitions/ActivityGetExport'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: The requested resource was not found.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: getCSVExportFile
/activities/contact_delete:
post:
tags:
- Bulk Activities
summary: Delete Contacts in Bulk
description: Use this endpoint to bulk delete contacts in an account. Contacts to delete are specified by contact_id (up to 500), or by list_id (up to 50 lists); all contacts that are members of the list_ids are deleted. Deleted contacts won’t receive email from you, and they don’t count as active contacts. Unlike unsubscribed contacts, deleted contacts can be added back to an account. [Learn how to revive deleted contacts](/api_guide/contacts_delete.html#revive).
operationId: postContactDelete
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: The request body contains an array of contact_ids <em>or</em> list_ids. All contact_ids provided are deleted, or all members of each specified list_id are deleted.
required: true
schema:
$ref: '#/definitions/ContactDelete'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityDeleteStatus'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createDeleteActivity
/activities/contacts_file_import:
post:
tags:
- Bulk Activities
summary: Import Contacts using a CSV File
description: "This multipart method creates an asynchronous background job that adds or updates contacts by importing a CSV file containing contact information. Do not use a Content-Type header value with this method.\n\nImporting a new contact email address automatically sets the contact's `permission_to_send` property as `implicit` and the `opt_in_source` property as `Account`. Importing an existing contact only updates the contact properties you include in the request.\nImporting contacts with `sms_number`s requires using the `sms_permission_to_send` parameter to specify permissions for all contacts being imported. Set to `explicit` to specify that all contacts either provided explicit permission. Set to `not_set` if permission was not provided. If `explicit`, you must also include the `sms_consent_date` as a column header to include the date the contact consented to receiving SMS messages.\nContacts must have either an email address or an SMS number defined.\n \nThe CSV file has a maximum of 40,000 lines including the header row (39,999 contacts) and a maximum file size of 4 megabytes (MB). Lines above the 40,000 line maximum are not processed. If the request body exceeds 4 MB, only the contacts contained in the first 4 MB are imported and the remaining data is dropped."
operationId: contactsCSVImport
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: file
in: formData
description: "The CSV file you are importing must include either `email` or `sms_number` as a column heading. Other properties you can include using column headings are: `first_name`. `last_name`, `phone`, `job_title`, `anniversary`, `birthday_day`, `birthday_month`, `company_name`, `street`, `street2`, `city`, `state`, `zip`, `country`, and `sms_consent_date`. \n\nIf adding an `sms_number`, you must also include the `sms_permission_to_send` parameter and set it to either `not_set` or `explicit`. If `explicit`, requires including `sms_consent_date` as a column header to specify the date the contact consented to receiving SMS messages. \n\nYou can also use custom fields as column headings. Enter the custom field name prefixed with `cf:` as the column heading. For example, use `cf:first_name` as the header name if you have a custom field named \"first_name\". The custom field must already exist in the Constant Contact account you are using. Depending on the custom field data type, you can enter dates or strings as the value of the custom field. Each contact can contain up to 25 different custom fields."
required: true
type: file
x-example: new_contacts_import.csv
- name: list_ids
in: formData
description: Specify which contact lists you are adding all imported contacts to as an array of up to 50 contact `list_id` values.
required: true
type: string
items:
type: string
maxItems: 50
format: csv
x-example: 8c077f20-1586-11e4-bcb3-00163e56be7c
- name: sms_permission_to_send
in: formData
description: If importing contact `sms_number`s, use this parameter to specify how SMS consent was provided. If all contacts in the file provided their consent, set to `explicit` and include each contact's `sms_consent_date`. If all contacts in the file have not yet provided consent, set to `not_set` (`sms_consent_date` is not required). You cannot message a contact that does not have a sms consent date set.
required: false
type: string
enum:
- not_set
- explicit
x-example: not_set
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityImport'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: The requested resource was not found.
'415':
description: 1. This endpoint requires that Content-Type be unspecified 2. Wrong file format, upload file must be of type .csv
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createCSVImportActivity
/activities/contacts_json_import:
post:
tags:
- Bulk Activities
summary: Import Contacts using a JSON Payload
description: "Use this method to create an asynchronous background job that adds new contacts or updates existing contacts by importing a JSON payload. This method requires a request body that contains the contact data you are importing and the contact lists to which you want to add the imported contacts. A contact's data must include an `email` address and/or `sms_number`. The `sms_number` must be a US phone number to associate with the contact's SMS-enabled phone. Valid formats are <code>1231231234</code> or <code>123-123-1234</code> (the country code must be valid).\n\nImporting a new contact using this method automatically sets the contact's email `permission_to_send` property to `implicit` and the `opt_in_source` property as `Account`. Importing an existing contact only updates the contact properties you include in the request. For each contact, you can import up to three addresses and three phone numbers. International phone numbers are currently not supported. \n\nTo import custom fields, prefix the custom field name with `cf:` and add it as a contact property. For example, use the property name `cf:first_name` if you have a custom field named `first_name`. The custom field must already exist in the Constant Contact account you are using. Each contact can contain up to 25 custom fields.\n\nTo include a contact's `sms_number`, if the contact provided explicit permission to receive SMS messages, you must set the `sms_permission_to_send` property to `explicit` and specify the date of consent using the `sms_consent_date` column header. If explicit permission was not provided, set `sms_permission_to_send` to `not_set` (the `sms_consent_date` is not required). If the `sms_consent_date` is not set, SMS messages cannot be sent to contacts and `sms_permission_to_send` defaults to `not_set`. Valid value formats for `sms_consent_date` include 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. \n\nThe request body payload has a maximum size of 4 megabytes (MB). If the request body exceeds 4 MB, this method only imports the first 4 MB and drops the remaining data. Use the activity URL to check the status of the import activity request."
operationId: bulkImportContactsJSON
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: The JSON request payload that contains the contact data and contact lists for the import.
required: true
schema:
$ref: '#/definitions/ContactsJsonImport'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityImport'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-ctctmcp-allow: true
x-sdk-methodName: createImportJSONActivity
/activities/remove_list_memberships:
post:
tags:
- Bulk Activities
summary: Remove Contacts from Lists
description: Use this method to create an activity that removes contacts from one or more contact lists. Use the properties in the `source` object to remove specific contacts from your lists. Use the `list_ids` array to specify the target lists from which contacts are removed. Optionally, if the source is `all_active_contacts` (billable) or `list_ids`, use the `exclude` object to exclude specific contacts from being removed from the destination lists.
operationId: postListRemoveContact
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: The JSON payload used to create the Remove Contacts from Lists' activity
required: true
schema:
$ref: '#/definitions/ListActivityRemoveContacts'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityListsMembership'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: The requested resource was not found.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createListRemoveActivity
/activities/add_list_memberships:
post:
tags:
- Bulk Activities
summary: Add Contacts to Lists
description: Use this method to create an activity that adds contacts to one or more lists. Each contact can be a member of up to 50 lists. Use the properties in the `source` object to specify the contacts you want to add to lists. Use the `list_ids` array to specify which lists you want to add your source contacts to.
operationId: postListAddContact
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: The JSON payload used to create the 'add contacts to lists' activity
required: true
schema:
$ref: '#/definitions/ListActivityAddContacts'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityListsMembership'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createListAddActivity
/activities/list_delete:
post:
tags:
- Bulk Activities
summary: Delete Contact Lists
description: 'Use this endpoint to delete up to 100 contact lists in an account. '
operationId: postListDelete
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: An array of `list_id`'s to delete.
required: true
schema:
$ref: '#/definitions/ListIdList100'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityDeleteListsResponse'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createListDeleteActivity
/activities/contacts_taggings_remove:
post:
tags:
- Bulk Activities
summary: Remove Tags from Contacts
description: 'Use this method to create an asynchronous activity that removes one or more tags from all contacts meeting your contact filtering criteria. Filtering criteria must include the `source` type used to identify contacts from which the specified tags (`tag_id`) are removed.
Source types are mutually exclusive. If the specified source is either `all_active_contacts` or `list_ids`, you can optionally choose to `exclude` specified contacts by `contact_id`. Use the activity link in the results to check the status of your request."
For more use case information, see "[Remove Tags from Contacts](/api_guide/remove_tagging_activity.html)'
operationId: postTagRemoveContact
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: The JSON payload used to create an asynchronous activity that removes tags from contacts meeting your specified contact filtering criteria.
required: true
schema:
$ref: '#/definitions/TagAddRemoveContacts'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityTagging'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: The requested resource was not found.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createTagRemoveActivity
/activities/contacts_taggings_add:
post:
tags:
- Bulk Activities
summary: Add Tags to Contacts
description: 'Use this method to create an asynchronous activity that adds one or more tags to all contacts meeting your contact filtering criteria. Use the `source` type to identify contacts from which the specified tags (`tag_id`) are added.
Source criteria are mutually exclusive. If the source is `all_active_contacts` or `list_ids`, you can optionally choose to `exclude` contacts by `contact_id`. Use the activity link in the results to check the status of your request.
For more use case information, see "[Add Tags to Contacts](/api_guide/add_tagging_activity.html)'
operationId: postTagAddContact
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: The JSON payload used to create an asynchronous activity that adds tags to contacts that meet your specified contact filtering criteria.
required: true
schema:
$ref: '#/definitions/TagAddRemoveContacts'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityTagging'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: The requested resource was not found.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createTagAddContactActivity
/activities/contacts_tags_delete:
post:
tags:
- Bulk Activities
summary: Delete Tags
description: Use this method to create an asynchronous activity that deletes up to 500 tags. Deleted tags are automatically removed from tagged contacts. Use the `tag_ids` array of string values in the request body to specify which tags to delete.
operationId: postTagDelete
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: An array of string values (`tag_id`s) to delete.
required: true
schema:
$ref: '#/definitions/TagIdList500Limit'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityTagging'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
x-sdk-methodName: createTagDeleteActivity
/activities/custom_fields_delete:
post:
tags:
- Bulk Activities
summary: Delete Custom Fields
description: 'Use this endpoint to delete up to 100 custom fields for an account. '
operationId: postCustomFieldDelete
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: An array of `custom_field_id`'s to delete.
required: true
schema:
$ref: '#/definitions/CustomFieldId100'
responses:
'201':
description: Request successful. Activity queued for processing.
schema:
$ref: '#/definitions/ActivityDeleteCustomFields'
'400':
description: Bad request. Either the JSON was malformed or there was a data validation error.
'401':
description: The Access Token used is invalid.
'403':
description: Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
'404':
description: The requested resource was not found.
'429':
description: Too many requests. You exceeded 1,000 queued activities for this user account.
'500':
description: There was a problem with our internal service.
'503':
description: Our internal service is temporarily unavailable.
security:
- oauth2_implicit:
- contact_data
- oauth2_access_code:
- contact_data
x-authorization-privileges:
- contacts:write
definitions:
ActivityExportStatus:
type: object
properties:
activity_id:
type: string
format: uuid
example: 86b90820-cc52-11ea-9dad-fa163e3d9194
description: Unique ID for the activity.
readOnly: true
state:
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/constant-contact/refs/heads/main/openapi/constant-contact-bulk-activities-api-openapi.yml