Import API Overview

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 automates the existing prospect import feature set. Only prospect import is supported currently.

IMPORTANT The user's role must have the Prospect Import ability to start an API import. For more information, see Pardot User Roles

When to Use the Import API

Use the Import API to insert or update large sets of data, when you don't require synchronous completion responses, or when batch upsert limitations are too restrictive: http://developer.pardot.com/kb/api-version-4/prospects/#upserting-prospects. Currently, only Prospect upsert is supported.

The Import API processes many records asynchronously in batches. Each batch requires a minimum amount of system resources to run, so larger batches are generally more efficient. Small batches may result in slower performance.

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.

Matching and Upsert behavior

When a row in the CSV file matches an existing prospect, the prospect is updated. Field values in the CSV, including blank (null) values, overwrite existing values for the prospect. To modify this default behavior, see the columns param on the Create endpoint.

A new prospect is created when a matching prospect isn't found. All standard and custom fields are supported.

In API Version 4, you must specify either the "prospect_id" or "salesforce_fid" identifier (Salesforce ID of a synced prospect). If you don't specify an identifier, or the prospect that is matched is in the recycle bin, that record isn't upserted unless the restoreDeleted option is specified during import creation. The rest of the import isn't affected when a record is skipped.

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 is not guaranteed.

The Import resource is used to create an import, get status for an import, upload data as a batch, and change status for an import. When a batch finishes processing, the result for failed records is available in a result set resource. All other records are assumed to be successful.

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

  1. Create an import that specifies 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 will also contain statistics for creates, updates, and failures.
  5. If there are failures, download a log of failures. The log includes only records not inserted or updated.

Imports left in the "Open" state expire after 24 hours.

Limitations

Expiration

Imports expire:

  1. 24 hours after creation if the import isn't submitted. No records are imported in this case, even if batches of data have been added.
  2. 7 days after completion.

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

Getting Started

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.


Create

/api/import/version/4/do/create

Used to create a new asynchronous import. If a batch of import data is included in this request, the import can be submitted for processing as part of this operation. Otherwise one or more batches must be created and associated with this import using the do/batch endpoint and the import must be submitted for processing with the do/update endpoint.

POST

Params

Request Body

ContentType: application/json or multipart/form-data

Use multipart/form-data if sending prospect data in the create request. Use application/json if subsequent do/batch requests will be made with prospect data.

{
    "operation": "Upsert",
    "object": "Prospect",
    "restoreDeleted": boolean,
    "state": "Ready",
    "columns": [
        {"field": "field1_name", "overwrite": boolean, "nullOverwrite": boolean },
        {"field": "field2_name"},
        ...
    ]
}

A single part with the name "importFile" should contain the CSV file for the batch. The file should contain a header row.

Success

{
    "id": int,
    "state": string,
    "isExpired": boolean,
    "batchesRef": string : "https://pi.pardot.com/api/import/version/4/do/batch/id/{id}"
}

Errors


Add Batch

/api/import/version/4/do/batch/id/{id}

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

POST

Params

{id}: The ID of the import.

Body

ContentType: multipart/form-data

A single part with the name "importFile" should contain the CSV file for the batch. The file should contain a header row.

Column names must match Filed Names in Pardot http://developer.pardot.com/kb/object-field-references/. For example, to set campaign, pass “campaign_id”. 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.

Success

Errors


Update

/api/import/version/4/do/update/id/{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.

PATCH

Params

{id}: The ID of the import.

Body

ContentType: application/json

{
    "state": "Ready" // see State enum
}

Success

{
    "id": {id},
    "state": "Waiting",
    "isExpired": boolean
}

Errors


Read

/api/import/version/4/do/read/id/{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.

GET

Params

{id}: The ID of the import.

Success

{
    "id": int,
    "state": string,
    "isExpired": int
    // if state is "Complete"
    "createdCount": int,
    "updatedCount": int,
    "errorsRef": string : "https://pi.pardot.com/api/import/version/4/do/downloadErrors/id/{id}",
    "errorCount": int
}

Errors


Query

/api/import/version/4/do/query

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

Params

For date representation in the parameters above the value can be today, yesterday, last_7_days, this_month, last_month, or a custom time specified in GNU Date Input Syntax format.

Success

Status Code: 200

Output Representation

Note that the import representation returned in query doesn’t contain resultRefs. Use the read endpoint for the import to get the full import representation.

{
    "result": {
        "total_results": int,
        "import": [
            {
                "id": int,
                "state": string,
                "isExpired": boolean,
                "origin": string,
                "createdAt": datetime,
                "updatedAt": datetime
            }
        ]
    }
}

Errors


Download Errors

/api/import/version/4/do/downloadErrors/id/{id}

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

GET

Params

{id}: The ID of the import.

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


Enums

Import State

Import Operation

Object

Import Origin