/bulkImportJobs

Initiates a bulk import job by specifying the url for a zipped, delimited file, of no more than 100MB. A bulk import job can update and/or create multiple data types including, but not limited to, Contacts, Contributions, and ActivistCodes. For a complete list of supported types, see the resources endpoint.

The zipped file can contain both update and creation records for a single resource type. It can also contain a header row. The header row is only there as a debugging aid, and is not used by the import process. See Property hasHeader in the File object for more information on headers.

When the bulk import job is updating resources, if any non-required columns are left blank, those fields will not be updated. This process cannot be used to delete information; it can only update or create.

Request

Bulk Import Job

Property

Type

Description

description

string

Required; A description of the job, to be included in notifications (whether via email or webhook). Maximum length is 255 characters. No HTML or HTML special character syntax. More precisely, input must not match this regex: [<>]+|&#

file

object

Required; A File object which describes the source file and columns to be acted on. The file can be up to 100 MB (100,000 KB) in size.

actions

array

Required; An array of Action objects, each defining an action to be taken.

File

Property

Type

Description

fileName

string

Required; Name of the delimited file within the zip file accessible by sourceUrl (e.g., MyImportData.csv).

hasHeader

bool

Optional; Indicates that the first line of the file should be skipped. A header row in the file will be not be used; column names are determined by the required columns array and the order that the columns appear in the file. Defaults to false.

hasQuotes

bool

Optional; Indicates that fields are enclosed in quotation marks within each column of the file. Defaults to false. Important: If any instances of the delimiter character appear in your file itself, you will need to make sure to quote those strings and set this to true. This is very likely if you use commas as your delimiter, as commas appear in many fields you are likely to upload (eg. a Long Name of Names, with, commas in a .csv file). If you create your data with a spreadsheet program, it will probably quote the strings with delimiter in them automatically when saving.

sourceUrl

string

Required; URL at which a zip file containing fileName can be accessed. The following URL schemes (“protocols”) are supported: SFTP, FTPS, HTTPS. If authentication is required, the username and password should be included in the URL (e.g., sftp://user:[email protected]/my_import_data.zip).

columnDelimiter

string

Optional; Character that separates each each column; one of: CSV → comma (,) separated values, Tab → Tab separated values, Pipe → pipe (|) separated values. Defaults to CSV.

columns

array

Required; An ordered array of Column objects, describing each column of the source file (from left to right). At least one column is required.

Column

A column name must be present for every column in the uploaded file, listed in the order in which they appear in the file from left to right. See mapping types for more information.

Property

Type

Description

name

string

Required; A column’s unique, alphanumeric name that can be referenced in actions (e.g., VanID)

The first column of a file is restricted based on the ResourceType and MappingType and must match or be mapped to a specific column name; however the match is case insensitive.

ResourceType

MappingType

Required Column Name

Contacts

All Except For CreateOrUpdateContact

VanId

Contributions

ContributionAdjustments

ContributionId

Contributions

EditContributionData

ContactsContributionId

ContributionAdjustments

ContributionAdjustments

ContributionId

ContributionAdjustments

EditContributionData

ContactsContributionId

Action

Required properties: actionType, ResourceType, and ResultFileSizeKbLimit.

Property

Type

Description

actionType

string

Required; The string loadMappedFile.

resourceType

string

Required; The type of resource being updated. Available options: Contacts, Contributions, ActivistCodes, or ContactsActivistCodes.

resultFileSizeKbLimit

int

Required; The maximum size in kilobytes of any result file returned.

mappingTypes

array

Required; Collection of mappings to apply to the file, translating uploaded tabular data to our object models

columnsToIncludeInResultsFile

array

An array of Column objects to be included in the bulk import job’s results file (for example, to synchronize with an external ID to an external data source).

Mapping types

The mappingTypes array encodes a series of field mapping definitions. These define the supported methods for mapping out the flat data in your file, in order to translate it into datatypes understood by our import system.

The available mapping types can be discovered from the GET /bulkImportMappingTypes endpoint.

Property

Type

Description

name

string

Required; The name of the field mapping type

fieldValueMappings

array

Optional; Any mappings, static values, or other options for this field mapping. This array is not needed if your input is using built-in mappings. For example, if your Columns array uses the names of our fields, your values are already in a format that will be accepted by our system, and no other options are required, it is not necessary to set these values.

resultFileColumnName

array

Optional; A string to represent this mapping in the results file produced by bulk import, if the default string is not desired

The fieldValueMappings array contains definitions for the columns mapped as part of this field mapping. If a column or a property is left out of the array, default values will be used, wherever possible.

Property

Type

Description

fieldName

string

The name of this field’s column, as discovered by GET /bulkImportMappingTypes.

columnName

string

If this column, as defined in the Columns array, does not have the same name as the fieldName, include the column name here.

staticValue

string

If this field should be using a static value for the entire bulk import, instead of drawing a value from the uploaded file, set that value here.

values

array

A collection of translations from values in the uploaded file to values as they should be imported into our system.

The values array is for those occasions where the uploaded file include data in some external format, and it needs to be translated into data as it is understood by our object models. For example, an external system creating the bulk import uploaded file encode types as “ccard”, “$$”, and “vmo”, which would be translated via the values array into “Credit Card”, “Cash”, and “Venmo”.

Property

Type

Description

sourceValue

string

What string should be translated when it is found in this column in the uploaded file.

targetValue

string

A string representation of the value to which the sourceValue should be translated.

Examples

Example 1: Simple contacts import

POST /bulkImportJobs
{
  "file": {
    "fileName": "my_bulk_upload.csv",
    "hasHeader": true,
    "hasQuotes": false,
    "sourceUrl": "https://a-place-for-files.com/my_bulk_upload.zip",
    "columns": [
      { "name": "GivenName" },
      { "name": "MiddleInitial" },
      { "name": "Surname" },
      { "name": "StreetAddress" },
      { "name": "City" },
      { "name": "State" },
      { "name": "ZipCode" },
      { "name": "EmailAddress" },
      { "name": "TelephoneNumber" },
      { "name": "Birthday" },
      { "name": "mStreet" },
      { "name": "mApt" },
      { "name": "mCity" },
      { "name": "mState" },
      { "name": "mZIP" },
      { "name": "mCountry" },
      { "name": "CodeId" }
    ],
    "columnDelimiter": "Csv"
  },
  "description": "A bulk import of new users with basic contact information",
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
          "name": "OriginSourceCode",
          "fieldValueMappings": [
            { "fieldName": "CodeId" }
          ]
        },
        {
          "name": "CreateOrUpdateContact",
          "resultFileColumnName": "NewPerson",
          "fieldValueMappings": [
            {
              "fieldName": "FirstName",
              "columnName": "GivenName"
            },
            {
              "fieldName": "MiddleName",
              "columnName": "MiddleInitial"
            },
            {
              "fieldName": "LastName",
              "columnName": "Surname"
            },
            {
              "fieldName": "AddressLine1",
              "columnName": "StreetAddress"
            },
            {
              "fieldName": "City",
              "columnName": "City"
            },
            {
              "fieldName": "StateOrProvince",
              "columnName": "State"
            },
            {
              "fieldName": "ZipOrPostal",
              "columnName": "ZipCode"
            },
            {
              "fieldName": "Email",
              "columnName": "EmailAddress"
            },
            {
              "fieldName": "Phone",
              "columnName": "TelephoneNumber"
            },
            {
              "fieldName": "DOB",
              "columnName": "Birthday"
            }
          ]
        },
        {
          "name": "MailingAddress",
          "fieldValueMappings": [
            {
              "fieldName": "MailingAddress",
              "columnName": "mStreet"
            },
            {
              "fieldName": "MailingAddressLine2",
              "columnName": "mApt"
            },
            {
              "fieldName": "MailingCity",
              "columnName": "mCity"
            },
            {
              "fieldName": "MailingStateOrProvince",
              "columnName": "mState"
            },
            {
              "fieldName": "MailingZipOrPostal",
              "columnName": "mZIP"
            },
            {
              "fieldName": "MailingCountryCode",
              "columnName": "mCountry",
              "values": [
                {
                  "sourceValue": "America",
                  "targetValue": "US"
                }
              ]
            },
            {
              "fieldName": "MailingDisplayAsEntered",
              "staticValue": "1"
            }
          ]
        }
      ]
    }
  ]
}

Example 2: Repeated fields in import

In this example, a bulk upload of Contacts will be created that applies multiple ExternalID fields to each uploaded Contact. One External ID, the one in the third column in the uploaded file, is of varying type, and draws its ExternalIDType from the second column in the uploaded file. This is the external ID which will be included in the results file. The fourth column in the uploaded file contains another external ID. These are all hardcoded to the ExternalIDType of “1”.

POST /bulkImportJobs
{
  "file": {
    "fileName": "my_bulk_upload.csv",
    "hasHeader": true,
    "hasQuotes": false,
    "sourceUrl": "https://a-place-for-files.com/my_bulk_upload.zip",
    "columns": [
      { "name": "VANID" },
      { "name": "ExternalIdTypeID" },
      { "name": "ExternalId" },
      { "name": "ID2" }
    ],
    "columnDelimiter": "Csv"
  },
  "description": "A bulk import of external IDs",
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "columnsToIncludeInResultsFile": [
        { "name": "ExternalIdTypeID" }
      ],
      "mappingTypes": [
        {
          "name": "ApplyExternalID",
          "fieldValueMappings": [
            { "fieldName": "ExternalIdTypeID" },
            { "fieldName": "ExternalId" }
          ]
        },
        {
          "name": "ApplyExternalID",
          "fieldValueMappings": [
            {
              "fieldName": "ExternalIdTypeID",
              "staticValue": "1"
            },
            {
              "fieldName": "ExternalId",
              "columnName": "ID2"
            }
          ]
        }
      ]
    }
  ]
}

Example 3: Apply custom fields to contacts

In this example, a bulk upload of Contacts will be created that applies multiple custom contact fields to each uploaded Contact. Multiple custom fields belonging to the same custom field group may be mapped, but you cannot mix custom fields from different custom field groups. Multiple custom contact groups may be added as separate mappingTypes.

POST /bulkImportJobs
{
  "description": "A bulk import with custom contact fields",
  "file": {
    "fileName": "my_bulk_upload.csv",
    "hasHeader": true,
    "hasQuotes": false,
    "sourceUrl": "https://a-place-for-files.com/my_bulk_upload.zip",
    "columns": [
      { "name": "VANID" },
      { "name": "CustomNumber_389" },
      { "name": "CF390" }
    ],
    "columnDelimiter": "Csv"
  },
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
          "name": "ApplyContactCustomFields",
          "fieldValueMappings": [
            {
              "fieldName": "CustomFieldGroupID",
              "staticValue": "1109"
            },
            {
              "fieldName": "CF389",
              "columnName": "CustomNumber_389"
            },
            {
              "fieldName": "CF390"
            }
          ]
        }
      ]
    }
  ]
}

Example 4: Apply Organizing Turfs to contacts

In this example, a bulk upload of Contacts will be created or updated with the mapped levels of organizing turf. You can only map one organizing turf per Contact and all turf levels must be supplied; any existing values will be overwritten. Supplying values outside the current turf hierarchy will result in a Failed job status.

POST /bulkImportJobs
{
  "description": "A bulk import with organizing turfs",
  "file": {
    "fileName": "my_bulk_upload.csv",
    "hasHeader": true,
    "hasQuotes": false,
    "sourceUrl": "https://a-place-for-files.com/my_bulk_upload.zip",
    "columns": [
      { "name": "VANID" },
      { "name": "Region" },
      { "name": "Organizer" },
      { "name": "Team" }
    ],
    "columnDelimiter": "Csv"
  },
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
          "name": "ApplyOrganzingTurfs",
          "fieldValueMappings": [
            {
              "fieldName": "CF123",
              "columnName": "Region"
            },
            {
              "fieldName": "CF124",
              "columnName": "Organizer"
            },
            {
              "fieldName": "CF125",
              "columnName": "Team"
            }
          ]
        }
      ]
    }
  ]
}

Example 5: Apply Jobs to contacts

In this example, a bulk upload of Contacts will be updated with all employer job information mapped from columns in the source file. Multiple jobs can be applied per Contact and any existing job record values will be overwritten. Supplying invalid values will result in a Failed job status.

POST /bulkImportJobs
{
  "description": "A bulk import with jobs",
  "file": {
    "fileName": "my_bulk_upload.csv",
    "hasHeader": true,
    "hasQuotes": true,
    "sourceUrl": "https://a-place-for-files.com/my_bulk_upload.zip",
    "columns": [
      { "name": "VANID" },
      { "name": "Employer" },
      { "name": "EmployeeID" },
      { "name": "Worksite" },
      { "name": "WorkArea" },
      { "name": "Department" },
      { "name": "ShiftType" },
      { "name": "ScheduleType" },
      { "name": "MemberStatus" },
      { "name": "HireDate" },
      { "name": "StartDate" },
      { "name": "ProbationEndDate" },
      { "name": "IsTerminated" },
      { "name": "TerminatedDate" },
      { "name": "TerminatedReason" },
      { "name": "TerminatedBy" },
      { "name": "TerminatedNotes" },
      { "name": "IsExcluded" },
      { "name": "ExcludedDate" },
      { "name": "ExcludedReason" },
      { "name": "ExcludedBy" },
      { "name": "ExcludedNotes" },
      { "name": "MembershipCardSigned" },
      { "name": "MembershipCardSignedDate" },
      { "name": "MembershipCardReceivedDate" },
      { "name": "MembershipCardEnteredBy" },
      { "name": "AuthorizationCardSigned" },
      { "name": "AuthorizationCardSignedDate" },
      { "name": "AuthorizationCardReceivedDate" },
      { "name": "AuthorizationCardEnteredBy" },
      { "name": "Wage" },
      { "name": "WageType" },
      { "name": "WealthcareContribution" },
      { "name": "HoursPerWeek" },
      { "name": "SickDays" },
      { "name": "VacationDays" }
    ],
    "columnDelimiter": "Csv"
  },
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
            "name": "Jobs",
        }
      ]
    }
  ]
}

Example 6: Apply Names and Salutations to contacts

In this example, a bulk upload of Contacts will be updated with name and salutation information mapped from columns in the source file.

POST /bulkImportJobs
{
  "description": "Load Contact Names",
  "listeners": [{"type": "email", "value": "[email protected]" }],
  "file": {
    "fileName": "NamesImport.txt",
    "hasHeader": true,
    "hasQuotes": false,
    "sourceUrl": "https://a-place-for-files.com/NamesImport.zip",
    "columns": [
      { "name": "VANID" },
      { "name": "Last" },
      { "name": "First" },
      { "name": "Middle" },
      { "name": "Suffix" },
      { "name": "Salutation" },
      { "name": "EnvelopeName" }
    ],
    "columnDelimiter": "Tab"
  },
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
          "name": "Salutations",
          "fieldValueMappings": [
            {
              "fieldName": "LastName",
              "columnName": "Last"
            },
            {
              "fieldName": "FirstName",
              "columnName": "First"
            },
            {
              "fieldName": "MiddleName",
              "columnName": "Middle"
            },
            {
              "fieldName": "Suffix",
              "columnName": "Suffix"
            },
            {
              "fieldName": "Salutation",
              "columnName": "Salutation"
            },
            {
              "fieldName": "FormalSalutation",
              "columnName": "Salutation"
            },
            {
              "fieldName": "AdditionalSalutation",
              "columnName": "Salutation"
            },
            {
              "fieldName": "EnvelopeName",
              "columnName": "EnvelopeName"
            },
            {
              "fieldName": "FormalEnvelopeName",
              "columnName": "EnvelopeName"
            },
            {
              "fieldName": "AdditionalEnvelopeName",
              "columnName": "EnvelopeName"
            }
          ]
        }
      ]
    }
  ]
}

Response

A successful POST returns the jobId of the bulk import job.

{
  "jobId": 998877
}
Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!