Map Data Fields

To use Bulk API to import data that was exported directly from Microsoft Outlook, Google Contacts, and other third-party sources, map data fields in any CSV import file to Salesforce data fields. It’s not necessary for the CSV import file to be Bulk API-compatible.

For example, say you have a CSV import file that includes a field called Number that you want to map to the standard Salesforce field AccountNumber. When you add a batch job using Bulk API, data from your Number field is imported into (or updates) the AccountNumber field in Salesforce.

To add a batch job that maps data fields to Salesforce data fields:

  1. Create a transformation spec (spec.csv) that defines data field mappings. (This file is different from the CSV import file that contains your data.)
  2. Create a job that specifies an object and action, just as you would for any other Bulk API job.
  3. Upload the transformation spec.
  4. Send data to the server in batches.
  • Transformation specs must be CSV files. XML and JSON files aren’t supported.
  • Transformation specs must have a file size less than 8192 characters.
  • Transformation specs (spec.csv files) must use UTF-8 encoding. CSV import files don’t need to use UTF-8 encoding. (You can specify the encoding in the Content-Type header.)
  • Transformation specs aren’t persistent; their scopes are limited to the current job.

The transformation spec (spec.csv) provides the instructions for how to map the data in your import file to Salesforce data fields.

The spec.csv file contains four fields:

FieldDescription
Salesforce FieldThe Salesforce field you want to map to.
Csv HeaderThe field in your import file you want to map.
ValueA default value. Bulk API uses this value in two instances:
  • When there’s no value present in the import file for the field specified in the Csv Header field
  • When there’s no value defined for the Csv Header field in the spec.csv file
This field is optional.
HintTells Bulk API how to interpret data in the import file. Bulk API can use this value to do two things:
  • Interpret Java format strings for date and time fields
  • Define what is true using regular expressions for boolean fields
This field is optional.

Here’s a sample spec.csv file:

This spec.csv file tells Bulk API to:

  • Map the Full Name field in the import file to the LastName and FirstName fields in Salesforce.
  • Map the Job Title field in the import file to the Title field in Salesforce.
  • Map the Lead Source field in the import file to the LeadSource field in Salesforce, and use Import as the default value when no values are present are in the import file.
  • Use Imported from XYZ.csv as the default value for the Description field in Salesforce.
  • Map the Date of Birth field in the import file to the Birthdate field in Salesforce, and use the dd MM yy format to convert Date of Birth field formats into an acceptable format for Bulk API.

The corresponding contents of the import file can look like this:

The corresponding request body after transformation looks like this:

To upload the transformation spec, send a POST request to this URI:

You can find the My Domain name and My Domain login URL for your org on the My Domain page in Setup.