Delete Multiple Records Using Bulk API 2.0

Deleting records using Bulk API 2.0 involves a few distinct steps. First, organize the record IDs that you want to delete in a CSV file. Next, send a POST request to create a bulk ingestion job, which provides you with a job ID. Use the job ID to send a PUT request that contains your CSV data. When you finish uploading data, send a PATCH request to change the status of the job and begin processing records. Finally, send a GET request to find the status of the job.

You can use Bulk API 2.0 to delete many record types. This table shows the record types that are most relevant to Marketing Cloud.

Record TypeAPI Name
Contact recordsContact
Lead recordsLead
Marketing segmentsMarketSegment

Before you send a request to Bulk API 2.0, obtain a bearer token. For more information, see Connect to REST-based APIs.

Data uploads for Bulk API 2.0 deletion requests can include only one field: Id. This behavior is different from other Bulk API 2.0 uploads.

The first line of the CSV file must contain the text Id. Each line after that must contain the ID of the record that you want to delete, as shown in this example.

To begin the process of deleting records in bulk, create a bulk ingestion job. Issue a POST request to the /services/data/v60.0/jobs/ingest endpoint. The body of the request must contain at least two properties: object and operation. The value of the object property must match the API name of the record type that you’re deleting. The value of the operation property must be delete.

This example shows a minimal request to create a job that deletes Contacts in bulk.

The response includes an id value. This value is the job ID, which you use in subsequent operations.

To upload data, send a PUT request to the /services/data/v60.0/jobs/ingest/JOB_ID/batches endpoint, where JOB_ID is your ingestion job ID. The body of the request contains your data in CSV format. For best results, limit the size of the data to 100 MB.

For general considerations related to uploading data using Bulk API 2.0, see Upload Job Data in the Bulk API 2.0 and Bulk API Developer Guide.

When you finish uploading data, change the status of the job to UploadComplete. This step tells the system to start processing the uploaded data. You can change the status by sending a PATCH request to the /services/data/v60.0/jobs/ingest/{jobId} endpoint. The body of the request must be a JSON object with a single property named state with a value of uploadComplete.

To end an ingestion job without processing any records, change the value of state to aborted.

Check the status of the ingestion job by sending a GET request to the /services/data/v60.0/jobs/ingest/JOB_ID endpoint, where JOB_ID is the job ID for the ingestion job. The response includes a status property, which describes the current state of the job.