Our v3 API is now available! Learn more by visiting the v3 developer portal. Creating new v2 API keys is no longer supported.

Using the Bulk Activity Endpoints

Bulk activity endpoints are intended for developers to use when they need to with large collections of contacts. Use the Bulk Activity endpoints to create asynchronous background jobs (activities) that you can let process while performing other actions.

How multiple activities process

Bulk activities are processed asynchronously. If 6 activity requests are made by an account, they will be processed by any number of servers on our side (up to 6 in this case), so 2 activities will be likely to take place at the same time. If one activity is dependent on another, such as a clear list activity needing to be processed before an import contacts activity begins, you should check for completion before sending the dependent request. This will prevent unexpected results like partially filled lists.

We recommend checking the activity status once per 30 seconds when waiting for a bulk activity status of "complete." Activities can take anywhere from 30 seconds to 15 minutes and up for very large requests. Activity records are stored for 14 days.


There is a hard limit of 1000 activities that can be in queue for processing for each individual account. If an account is bumping into this limit, please review how the integration is using bulk activity endpoints, and review these guidelines for which endpoints to use when syncing and adding contacts. 

Updating existing contacts

When updating existing contacts using either of the bulk import contacts endpoints (JSON or multipart), 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.

Syncing activities and tasks

If your integration updates contact lists using the bulk import endpoint before sending out a campaign, you need to make sure that the import contacts bulk activity has completed before you schedule the campaign. If not, it is possible that the campaign can be sent out to a partial subscriber list.