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.

API users first create a job with a POST /bulkImportJobs call.
A successful POST returns the jobId of the bulk import job.
API users make a GET /bulkImportJobs/{jobId} call.
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.