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

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:

1. If a match is found and contains prospect fields, then update the prospect record.
2. If a match is found and the CSV contains the list columns, then the prospect is added to, or removed from the list.
3. If no match is found, then the record returns an error.
4. 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:

1matchEmail,firstName,BestProduct__c, addToList, removeFromList
2test@test.com,John,Product A,123;234,546;758

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.

1. Create an import that specifies the object and action.
2. Upload data to the server in one or more batches.
3. 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.
4. 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.
5. 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:

1. 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.
2. 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.

Required Editable Fields

Optional Editable Fields

Read-Only Fields

1POST /api/v5/imports

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

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

1POST /api/v5/imports/?fields=id,createdAt, status, isExpired, origin, batchesRef
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5{
6    "operation": "upsert",
7    "object": "prospect",
8    "fields": {
9        "field1_name": {
10            "nullOverwrite": boolean,
11            "overwrite": boolean
12         } ///Repeat for every field in the CSV file
13    }
14}

Create Import Job Example Response

• Status Code: 201
• Output Representation

1{
2    "id": int,
3    "status": string,
4    "isExpired": boolean,
5    "origin": "api",
6    "batchesRef": string : "https://pi.pardot.com/api/v5/imports/1863",
7    "createdAt":"<YYYY-MM-DD>T<HH24:MI:SS-TimezoneOffset>",
8    "updatedAt":"<YYYY-MM-DD>T<HH24:MI:SS-TimezoneOffset>"
9}

Errors

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

Example of Creating Import for a Single File Request

1POST /api/v5/imports/?fields=id,createdAt, status
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: multipart/form-data; boundary=----boundary-marker
5
6----boundary-marker
7Content-Disposition: form-data; name="file"; filename="prospectList.csv"
8
9<file-data>
10----boundary-marker
11Content-Disposition: form-data; name="input"
12
13{
14    "operation": "Upsert",
15    "object": "Prospect",
16    "restoreDeleted": true,
17    "status": "Ready"
18    "fields": {
19        "field1_name": {"overwrite": false, "nullOverwrite": true },
20        "field2_name": {"overwrite": true, "nullOverwrite": false },
21                ...
22    }
23}

Example of Creating Import for a Single File Response

1HTTP/1.1 201 Created
2Content-Type: application/json
3{
4"id": int,
5"createdAt": :"<YYYY-MM-DD>T<HH24:MI:SS-TimezoneOffset>",
6“status”:”Waiting”
7}

1POST /api/v5/imports/{id}/batches

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

Params for Add Batch

Body for Add Batch

1ContentType: multipart/form-data

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

1POST /api/v5/imports/{id}/batches
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: multipart/form-data; boundary=----boundary-marker
5
6----boundary-marker
7Content-Disposition: form-data; name="file"; filename="prospectList.csv"
8
9<file-data>

Success

• Status Code: 204
• Output Representation: Empty Body

Example Success Response

1HTTP/1.1 204 No Content

Errors

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

1PATCH /api/v5/imports/{id}

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

Example Request for Update

1PATCH /api/v5/imports/{id}?fields=id,isExpired,status
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5{
6    "status": "Ready" // see State enum
7}

Example Response for Update

• Status Code: 200

1{
2  "id": int,
3  "status": "Waiting",
4  "isExpired": boolean
5}

Errors for Update

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

1GET /api/v5/imports/{id}

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

Example Request for Read

1GET /api/v5/imports/{id}?fields=id,isExpired, status,createdCount,updatedCount,errorsRef,errorCount
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json

Example Response for Read

Status Code: 200

1{
2    "id": int,
3    "status": string,
4    "isExpired": int
5    // if status is "Complete"
6    "createdCount": int,
7    "updatedCount": int,
8    "errorsRef": string : "https://pi.pardot.com/api/v5/imports/{id}/errors",
9    "errorCount": int
10}

Errors for Read

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

1GET /api/v5/imports

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

Query Filters and Sorting

Example Request for Query

1GET /api/v5/imports?fields=id,createdAt,updatedAt,status
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json

Example Response for Query

Status Code: 200

1{
2    "nextPageToken": **null**,
3    "nextPageUrl": **null**,
4    "values": [
5        {
6            "id": int,
7            "createdAt": date,
8            "status": string,
9            "updatedAt": date
10        },
11        {
12            "id": int,
13            "createdAt": date,
14            "status": string,
15            "updatedAt": date
16        }
17}

Errors for Query

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

1GET /api/v5/imports/{id}/errors

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

Example Request for Download Errors

1GET /api/v5/imports/{id}/errors
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json

Example Response for Download Errors

Status Code: 200

1matchId,email,addToList,campaignId,Error Type,Import Error Description
2115,"prospect1@site.com",28,84,"Prospect with email address already exists","Prospect with email ""prospect1@site.com"" already exists."
3116,"prospect2@site.com",28,84,"Prospect with email address already exists","Prospect with email ""prospect2@site.com"" already exists."

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.

1POST /api/v5/imports/{id}/do/cancel

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

1{
2    "id": int,
3    "createdAt": "<YYYY-MM-DD>T<HH24:MI:SS-TimezoneOffset>",
4    "isExpired": boolean,
5    "origin": string,
6    "status": string,
7    "updatedAt": "<YYYY-MM-DD>T<HH24:MI:SS-TimezoneOffset>"
8}

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.

j

Get Started

Quick Start

Version 3 Docs

Version 4 Docs

Version 5 Docs

Account

Bulk Actions

Campaigns

Custom Fields

Custom Redirects

Dynamic Content

Dynamic Content Variations

Emails

Email Templates

Engagement Studio Programs

Exports

External Activities

External Activity

Files

Folders

Folder Contents

Forms

Form Fields

Form Handlers

Form Handler Fields

Imports

Landing Pages

Layout Templates

Lifecycle Stages

Lifecycle Histories

Lists

List Email

List Memberships

Opportunities

Prospects

Tags

TaggedObjects

Prospect Accounts

Tracker Domains

Users

Visitors

Visitor Activity

Visits

Visitor Page Views

Tracking and Consent API

Get Started as an Account Engagement ISV

Extend the Email Builder Experience

Work with Extensibility Features

Salesforce Objects for Account Engagement Development

Additional Resources