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:

GivenName

Surname

StreetAddress

City

State

Zip

Email

HomePhone

HPCountry

MPhone

WorkPhone

ExternalId

Marco

DiNyle

1630 Revello Drive

Rogerstown

CA

91115

[email protected]

413-555-0928

US

413-555-0928

413-555-0938

1234

Tamás

Erdélyi

3976 Poe Road

Springtown

MA

01909

[email protected]

843-555-2852

US

843-555-2852

843-555-0728

2345

Mathangi

Arulpragasam

3314 Villa Drive

Colombo

OH

91132

[email protected]

01632 960387

GB

617-555-1224

617-555-1000

3456

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"
    }
  ]
}