Import API

The Import API provides a programmatic way to insert or update large amounts of data in Account Engagement. It uses Account Engagement's existing API structures, patterns, and terminology. The Import API upserts prospects and updates list memberships in a single import.

Use the Import API:

To upsert or remove prospect records in bulk, including a custom field.
To update list memberships, including up to 20 lists in a single record.
To perform both actions in a single record.

Currently, prospect upserts and list membership updates are supported.

The Import API lets you import a CSV file of prospects. Columns in the CSV correspond to field names on Prospect. Rows correspond to prospects to be upserted. Each column must match a valid field name, or validation fails and the CSV is rejected. All standard and custom fields are supported.

Prospects > Prospects > Import - Required for any import job.
Marketing > Segmentation > List > View - Required to update list assignments.
Admin > Import > View - Required to view all imports via query. Otherwise, the query returns only the user initiated imports.
Prospects > Prospects > Assign - Required to bulk assign prospects to a user.

For more information, see Account Engagement User Roles

Un-assigning prospects is NOT supported through Import.

Matching and Upsert Behavior

Perform an upsert by using a match column. The following matching columns are supported:

matchId (Prospect ID)
matchSalesforceId (Prospect Salesforce Lead/Contact ID)
matchEmail (Prospect Email)

Including only one match column is permitted, otherwise the record returns an error.

To perform prospect creates, then do not include any values in the matching column.

To perform list membership assignments only, include just the match column and the fields addToList or removeFromList, or both.

The default matching behavior is:

If a match is found and contains prospect fields, then update the prospect record.
If a match is found and the CSV contains the list columns, then the prospect is added to, or removed from the list.
If no match is found, then the record returns an error.
If an invalid list assignment is entered, then the whole record fails (including prospect updates). This includes dynamic lists and test lists.

If the following parameters are submitted in the Create request, they modify the matching & upsert behavior of the import:

Field	Datatype	Description
`createOnNoMatch`	Boolean	Optional. `False` (Default): If a match key is provided and no match is found, then generate an error. `True`: If a match key is provided and no match is found, then create a record.
`restoreDeleted`	Boolean	Optional. `False` (Default): Creates a prospect for AMPSEA. Fails for non-AMPSEA. `True`: Restore deleted records that match, and update.

Field	Datatype	Description
`overwrite`	Boolean	Indicates whether to update when there is already a value on the record. Default: `True`.
`nullOverwrite`	Boolean	Indicates whether to update a field to `null` if an input value is blank, that is, ",,". Default: `True`.

To modify the update behavior of a field, all fields must be defined in the Create operation.

This example will:

Match based on Email.
Update the prospect's First Name.
Update the prospect’s custom field Best Product.
Add the prospect to two lists.
Remove the prospect from two lists.

An import contains a set of records divided into one or more batches of data. A batch is a set of records sent to the server in an HTTP POST request. The import specifies which object is processed and what type of operation is used. The Import API currently supports only the Prospect object and the Upsert operation.

Batches are processed in parallel, and batches are subdivided into smaller groups of objects for processing. The order in which individual records, batches, and entire imports are processed isn’t guaranteed.

The Import resource is used to create an import, get the status for an import, upload data as a batch, and change the status for an import.

Users create, submit, and retrieve results of imports with these steps.

Create an import that specifies the object and action.
Upload data to the server in one or more batches.
To submit the import for processing, set the state of the import to "Ready". After the import is submitted, you can't add more batches of data or abort the import.
Check the status of the import at a reasonable interval. We recommend that you wait a few minutes between calls. Calls to check import status count against API call limits. When the results of the status check indicate a complete import, the results also contain statistics for creates, updates, and failures.
If there are errors, download a log of failures. The log includes only records not inserted or updated.

There is a maximum of 1000 batches per account, per day.
Each batch must be smaller than 10 MB.
The daily data limit is 10 GB.
Each import can contain up to 10 batches.
Only 1 import processes at a time, using first-in, first out (FIFO) queuing.
The daily Account Engagement API call limit and the concurrent Account Engagement API call limit apply to Import API calls just as they would any other Account Engagement API calls.

Imports expire:

If the import isn't submitted, it expires 24 hours after creation. No records are imported in this case, even if batches of data have been added.
Seven days after the import has been completed.

After an import expires, it can't be changed and attempts to check its status or retrieve error results will fail.

Imports that stay in the processing state are canceled after one month.

This document assumes that you're familiar with connecting to the Account Engagement API, managing prospects, and creating CSV files. You can import data by using these endpoints.

Verb	URI Path	Action
POST	/v5/imports	Create import job. Generates an “id” for the job.
POST	/v5/imports/{id}/batches	Upload batch to import job. Max is 10 files.
PATCH	/v5/imports/{id}	Update the state to “ready”. Unable to add batches after the state is changed.
GET	/v5/imports/{id}	Read the status of an import job.
GET	/v5/imports	Query import jobs.
GET	/v5/imports/{id}/errors	Download the errors for an import job.
POST	/v5/imports/{id}/do/cancel	Cancel an import job.

Required Editable Fields

The fields in this table are only required for the Create operation.

Field	Type	Description
`operation`	String	The operation to be executed. Currently only `Upsert` is available.
`object`	String	The current object to be run against the import. Currently only `Prospect` is available.
`status`	String	Set the status of the import to ready. Required action to move the import into waiting status.

Optional Editable Fields

The fields in this table are only optional for the Create operation.

Field	Type	Description
`createOnNoMatch`	Boolean	Optional. `False` (Default): If a match key is provided and no match is found, then generate an error. `True`: If a match key is provided and no match is found, then create a record.
`restoreDeleted`	Boolean	Optional. `False` (Default): Creates a prospect for AMPSEA. Fails for non-AMPSEA. `True`: Restore deleted records that match, and update.
`fields`	Fields{}	Optional. Enables modifying the update behavior of fields.

Read-Only Fields

Field	Type	Description
`id`	Integer	The operation to be executed. Currently only `Upsert` is available.
`status`	String	The status of the import: `Open` - Import is able to accept batches. `Waiting` - Import is waiting to process. `Processing` - Import is being processed. `Complete` - Import has finished processing. `Failed` - An unexpected error happened processing the import. `Canceling` - The import job is canceling. `Canceled` - The import job was canceled.
`isExpired`	Boolean	Indicates whether the import has expired.
`batchesRef`	String	The URL to use for adding batches to the import.
`createdAt`	Datetime	The date and time that the import was created.
`updatedAt`	Datetime	The date and time that the import was last updated.
`createdById` `createdBy`	Integer	The ID of the user and related user object, that is, able to get username by using `createdBy.username`.
`updatedById` `updatedBy`	Integer	The ID of the user and related user object.
`createdCount`	Integer	The number of created records. Only populated after batch is in Complete status. Not available in Query.
`updatedCount`	Integer	The number of updated records. Only populated after batch is in Complete status. Not available in Query.
`errorCount`	Integer	The number of error records. Only populated after batch is in Complete status. Not available in Query.
`errorRef`	String	The URL to download the error records. Only populated after the batch is in Complete status. Not available in Query.

Used to create an import job, and generate the id for the job. One or more batches must be created and associated with this import using the POST /v5/imports/{id}/batch endpoint and the import must be submitted for processing with the PATCH /v5/imports/{id} endpoint.

Params

Field	Description
`fields`	The value for `fields` is a comma-separated enumeration of the fields to be returned. If no fields are input, only `id` is returned.

Request Body

In the create request, a batch can optionally be uploaded. If uploading a file at this step, use the Content Type multipart/form data. Otherwise, use application/json.

Create Import Job Example Request

Create Import Job Example Response

Status Code: 201
Output Representation

Errors

Status code: 4xx
Error codes: See Error Codes & Messages

Example of Creating Import for a Single File Request

Example of Creating Import for a Single File Response

Allows adding batches of data to an existing import when in the "Open" state.

Params for Add Batch

URL Element	Description
`id`	The ID of the import.

Body for Add Batch

A single part with the name "file" contains the CSV file for the batch. Make sure that the file contains a header row. Column names must match field names on Prospect. For example, to set campaign, pass “campaignId”. Columns that don't match existing field names cause validation to fail on this step. Each batch must contain an identical header with the same fields in the same order.

Example Request

Success

Status Code: 204
Output Representation: Empty Body

Example Success Response

Errors

Status code: 4xx
Error codes: See Error Codes & Messages

Used to submit the import by changing the state to "Ready". After this step, no more batches of data can be added, and processing of the import begins.

Params for Update

URL Element	Description
`fields`	The value for `fields` is a comma-separated enumeration of the fields to be returned. If no fields are input, only `id` is returned.
`id`	The ID of the import.

Example Request for Update

Example Response for Update

Status Code: 200

Errors for Update

Status code: 4xx
Error codes: See Error Codes & Messages

Returns the current state of the import. If processing is complete, the output provides a path to the results of the operation along with any statistics about the operation.

Params for Read

URL Element	Description
`fields`	The value for `fields` is a comma-separated enumeration of the fields to be returned. If no fields are input, only `id` is returned.
`id`	The ID of the import.

Example Request for Read

Example Response for Read

Status Code: 200

Errors for Read

Status code: 4xx
Error codes: See Error Codes & Messages

Used by administrators to retrieve a list of imports and their status. A user must have the “Admin > Imports > View” ability to execute this endpoint.

Params for Query

URL Element	Description
`fields`	The value for `fields` is a comma-separated enumeration of the fields to be returned. If no fields are input, only `id` is returned.

Query Filters and Sorting

Field	Type	Filter or Value
`id`	number	idGreaterThan idGreaterThanOrEqualTo idLessThan idLessThanOrEqualTo
`createdAt`	date 2019-09-07T15:50:00-04:00	createdAtBefore createdAtBeforeOrEqualTo createdAtAfter createdAtAfterOrEqualTo
`updatedAt`	date 2019-09-07T15:50:00-04:00	updatedAtBefore updatedAtBeforeOrEqualTo updatedAtAfter updatedAtAfterOrEqualTo
`status`	string	`open` `processing` `complete` `waiting` `failed` `canceled`
`orderBy`	string	`id`/`createdAt`/`updatedAt`/ + `ASC`/`DESC` `orderBy id ASC` `orderBy createdAt DESC`

Example Request for Query

Example Response for Query

Status Code: 200

Errors for Query

Status Code: 4xx
Error codes: See Error Codes & Messages

Download errors associated with the specified import (after it’s completed or canceled). Canceled imports will allow callers to download error files. Only prospects that were processed before the cancellation request will receive error records. Error files for canceled imports do not show which prospects were not processed.

Params for Download Errors

URL Element	Description
`id`	The ID of the import job.

Example Request for Download Errors

Example Response for Download Errors

Status Code: 200

Success

CSV data with error info for any rows that failed to result in inserts or updates. For error descriptions, see Prospect Import Errors.

Errors

Status code: 4xx
Error codes: See Error Codes & Messages.

Used to cancel the import. If the import is already completed or failed, it can't be canceled. Canceling an import updates the updatedAt field of the import. To view prospects processed before cancellation, in the Account Engagement Lightning App, navigate to Prospects > Import Prospects > API Imports and then click the import record for details.

Cancel Import Example Response

Status Code: 200
Output Representation

Errors for Cancel

Status Code: 4xx
Error codes: See Error Codes & Messages

Open : The import is created and can have batches added.
Ready : All imports are added and ready to be processed.
Waiting : The import is waiting to be picked up by a processing agent.
Processing : The import batches are being processed.
Complete : All batches completed and results are ready to be consumed.
Failed : The import batches have failed.
Canceling: The system is in the process of canceling the import job and preparing the results in response to user request to cancel the import. The status will transition to Canceled after the import results are ready to be consumed.
Canceled : The import process has been canceled.

Upsert : Upsert objects.

Prospect : Operate on Prospect.

UI : The import request is initiated through the wizard.
API : The import request is initiated through an api call.