Bulk API 2.0 and Bulk API Developer Guide

Introduction to Bulk API 2.0
Getting Started
Set Up a Salesforce Developer Edition Organization
Authentication
Walkthrough for Bulk Insert
Walkthrough for Bulk Insert With A Multipart Request
Walkthrough for Bulk Upsert
Walkthrough for Query Jobs
Bulk API 2.0
Bulk API
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Walkthrough for Bulk Insert

This walkthrough guides you through the steps for creating a job to insert new records, uploading data for the job, checking status, and retrieving the results.
  • Read through all the steps in this walkthrough. You might also want to review the rest of this document to get a quick overview of Bulk API 2.0 calls and concepts.
  • Familiarize yourself with Workbench. This walkthrough uses Workbench to issue Bulk API 2.0 calls, but you can use any tool or development environment that can make REST requests.
  1. Create a CSV file containing your data.

    Using your preferred spreadsheet tool, create a CSV file that contains the records you want to insert. The first row of the CSV file lists the field names for the object you're working with. Each subsequent row corresponds to a record that you want to insert.

    For a simple example list of Contacts that can be used to create a CSV file, see Bulk API Sample Contact Data

    For additional information on preparing CSV files, such as delimiter options and valid date/time formats, see Bulk API 2.0 Ingest.

  2. Create a job.

    To do any Bulk API 2.0 task, such as inserting or updating records, you first create a job. The job specifies the type of object, such as Contact, that you're loading. The job also specifies the operation you're performing, such as insert or delete. Once you've created a job, you can use the resulting job ID in Bulk API 2.0 requests to close or abort (cancel) the job.

    1. In Workbench, log in to your org.
    2. Go to Utilities | REST Explorer. Use Bulk API 2.0 to create a job by issuing a POST request with the following details:
      Request Headers:
      1Content-Type: application/json; charset=UTF-8
2Accept: application/json
      URI:
      1/services/data/vXX.X/jobs/ingest/
      Request Body:
      1{
2    "object" : "Contact",
3    "contentType" : "CSV",
4    "operation" : "insert",
5    "lineEnding": "CRLF"
6}

      If you’re inserting an object other than Contact, replace “Contact” in the request body with your object name.

      When you’re using Workbench, set lineEnding to CRLF. If you’re using another tool, set it to match the line endings in your data file.

      You should get a response that includes the job ID, with a job state of Open. You'll use the job ID in Bulk API 2.0 calls in the next steps. You’ll also use the URL in the contentUrl field of the response in the next step when you upload your data.

  3. Upload your CSV data.

    After creating a job, you're ready to upload your data. You provide record data using the CSV file you created earlier.

    In Workbench's REST Explorer, use Bulk API 2.0 to create a job data request with the CSV data. Issue a PUT request with the following details:

    Request Headers:
    1Content-Type: text/csv
2Accept: application/json
    URI:

    Use the URI provided in the contentUrl field of the response from step 1. The URI has a format similar to the following example.

    1/services/data/vXX.X/jobs/ingest/jobId/batches/
    Request Body:
    1(Content of your CSV file)

    For the Request Body, copy and paste the CSV data into Workbench's Request Body text field. With Bulk API 2.0, you can submit CSV data that does not in total exceed 150 MB in size (after base64 encoding).

    You should get a response that includes the job ID still in the Open state. You could cancel the job at this point by using a PATCH to set the job state to Aborted.

  4. Upload complete.

    Once you're done submitting data, you can inform Salesforce that the job is ready for processing by closing the job.

    In Workbench's REST Explorer, issue a PATCH request with the following details:

    Request Headers:
    1Content-Type: application/json; charset=UTF-8
2Accept: application/json
    URI:
    1/services/data/vXX.X/jobs/ingest/jobId/
    Request Body:
    1{
2    "state" : "UploadComplete"
3}
  5. Check the job status and results.

    To get basic status information on a job, such as the overall job state or the number of records processed, use a GET request with the following details:

    Request Headers:
    1Content-Type: application/json; charset=UTF-8
2Accept: application/json
    URI:
    1/services/data/vXX.X/jobs/ingest/jobId/

    Once a job has been completed and is in the JobComplete state (or Failed state), you can get details of which job data records were successfully processed by issuing a GET request with the following details:

    Request Headers:
    1Content-Type: application/json; charset=UTF-8
2Accept: text/csv
    1/services/data/vXX.X/jobs/ingest/jobId/successfulResults/

    You get a response that contains CSV data, with each row containing a record ID and information on whether that record was successfully processed or not. To get details on records that encountered an error during processing, use a GET request using the failedResults resource instead of the successfulResults resource.