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.

What You Can Do With The 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 action is supported.

  • bulk delete prospects by ID

User Permissions Required For Bulk Actions

  • 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

Limits

  • 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.

Expiration

  • 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.

Pause And Resume

  • 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.

Cancellation

  • 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.

Optional Email Notifications

  • 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.

Errors

API Error Responses

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

Error Report

  • 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.
Error TypeDefinition
Not foundThe specified ID does not match an existing object record.
Not authorizedThe prospect isn’t assigned to the user performing the bulk action, and the user doesn't have the View Prospects Not Assigned to Self permission.

Bulk Action Endpoints

OperationVerbURI PathInputsDescription
CreatePOST/api/v5/bulk-actionsobject, action, status, CSV file, selected fieldsCreate a bulk action job. Generates ID.
ReadGET/api/v5/bulk-actions/{id}selected fields in query stringRead status of a bulk action job.
QueryGET/api/v5/bulk-actionsselected fields, sort order, filtersQuery bulk action jobs.
PausePATCH/api/v5/bulk-actions/{id}"status": "Paused"Pause processing of a bulk action job.
ResumePATCH/api/v5/bulk-actions/{id}"status": "Ready"Resume processing of a bulk action job.
CancelPATCH/api/v5/bulk-actions/{id}"status": "Cancelled"Cancel a bulk action job.
Download Error ReportGET/api/v5/bulk-actions/{id}/errorsidDownload report of records that a completed bulk action job failed to successfully process due to errors.

See Import v5 API as a reference.

Fields

Required Editable Fields

The following fields must be specified for the Create operation.

FieldTypeDescription
objectStringIdentifies the object type that the bulk action has been created to process. See Object. This field is not editable after creation.
bulkActionStringSpecifies the action to be performed when processing records in the bulk action. See BulkAction. This field is not editable after creation.
statusStringThe status of the bulk action. This field must be specified for the Create, Pause, Resume, and Cancel operations. See Status. The API user specifies initial status of "Ready" or "Paused" when creating the bulk action. After creation, the API user may pause or cancel a bulk action that hasn’t yet entered a final status by changing the status to "Paused" or "Cancelled" respectively. The API user may resume a paused bulk action by changing the status to "Ready". All other status changes are exclusively managed by the Account Engagement system.

Optional Editable Fields

FieldTypeDescription
sendSystemEmailBooleanSpecify true for this write-only field to opt-in to receiving a system email notifying the API user when the bulk action job is Complete, Cancelled, or Failed. This field may optionally be specified for the Create operation. This field isn't editable after creation. Default value for this field is false.

Read-Only Fields

FieldTypeDescription
idIntegerIdentifies the bulk action.
fileNameStringFor bulk actions whose origin is "API", this identifies the filename of the uploaded file part of the multipart request body of the Create request.
originStringIdentifies whether the bulk action was initiated from "API" origin. Origin.
countIntegerTotal number of items originally queued for processing as part of this bulk action.
percentCompleteIntegerEstimated progress of the bulk action as a percentage. This doesn't necessarily convey the actual percentage of objects that have been processed. Not available in Query.
createdAtDateTimeThe date and time the bulk action is created in the timezone of the user making the request.
updatedAtDateTimeThe date and time that the bulk action was last updated (e.g. due to status change or percentComplete change).
createdByIdIntegerIdentifies the user who created the bulk action.
createdByUserUser object representing the user who created the bulk action. This is also the user that is notified by email when the bulk action is complete.
updatedByIdIntegerIdentifies the user who last updated the bulk action.
updatedByUserUser object representing the user who last updated the bulk action.
errorCountIntegerThe number of records that failed to process due to errors after exhausting all retries. This corresponds to the number of records reported in the Error Report. Only populated after bulk action is in a final status.
errorsRefStringThe URL to download the Error Report. Only populated after the bulk action is in a final status. Not available in Query.
processedCountIntegerThe number of records that have been successfully processed including no-ops. Only populated after bulk action is in a final status.

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.

POST for Create

Params for Create

URL elementRequiredDescription
fieldsThe value for fields is a comma-separated enumeration of the fields to be returned. If no fields are input, only id is returned.

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

Body for Create Bulk Action

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.

Example of CSV file

Example multipart request with attached CSV file

Example success response

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

Errors for Create

  • 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.

GET for Read

Params for Read

URL elementRequiredDescription
fieldsXThe value for fields is a comma-separated enumeration of the fields to be returned.
idXThe id of the bulk action.

Example request

Example response

Errors for Read

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.

Get for Query

Params for Query

URL elementRequiredDescription
fieldsXThe value for fields is a comma-separated enumeration of the fields to be returned.

Query Filters and Sorting

FieldTypeFilter or Value
idnumberidGreaterThan
idGreaterThanOrEqualTo
idLessThan
idLessThanOrEqualTo
createdAtdate 2019-09-07T15:50:00-04:00createdAtAfter
createdAtAfterOrEqualTo
createdAtBefore
createdAtBeforeOrEqualTo
updatedAtdate 2019-09-07T15:50:00-04:00updatedAtAfter
updatedAtAfterOrEqualTo
updatedAtBefore
updatedAtBeforeOrEqualTo
bulkActionstringFilter results by action. See BulkAction for range of values. COMPATIBILITY CONSIDERATION: Support for additional actions may be added. If your queries are not designed to handle this, then it is highly recommended to use this filter option for your queries.
objectstringFilter results by object. See Object for range of values. COMPATIBILITY CONSIDERATION: Support for additional objects may be added. If your queries are not designed to handle this, then it is highly recommended to use this filter option for your queries.
originstringFilter results by origin. See Origin for range of values. COMPATIBILITY CONSIDERATION: Support for additional origins may be added. If your queries are not designed to handle this, then it is highly recommended to use this filter option for your queries.
statusstringWaiting
Processing
Paused
Complete
Failed
Cancelling
Cancelled
orderBystringid
createdAt
updatedAt

An optional direction qualifier, "ASC" or "DESC", can be specified to control the direction of the sort (e.g. "createdAt DESC"). Default sort order is "id ASC".

Example Request

Example Response

Errors for Query

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.

PATCH for Pause

Params for Pause

URL elementRequiredDescription
fieldsThe value for fields is a comma-separated enumeration of the fields to be returned. If no fields are input, only id is returned.
idXThe ID of the bulk action.

Example Request

Example Response

Errors for Pause

  • 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.

PATCH for Resume

Params for Resume

URL elementRequiredDescription
fieldsThe value for fields is a comma-separated enumeration of the fields to be returned. If no fields are input, only id is returned.
idXThe ID of the bulk action.

Example Request

Example Response

Errors for Resume

  • 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.

PATCH for Cancel

Params for Cancel

URL elementRequiredDescription
fieldsThe value for fields is a comma-separated enumeration of the fields to be returned. If no fields are input, only id is returned.
idXThe ID of the bulk action.

Example Request

Example Response (intermediate transition to Cancelling status because cancellation processing is asynchronous)

Example Response (entered final status synchronously)

Errors for Cancel

  • 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).

GET for Download Errors

Params for Download Errors

URL elementRequiredDescription
idXThe ID of the bulk action.

Example Request

Example Response

Success

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.

Errors

  • 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.

Object

  • Prospect

BulkAction

  • Delete: Move records of the specified object type to the recycle bin.

Status

  • 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.

Origin

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