Conceptual Introduction

A Bulk Import Job consists of an Upload File and a Mapping Definition. Each Bulk Import Job is of a single Resource Type and may be either creation of new entities, updating existing entities, or a combination of the two.

Upload File

The Upload File is simple flat tabular data.

Each row of the Upload File contains information about one entity of the given Resource Type. For example, if your Resource Type is Contacts, and you are creating new records, your Upload File might look like this:

Limitations

• It is a zip file which contains data formatted as plain text, either as comma separated values (.csv) or tab delimited (.txt).
• If any instances of the delimiter character appear in your file itself, you will need to make sure to quote those strings. This is very likely if you use commas as your delimiter, as commas appear in many fields you are likely to upload. If you create your data with a spreadsheet program, it will probably quote the strings with delimiter in them automatically when saving.
• An upload file can have at most 50 columns.

Mapping Definition

Our sample Upload File corresponds to several different Mapping Definitions in a Bulk Import Job.

• Most of the columns are straightforward columns that can be part of your Create Or Update Contact mapping definition: fundamental columns for creating a new Contact.
• There’s a different Mapping Definition for external identifiers: Apply External ID.
• This sample upload file includes both work and personal phones for each of our contacts. We can add Mapping Definitions for both kinds of phone separately: Apply Phone Numbers.

Some fields can be created initially with the Create Or Update Contact mapping definition if you only want to make a simple Upload File. For example, if you have only one email address or phone number per contact, you can add the email address and phone number as part of the Create Or Update Contact mapping. Other fields always need to be created as part of a separate mapping definition, such as External ID or Origin Source Code. To see what mappings are available to your API key, make a call to GET /bulkImportMappingTypes.

Our sample spreadsheet will correspond to five mapping definitions: one for the base contact definition, one for each of the three different types of phones, and one for the external ID.

{
  "name": "CreateOrUpdateContact",
  "fieldValueMappings": [
    {
      "fieldName": "FirstName",
      "columnName": "GivenName"
    },
    {
      "fieldName": "LastName",
      "columnName": "Surname"
    },
    {
      "fieldName": "AddressLine1",
      "columnName": "StreetAddress"
    },
    {
      "fieldName": "City"
    },
    {
      "fieldName": "StateOrProvince",
      "columnName": "State"
    },
    {
      "fieldName": "ZipOrPostal",
      "columnName": "Zip"
    },
    {
      "fieldName": "Email"
    }
  ]
}

{
  "name": "Phones",
  "fieldValueMappings": [
    {
      "fieldName": "Phone",
      "columnName": "HomePhone"
    },
    {
      "fieldName": "PhoneTypeID",
      "staticValue": "H"
    },
    {
      "fieldName": "PhoneOptInStatusID",
      "staticValue": "Opt-In"
    },
    {
      "fieldName": "CountryCode",
      "columnName": "HPCountry"
    }
  ]
}

{
  "name": "Phones",
  "fieldValueMappings": [
    {
      "fieldName": "Phone",
      "columnName": "MPhone"
    },
    {
      "fieldName": "PhoneTypeID",
      "staticValue": "C"
    },
    {
      "fieldName": "PhoneOptInStatusID",
      "staticValue": "Opt-In"
    },
    {
      "fieldName": "CountryCode",
      "staticValue": "US"
    }
  ]
}

{
  "name": "Phones",
  "fieldValueMappings": [
    {
      "fieldName": "Phone",
      "columnName": "WorkPhone"
    },
    {
      "fieldName": "PhoneTypeID",
      "staticValue": "W"
    },
    {
      "fieldName": "PhoneOptInStatusID",
      "staticValue": "Unknown"
    },
    {
      "fieldName": "CountryCode",
      "staticValue": "US"
    }
  ]
}

{
  "name": "ApplyExternalID",
  "fieldValueMappings": [
    {
      "fieldName": "ExternalId"
    },
    {
      "fieldName": "ExternalIdTypeID",
      "staticValue": "Friendster"
    }
  ]
}