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 With A Multipart Request

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. This walkthrough uses a single multipart request to both 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 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 make a “multipart” request that includes job data in the initial 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}
10
11--BOUNDARY
12Content-Type: text/csv
13Content-Disposition: form-data; name="content"; filename="content"
14
15Name,MailingCity
16Astro Nomical,San Francisco
17Hootie McOwl,San Francisco
18Appy Camper,San Francisco
19Earnie Badger,San Francisco
20--BOUNDARY--

      In this example, “BOUNDARY” is used at the start, as a separator, and at the end to mark the request body boundaries between the job details and the job CSV data.

      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.

  2. 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.