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
- 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 delete lists, 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.
- Delete Custom Fields: Remove up to 100 custom fields from contacts and delete the custom fields from an account.
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.
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.
Limits
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.
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.