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.

BulkUploadDataIDULFileIDPrimaryKeyPrimaryKeyTypeExternalIDPhones_1834Phones_1835ApplyExternalID_1836
1613512345VanID1234ProcessedProcessedProcessed
2613531415VanID2345Ignored to avoid overwriting best phoneProcessedProcessed
3613585753VanID3456ProcessedInvalid phone numberProcessed

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

ColumnDescription
BulkUploadDataIDData Row ID/Number
ULFileIDAn internal identifier which can be used to track this particular import for troubleshooting.
PrimaryKeyThe unique identifier for the resource.
PrimaryKeyTypeName of the unique identifier for the resource, e.g. VanID for Contacts, or ContributionID for Contributions.
requested columnsToIncludeInResultsFileAny 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 batchThe 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.