Export API Overview

The Export API provides a way to retrieve large volumes of data from Pardot. It uses Pardot's existing API structures, patterns, and terminology.

When to Use the Export API

Use the Export API to retrieve large sets of data when you don't need synchronous completion responses or when query limitations are too restrictive. Currently, only visitor activity is supported.

How the Export API Works

An export is associated with a query and a data set in Pardot. When you create an export, the query is split into smaller queries, which return smaller sets of data. These smaller queries are processed in parallel, and the retrieved data is saved in CSV files. When the export is complete, the CSV files are available to download.

The order of the records returned in the CSV files is not guaranteed. The number of records in each CSV file varies, and all of the files associated with an export make up the full data set for the query.

The Export resource is used to create an export and get the status of an export. When the export is complete, the links to the CSV files containing the data are available in the resource.

Limitations

Expiration

The data associated with an export expires after 7 days. When data expires, the Export resource removes links to the CSV files and shows that the export has expired. Attempts to retrieve the data after an export expires fail.

CSV File Formatting

Procedures

A procedure is a query and execution plan used to retrieve the data. Each object has a different set of procedures.

Visitor Activity

Fields

Select the visitor activity fields you want to export. Following are the fields that are available for visitor activity. The value for fields must be an array of strings of the available fields.

Abilities

Action Requirements
Create export Prospects > Visitors > View ability
View export Prospects > Visitors > View ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

To view an export with this procedure, the user must have the following:

OR

filter_by_created_at

Retrieves all visitor activity records with a created_at value that is greater than the created_after argument and less than the created_before argument.

Arguments

filter_by_updated_at

Retrieves all visitor activity records with an updated_at value that is greater than the updated_after argument and less than the updated_before argument.

Arguments

NOTE: The range between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.

List Membership

Fields

Select the prospect fields that you want to export. Following are the fields that are available for prospect. The value for fields must be an array of strings of the available fields.

Abilities

Action Requirements
Create export Marketing > Segmentation > Lists > View ability and Prospects > Visitors > View ability
View export Marketing > Segmentation > Lists > View ability and Prospects > Visitors > View ability and ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

To view an export with this procedure, the user must have the following:

OR

filter_by_created_at

Retrieves all list membership records with a created_at value that is greater than the created_after argument and less than the created_before argument.

Arguments

filter_by_updated_at

Retrieves all list membership records with a updated_at value that is greater than the updated_after argument and less than the updated_before argument.

Arguments

NOTE: The range between created_after and created_before or updated_after and updated_before cannot exceed 1 year. When created_before is not specified, the current date is used to gauge the interval.

Prospect

Fields

Select the prospect fields that you want to export. Following are the fields that are available for prospect. The value for fields must be an array of strings of the available fields.

Note: The grade and notes fields are not available through this api.

filter_by_updated_at

Retrieves all prospect records with a updated_at value that is greater than the updated_after argument and less than the updated_before argument.

Abilities

Action Requirements
Create export Prospects > Visitors > View ability
View export Prospects > Visitors > View ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

To view an export with this procedure, the user must have the following:

OR

Arguments

NOTE: The range between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.

Using the Export API

Create

/api/export/version/3/do/create

Used to create an export of an object and procedure.

POST

Request Body

Content-Type must be application/json.

Input Representation

{
    "object": string,
    "fields": [string, string, ....],
    "procedure": {
        "name": string,
        "arguments": {
            "argument name": argument value,
            // additional arguments...
        }
    }
}

Success

Status Code: 200

Output Representation

{
    "export": {
        "id": int,
        "state": string,
        "isExpired": boolean,
        "resultRefs": string OR string[],
        "createdAt": datetime,
        "updatedAt": datetime
    }
}

Errors

Example

Here is a request to execute the visitor activity procedure named filter_by_created_at, which retrieves all visitor activity data where the created_at value is between two dates. In this example, the data is retrieved from December 25, 2019 to December 25, 2020.

POST /api/export/version/3/do/create
HOST: pi.pardot.com
Content-Type: application/json
Authorization: Pardot user_key=U,api_key=A

{
    "object": "visitorActivity",
    "fields": ["id", "prospect_id", "visitor_id", "type_name", "created_at"],
    "procedure": {
        "name": "filter_by_created_at",
        "arguments": {
            "created_after": "2019-12-25 10:00:00",
            "created_before": "2020-12-25 24:59:59"
        }
    }
}

After sending the request as a POST, the response is as follows. From this response we know the export is queued for execution but hasn't started or completed. We suggest waiting a few minutes before checking the Read endpoint for the new status.

{
    "id": 201917,
    "state": "Waiting",
    "isExpired": false
}

Read

/api/export/version/3/do/read/id/{id}

Used to retrieve the status of the export. Once an export is complete, the links to download the results are available in the result body.

GET

Params

{id}: The ID of the export.

Success

Status Code: 200

Output Representation

{
    "export": {
        "id": int,
        "state": string,
        "isExpired": boolean,
        "resultRefs": string OR string[],
        "createdAt": datetime,
        "updatedAt": datetime
    }
}

Errors

Example

After calling the Create endpoint, the ID of the export is given in the response. This ID is used in the URL to call the Read endpoint.

GET /api/export/version/3/do/read/id/201917
HOST: pi.pardot.com
Content-Type: application/json
Authorization: Pardot user_key=U,api_key=A

If the export is waiting to be processed, state is "Waiting", as in the following example.

{
    "id": 201917,
    "state": "Waiting",
    "isExpired": false
}

If the export is finished, state is "Complete" and resultRefs contains URLs to download the CSV files.

{
    "id": 201917,
    "state": "Complete",
    "isExpired": false,
    "resultRefs": [
        "https://www.pardot.com/api/export/version/3/do/downloadResults/id/201917/file/23191",
        "https://www.pardot.com/api/export/version/3/do/downloadResults/id/201917/file/20201",
        "https://www.pardot.com/api/export/version/3/do/downloadResults/id/201917/file/20102"
    ]
}

Query

/api/export/version/3/do/query

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

GET

Params

Success

Status Code: 200

Output Representation

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

{
    "result": {
        "total_results": int,
        "export": [
            {
                "id": int,
                "state": string,
                "isExpired": boolean,
                "resultRefs": string OR string[],
                "createdAt": datetime,
                "updatedAt": datetime
            }
        ]
    }
}

Errors

Download Results

The URLs retrieved from the Read endpoint can be used to download the results of the export. A failure occurs when attempting to download any results from an expired export. See Expiration for more information.

GET

Success

The data represented in CSV format. See the CSV Format section for more information.

Errors

Enums

Export State