Ingest Multiple Records Using Bulk API 2.0

Ingesting records using Bulk API 2.0 involves a few distinct steps. First, organize your data 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.

You can use Bulk API 2.0 to create the record types shown in this table.

Record TypeAPI Name
Contact recordsContact
CampaignsCampaign

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

The column names in your CSV file must match the field names in the target object exactly. You can retrieve a list of field names by issuing a GET call to the /services/data/v60.0/sobjects/OBJECT_API_NAME/describe endpoint, where OBJECT_API_NAME is the API name of the object to describe. Alternatively, you can view a list of fields in the Object Explorer in Salesforce Setup.

There are several other considerations to keep in mind when you create the CSV file. For more information, see Prepare CSV Files in the Bulk API 2.0 and Bulk API Developer Guide.

To begin the process of importing 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 inserting. The value of the operation property must be insert to create records. You can also update records by specifying an operation type of update, or update an upsert operation by specifying upsert.

This example shows a minimal request to create a job that ingests Contacts in bulk. For additional information and code examples, see createBulkContactIngestionJob.

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 more information and code examples, see uploadContactData.

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.

For more information and code examples, see closeBulkContactIngestionJob.

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. For more information about retrieving the status of a job, see getBulkContactIngestionJob.

You can also retrieve lists of records that were successfully ingested, that failed to be ingested, or that haven’t been ingested yet.