Workflow

Bulk Import Jobs are run asynchronously. The entire workflow of initiating a bulk import job and investigating the returned results consists of multiple calls.

  1. API users first create a job with a POST /bulkImportJobs call.
  2. A successful POST returns the jobId of the bulk import job.
  3. API users make a GET /bulkImportJobs/{jobId} call.
  4. When the results of the GET return a status of Complete, the asynchronous job is completed, and the API user can inspect the results.

If at least a subset of the rows in the Upload File are successfully imported into the database, the status of the GET call will be Complete, and the resultFiles array will contain links to files containing information about the Bulk Import Job.

Result Files

For every row in your upload file that validates, there will be a row in the results file. For the upload file in the Conceptual Overview, the results file should look something like this.

BulkUploadDataID

ULFileID

PrimaryKey

PrimaryKeyType

ExternalID

Phones_1834

Phones_1835

ApplyExternalID_1836

1

6135

12345

VanID

1234

Processed

Processed

Processed

2

6135

31415

VanID

2345

Ignored to avoid overwriting best phone

Processed

Processed

3

6135

85753

VanID

3456

Processed

Invalid phone number

Processed

The columns in the result file can be parsed by the consuming software.

Column

Description

BulkUploadDataID

Data Row ID/Number

ULFileID

An internal identifier which can be used to track this particular import for troubleshooting.

PrimaryKey

The unique identifier for the resource.

PrimaryKeyType

Name of the unique identifier for the resource, e.g. VanID for Contacts, or ContributionID for Contributions.

requested columnsToIncludeInResultsFile

Any columns which have been tagged in columnsToIncludeInResultsFile will appear next. In this example, that is the ExternalID column. When creating new records, including a column in the results file can allow you to synchronize between the primary key created with the new record, and the primary key in an external system. This column does not need to have been included in any of the existing field mappings.

remaining columns: results for each batch

The remainder of the results file contains messages for each of the mapping types in the POST. If a resultFileColumnName has been specified, it will be used; otherwise the column header will be the name of the mapping type followed by an underscore and an identifier. Error messages for individual data imports will appear here.