Delete Multiple Records in Marketing Cloud Growth Using Bulk API 2.0

Use Bulk API 2.0 to delete thousands of records asynchronously.

This table shows the relevant record types that you can delete using Bulk API 2.0.

Record TypeAPI Name
Contact recordsContact
Lead recordsLead

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

To delete records in bulk, you must first create a CSV file that lists the IDs of the records you want to delete. Bulk deletion requests can include only the Id field. This behavior is different from other requests in Bulk API 2.0.

The first line of the CSV file must contain the text Id. Each line after that contains the ID of each 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/v61.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 request to create a job that deletes Contacts in bulk.

If the request is successful, 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/v61.0/jobs/ingest/JOB_ID/batches endpoint, where JOB_ID is your ingestion job ID. Include your data in CSV format in the body of the request. 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/v61.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/v61.0/jobs/ingest/JOB_ID endpoint, where JOB_ID is the job ID for the ingestion job. If the request is successful, the response includes a status property, which describes the current state of the job.