Bulk API 2.0

Bulk API 2.0
Bulk Uploading and Upserting
Examples
Walkthrough for Bulk Insert
Walkthrough for Bulk Insert With A Multipart Request
Walkthrough for Bulk Upsert
Data Files
Reference
Bulk Queries
PDF

Walkthrough for Bulk Insert With A Multipart Request

This walkthrough guides you through the steps for creating a job to insert new records, creating batches for the job, checking status, and retrieving the results. This walkthrough uses a single multipart request to create the job and upload job data.
  • 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 very 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 Data Files.

    For this walkthrough, since we’ll use a multipart request to create the job and upload the data, the total size of the CSV data should not exceed 100,000 characters.

  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. In this walkthrough we’ll also include job data in the request that creates the job.

    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 new job and upload job data by issuing a POST request with the following details:
      Request Headers:
      1Content-Type: multipart/form-data; boundary=BOUNDARY
2Accept: application/json
      URI:
      1/services/data/vXX.X/jobs/ingest/
      Request Body:
      1--BOUNDARY
2Content-Type: application/json
3Content-Disposition: form-data; name="job"
4
5{
6  "object":"Contact",
7  "contentType":"CSV",
8  "operation": "insert",
9  "lineEnding": "CRLF"
10}
11
12--BOUNDARY
13Content-Type: text/csv
14Content-Disposition: form-data; name="content"; filename="content"
15
16FirstName,LastName,MailingCity
17Astro,Nomical,San Francisco
18Hootie,McOwlface,San Francisco
19Appy,Camper,San Francisco
20Earnie,Badger,San Francisco
21--BOUNDARY--

      In this example, “BOUNDARY” is used to mark the request body boundaries between the job details and the job CSV data.

      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 UploadComplete. You'll use the job ID in Bulk API 2.0 calls in the next steps.

  3. 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'll 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.