Bulk activity features and endpoints

Bulk activity endpoints offer developers a way to manage thousands of contacts in a single API call. Use the Bulk Activity endpoints to create asynchronous background jobs (activities) that process while performing other actions.

What You Can Do with Activity Endpoints

Feature Description
Export Contacts Export contacts and select data to a CSV file. Integration users can select which contacts to export, or export them all.
Import or Sync Contacts You can import contacts from a CSV file using the multi-part form endpoint, or by using a standard JSON endpoint. You can also import custom fields values with these contacts.
Tag Management Users can add or remove tags from a large numbers of contacts and delete a large number of tags.
List Management Users can add or remove large numbers of contacts to or from existing lists.
Contact Maintenance Users can delete hundreds of contacts from their account in a single request.
View Activity Status View a detailed status for a specific activity, or status reports for all activity requests made in the past 10 days.

How Bulk Activities Work

Bulk activity endpoints create jobs that are placed into a queue and processed asynchronously. When a POST request is made to an activity endpoint, we send a response that includes an activity_id, along with the current status of the request. Poll the /activities/{activity_id} endpoint to determine when the job has completed. Activity requests are not processed sequentially; the order in which activities complete depends on several factors, including the load on the service processing the request, and the size of the request.

A bulk activity request that started processing before another may not complete first.

Making Multiple Activity Requests - Sequence Matters

In situations when a user makes multiple activity requests, it is important to know when one request is dependent on another request. For example, an application wants to import 10,000 contacts into a user’s account and then add some or all of these new contacts to one or more new lists. The import contacts activity has to complete before submitting the request to add these new contacts to the new lists. This will prevent unexpected results occurring in the Add to Lists request, and ensure that all new and updated contacts are processed in the user’s account first.


Here are a couple of limits to keep in mind when using bulk activity endpoints:

Endpoint Parameter Limit What happens if limit exceeded
All /activities Number of requests An account can have a maximum of 1000 activities requests queued or processing at any one time We send a “429 Too Many Requests” response
/activities/contacts_file_import Payload size The CSV file used with the endpoint cannot exceed 40,000 lines (1 header line and 39,999 contacts) or a file size of 4 megabytes. The request is processed, but we “drop” any data that exceeds the limit.
/activities/contacts_json_import Payload size The JSON payload cannot exceed 40,000 contact records or a file size of 4 megabytes. The request is processed, but we “drop” any data that exceeds the limit.

Polling for Activity Status

We recommend polling for the activity status once every 30 seconds when waiting for an activity to complete. Activities can take anywhere from 30 seconds to 15 minutes and up for very large requests.

Activity records are retained for 10 days.

Update existing contacts in a bulk import job

When updating existing contacts using either of the bulk import contacts endpoints (JSON or CSV), the process is non-destructive with respect to existing contact data. Any fields that are not included in the column_names array, or that have no data for a contact, are not overwritten as when making a PUT call to update one contact.

In short, you cannot delete any information for a contact using the bulk import endpoints unless you mistakenly include a value for a contact with a space or other ‘invisible’ data in it.