Import API

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

When to Use the Import API

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.

What You Can Do With the Import API

The Import API lets you import a CSV file of prospects. Columns in the CSV correspond to Pardot field names. 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.

User Permissions Required for Import

  • Prospect > Prospect > 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.

For more information, see Pardot User Roles

Matching and Upsert Behavior

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

  • Prospect ID
  • CRM Lead/Contact ID
  • Email

Including multiple match columns is permitted, but only one match value can be set per record. 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 udpates).

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

FieldDatatypeDescription
createOnNoMatchBooleanOptional.
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.
restoreDeletedBooleanOptional.
False (Default): Creates a prospect for AMPSEA. Fails for non-AMPSEA.
True: Restore deleted records that match, and update.
FieldDatatypeDescription
overwriteBooleanIndicates whether to update when there is already a value on the record.
Default: True.
nullOverwriteBooleanIndicates whether to update a field to null if an input value is blank, that is, ",,".
Default: True.

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

Sample Import CSV

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.

How the Import API Works

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.

Limits

  • 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 Pardot API call limit and the concurrent Pardot API call limit apply to Import API calls just as they would any other Pardot API calls.

Expiration

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 cancelled after one month.

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

Import Endpoints

VerbURI PathAction
POST/v5/importsCreate import job. Generates an “id” for the job.
POST/v5/imports/{id}/batchesUpload 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/importsQuery import jobs.
GET/v5/imports/{id}/errorsDownload the errors for an import job.

Fields

Required Editable Fields

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

FieldTypeDescription
operationStringThe operation to be executed. Currently only Upsert is available.
objectStringThe current object to be run against the import. Currently only Prospect is available.
statusStringSet 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.

FieldTypeDescription
createOnNoMatchBooleanOptional.
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.
restoreDeletedBooleanOptional.
False (Default): Creates a prospect for AMPSEA. Fails for non-AMPSEA.
True: Restore deleted records that match, and update.
fieldsStringOptional.
Enables modifying the update behavior of fields.

Read-Only Fields

FieldTypeDescription
idIntThe operation to be executed. Currently only Upsert is available.
statusStringThe 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.
Cancelled - The import job was cancelled by Support.
isExpiredBooleanIndicates whether the import has expired.
batchesRefStringThe URL to use for adding batches to the import.
createdAtDatetimeThe date and time that the import was created.
updatedAtDatetimeThe date and time that the import was last updated.
createdById
createdBy
IntThe Id of the user and related user object, that is, able to get username by using createdBy.username.
updatedById
updatedBy
IntThe Id of the user and related user object.
createdCountIntThe number of created records. Only populated after batch is in Complete status. Not available in Query.
updatedCountIntThe number of updated records. Only populated after batch is in Complete status. Not available in Query.
errorCountIntThe number of error records. Only populated after batch is in Complete status. Not available in Query.
errorRefStringThe 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.

POST for Create Import Job

Params

FieldDescription
fieldsThe 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

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.

POST for Add Batch

Params for Add Batch

URL ElementDescription
idThe ID of the import.

Body for Add Batch

A single part with the name "importFile" contains the CSV file for the batch. Ensure that the file contains a header row. Column names must match field names in Prospect V5 Fields. 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


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.

PATCH

Params for Update

URL ElementDescription
fieldsThe value for fields is a comma-separated enumeration of the fields to be returned. If no fields are input, only id is returned.
idThe ID of the import.

Example Request for Update

Example Response for Update

  • Status Code: 200

Errors for Update


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.

GET

Params for Read

URL ElementDescription
fieldsThe value for fields is a comma-separated enumeration of the fields to be returned. If no fields are input, only id is returned.
idThe ID of the import.

Example Request for Read

Example Response for Read

Status Code: 200

Errors for Read


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.

GET for Query

Params for Query

URL ElementDescription
fieldsThe 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

FieldTypeFilter or Value
idnumberidGreaterThan
idGreaterThanOrEqualTo
idLessThan
idLessThanOrEqualTo
createdAtdate 2019-09-07T15:50:00-04:00createdAtBefore
createdAtBeforeOrEqualTo
createdAtAfter
createdAtAfterOrEqualTo
updatedAtdate 2019-09-07T15:50:00-04:00updatedAtBefore
updatedAtBeforeOrEqualTo
updatedAtAfter
updatedAtAfterOrEqualTo
statusstringopen
processing
complete
waiting
failed
cancelled
orderBystringid/createdAt/updatedAt/ + ASC/DESC
orderBy id ASC
orderBy createdAt DESC

Example Request for Query

Example Response for Query

Status Code: 200

Errors for Query


Download errors associated with the specified import (after it’s complete).

GET for Download Errors

Params for Download Errors

URL ElementDescription
idThe 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


Import Status

  • 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.
  • Cancelled : The import process has been cancelled.

Import Operation

  • Upsert : Upsert objects.

Object

  • Prospect : Operate on Prospect.

Import Origin

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