Bulk Actions API

The Bulk Actions API provides a way to initiate multi-select table actions in Account Engagement for asynchronous bulk processing of records of a given object type such as bulk deleting prospects. It also provides a way to monitor and manage multi-select table actions initiated from the Account Engagement Bulk Actions API.

The Bulk Actions API lets you perform operations on records of a common object type in bulk by providing a CSV file containing the ID of the records. The following bulk actions are supported.

• bulk delete prospects by ID
• permanently delete prospects from the recycle bin

• General
  • Bulk action owner (i.e. the user that originally created the bulk action request) - Retains View and Edit ability for performing Read, Query, Pause, Resume, and Cancel operations on their bulk actions as long as the user still retains the same abilities that were originally required to Create the bulk action.
  • Admin > Table Actions > View ability - Required to view bulk actions created by other users. Applies to all operations.
  • Admin > Table Actions > Edit ability - Required to edit bulk actions created by other users. Applies to Pause, Resume, and Cancel operations.
• Object-specific - User permissions required to Create bulk actions depend on the object and requested action.
  • Prospect
    • any action
      • Prospect > Prospects > View prospects not assigned to self ability is required to perform bulk actions on prospects that aren’t assigned to the API user. Note that the Create operation doesn’t validate whether the prospects identified in the CSV are assigned to that user. This validation is done asynchronously as part of the bulk action processing. If the API user doesn’t have this ability, then any prospects that aren’t assigned to the API user will be skipped during bulk action processing and the expected final status of the bulk action will be:
        • Complete with non-zero errorCount. The error report will identify which prospects were skipped due to API user not having the required ability to view the prospect.
    • delete action requires Prospect > Prospects > Delete ability
    • permanentdelete action requires Prospect > Prospects > Delete Permanently from the Recycle Bin ability

• Object ID limit per request - A maximum of 100,000 object IDs may be specified per bulk action Create request.
• Max file size per request - The CSV file size for a Create request must be smaller than 10 MB.
• Concurrency limit - A maximum of 50 bulk actions whose origin is API may be “Waiting”, “Paused”, or “Processing” per account per BulkAction type at any given time. Attempting to create additional bulk actions for the account beyond this limit will result in the request being rejected with HTTP Status 429 (Too Many Requests) and Error Code 66.

• A bulk action resource automatically expires 7 days after transitioning to a final status (“Complete”, “Cancelled”, or “Failed”). The bulk action ID will no longer be readable or queryable via the API after it’s expired.
• Paused bulk actions will be automatically cancelled by the system after 7 days.

• Bulk actions that haven’t yet transitioned to a final status may be explicitly paused via the Pause operation. A bulk action that’s been paused for more than 7 days could be automatically Cancelled by the system.
• Bulk actions that are “Paused” can be resumed for processing via Resume operation.

• Bulk actions that haven’t yet transitioned to a final status can be explicitly Cancelled via the Cancel operation.
• Record updates that have already been applied by the bulk action before it was cancelled aren’t rolled back.

• If the API user specifies true for the sendSystemEmail option when creating the bulk action, then the system sends an email to that user when the bulk action has been completed.

• API error responses follow the same general conventions as Account Engagement v5 API.

• The Bulk Action API provides an endpoint for downloading an error report after the bulk action has transitioned to a final status. The error report is a CSV file with error details for any rows that the system failed to apply the requested bulk action due to errors.
• This report has same Expiration as the bulk action.
• Unprocessed records that weren’t processed due to cancellation aren’t included in the error report and aren’t reflected in the errorCount.
• Here are the bulk action errors that may appear in this report.

The following fields must be specified for the Create operation.

Creates a bulk action. A bulk action create POST request is submitted as a multipart request with an attached CSV file as described in Version 5 Overview.

Note that the standard v5 API deleted parameter is not supported for this resource.

The Content-Type of the request body is multipart/form-data with two parts, the input part specifies the requested bulk action to perform and the file part is a CSV file identifying the records to be processed by the bulk action.

• The input part is expected to be JSON object containing the following fields.
  • object field is required for specifying the object type to be processed by the bulk action. See Object.
  • bulkAction field is required for specifying the type of action to perform on each record in the bulk action See BulkAction.
  • status field is required and must be set to “Ready” or “Paused”.
• The file part is expected to be a CSV file formatted as follows identifying the records to be processed by the bulk action. This is a required input.
  • single column of data.
  • first row is header value “id” or “matchId”. Both refer to the ID field of the object and are semantically equivalent.
  • each subsequent row of data is an integer ID identifying a record of the target “object” type specified in the request body fields that the caller wants to be processed by the bulk action.
• See Limits for limits on the number of IDs that may be processed per bulk action.
• Order of processing is not guaranteed.

The fields in the response body and Location header are the same as the fields specified on the example request.

• HTTP Status 400 Bad Request
  • Error Code 153 - Missing required property.
  • Error Code 154 - Invalid property.
  • Error Code 159 - The file is not in a valid CSV format.
  • Error Code 162 - No file was specified or uploaded.
  • Error Code 63 - Too many IDs specified.
  • Error Code 49 - This API user lacks sufficient permissions for the requested operation.
• HTTP Status 429 Too Many Requests
  • Error Code 66 - You have exceeded your concurrent request limit.
  • Error Code 67 - You have reached or exceeded the limit of how many of this type of object you may have.
  • Error Code 122 - Daily API rate limit met.
• Error codes: See Error Codes & Messages.

Retrieves a bulk action resource by its ID. A 404 Not Found response will be returned if the given ID doesn’t exist or has already expired.

Example request

Example response

• Status code: 4xx
• Error codes: See Error Codes & Messages.

Retrieves a collection of bulk actions based on a given set of filter criteria following the conventions described in Version 5 Overview. Up to 3 distinct filters can be specified.

• Status code: 4xx
• Error codes: See Error Codes & Messages.

Pauses a bulk action given its ID. This request is only valid for bulk actions that haven’t already transitioned to a final status or Cancelling status. Pausing a bulk action that’s already in Paused status has no effect. Attempting to pause a bulk action that’s already in a final status will result in an error response.

• HTTP 400 Bad Request - Invalid input parameters.
  • Error Code 51 - Invalid Parameter. Only status can be set.
• HTTP 404 Not Found - The specified ID doesn’t exist.
• HTTP 405 Method Not Allowed - The pause operation cannot be performed because the bulk action has already transitioned to a final status or Cancelling status. See Status.
• Error codes: See Error Codes & Messages.

Resume a paused bulk action given its ID. This request only has an effect on bulk actions that are in Paused status. Attempting to resume a bulk action that’s Waiting or Processing has no effect. Attempting to resume a bulk action that’s already in a final or cancelling status will result in an error response. When servicing a request to resume a bulk action, the system will automatically transition the status of the bulk action to Waiting, Processing, or a final status if there is no further processing to be done.

• HTTP 400 Bad Request - Invalid input parameters.
  • Error Code 51 - Invalid Parameter. Only status can be set.
• HTTP 404 Not Found - The specified ID doesn’t exist.
• HTTP 405 Method Not Allowed - The resume operation cannot be performed because the bulk action has already transitioned to a final status or Cancelling status. See Status.
• Error codes: See Error Codes & Messages.

Cancels a bulk action given its ID. This request is only valid for bulk actions that have not already transitioned to a final status. Attempting to resume a bulk action that is Cancelling or Cancelled has no effect. Attempting to cancel a bulk action that is already in a final status will result in an error response. Cancellation requests may be processed asynchronously in which case the status will temporarily transition to Cancelling status before eventually entering final status of Cancelled.

• HTTP 400 Bad Request - invalid input parameters.
  • Error Code 51 - Invalid Parameter. Only status can be set.
• HTTP 404 Not Found - The specified ID doesn’t exist.
• HTTP 405 Method Not Allowed - The cancel operation cannot be performed because the bulk action has already transitioned to a final status. See Status.
• Error codes: See Error Codes & Messages.

Download errors associated with the specified bulk action (after it’s complete).

CSV data with error info for any rows that the bulk action failed to process due to an error. No data is returned if there were no errors. For error types and descriptions, see Error Report.

• HTTP Status 204 No error
• HTTP Status 400 Bad Request
  • Error Code 109 - The requested record was not found.
    • Note: This will be returned if the bulk action isn’t finished processing.
• HTTP Status 404 Not Found
  • Error Code 109 - The requested record was not found.
    • Note: This will be returned if the given ID doesn’t exist or has already expired.
• HTTP Status 429 Too Many Requests
  • Error Code 122 - Daily API rate limit met.
• See Error Codes & Messages.

• Prospect

• delete: Move records of the specified object type to the recycle bin.
• permanentdelete: Permanently delete records of the specified object type from the recycle bin (i.e. hard delete).

• Ready: The caller specifies this status to indicate that the bulk action is ready to be processed. This is relevant to Create and Resume operations.
• Waiting: The bulk action is waiting to be processed.
• Processing: A server has started processing the bulk action. Processing may not be continuous. Processing may be throttled and/or stalled at times to relinquish system resources for servicing other functions of the customer’s Account Engagement business unit or to protect availability of the Account Engagement service. The system may temporarily transition a bulk action back to Waiting status in such cases.
• Paused: The bulk action has been paused by an authorized user. A bulk action that’s been paused for more than 7 days will be automatically cancelled by the system.
• Complete: The bulk action is complete and results are ready to be consumed. Any records that failed to process successfully due to errors are available in the error report. The errorCount and errorsRef fields are available for Read. This is a final status.
• Failed: The bulk action encountered an unrecoverable system error and can’t complete normally. The error report may not be available for download or may be incomplete for Failed bulk action. This is a final status.
• Cancelling: The system is in the process of cancelling the bulk action job and preparing the results in response to user request to cancel the bulk action. The status will transition to Cancelled after the bulk action results are ready to be consumed. Pause and Resume operations aren’t supported for bulk actions with this status.
• Cancelled: The bulk action’s been Cancelled by an authorized user and can’t be restarted. Record updates that were already processed aren’t rolled back. Any records that failed to process successfully due to errors prior to cancellation are available in the error report. The errorCount and errorsRef fields are available for Read. This is a final status.

• API: The bulk action was requested by the customer from the Account Engagement API.