Blog
Token
About Us
AiDOOS Wiki
Project Cost Estimation

Welcome to Knowledge Base!

KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

Categories
All
CRM
Salesforce
ERP
SAP
Storage and Backups
Purestorage Netapp Nutanix
Cloud
AWS
Computing
IBM
Database
MongoDB MySQL PostgreSQL
DevOps
Docker Kubernetes Jenkins GitLab
Mobile
React Native Android
Web
React Angular PHP
Programming
Python
CRM-Salesforce
Salesforce Developers

Version 3 and 4 Overview

The Pardot API lets your application access current data within Pardot. Through the API, you can perform several common operations on Pardot objects including the following:

  • create -- Creates an object with the specified parameters.
  • read -- Retrieves information about the specified object.
  • query -- Retrieves objects that match specified criteria.
  • update -- Updates elements of an existing object.
  • upsert -- Updates elements of an existing object if it exists. If the object does not exist, one is created using the supplied parameters.

You must authenticate using a Salesforce OAuth endpoint. See Authentication for more.

Keep a few considerations in mind when you perform requests. For update requests, only the fields specified in the request are updated. All others are left unchanged. If a required field is cleared during an update , the request is declined.

All requests to the API:

  • Must use either HTTP GET or POST
  • Must pass the access token.
  • Must pass Pardot Business Unit ID in an HTTP Pardot-Business-Unit-Id header (obtained using Salesforce OAuth) to authenticate.
  • Must use the correct URL for your Pardot environment. See Test and Production Environments.

These examples use a production environment, so the domain is pi.pardot.com . If you are using a test environment, your domain is pi.demo.pardot.com . See Test and Production Environments.

Request Parameters

Parameter Required Description
object X The object type to be returned by the API request
op X The operation to be performed on the specified object type
id_field X The field to be used as the identifier for the specified object
id X The identifier for the specified objects
access_token X The access token obtained during Authentication
pardot_business_unit_id X The Pardot business unit. For details see Authentication
format The API data format: either xml (default) or json
params Parameters specific to your request; See individual methods for details

The ordering of parameters is arbitrary. Parameters are passed using conventional HTML parameter syntax, with '?' indicating the start of the parameter string (for GET requests only) and '&' as the separator between parameters. With the exception of <format> and <params> , all components are required. Data returned from the API is formatted using JSON or XML 1.0 with UTF-8 character encoding. Keep in mind that some characters in the response can be encoded as HTML entities, requiring client-side decoding. Also, keep in mind that all parameters specified in an API request MUST be URL-encoded before they are submitted.

In general, the API returns XML or JSON containing a current version of the target object's data. But unsuccessful requests return a short response containing an error code and message. See Error Codes & Messages for error descriptions and suggested remedies: Error Codes and Messages

The Pardot API supports several output formats, and each returns different levels of detail in the XML or JSON response. Output formats are defined by specifying the output request parameter. Supported output formats include:

  • full -- Returns all supported data for the Pardot object and all objects associated with it.
  • simple -- Returns all supported data for the Pardot object.
  • mobile -- Returns an abbreviated version of the object data. This output format is ideal for mobile applications.
  • bulk -- Returns basic data for an object (does not provide total object count). Used for querying large amounts of data.

If the output request parameter is not defined, the output format defaults to full . See the XML Response Format sections for each object for details about the formats.

Here's an example of calling the Pardot API using a simple PHP client using the cURL library.

Note: We strongly recommend against using PHP's file_get_contents function to call the Pardot API because it makes error handling cumbersome.

Salesforce Developers

Transitioned from Version 3 to Version 4?

Version 4 was created to accommodate multiple prospects with the same email address. If your Pardot org has the allow multiple prospects with the same email address (AMPSEA) feature enabled, then use version 4. If your Pardot org doesn’t have AMPSEA enabled, use version 3.

To determine if your Pardot org has AMPSEA enabled, check out this guide.

If you want to enable AMPSEA in your Pardot account, use the following guidelines to keep using Pardot APIs.

Update your requests to use the /version/4 path. For example:

Before:

After:

Most of the differences between version 3 and version 4 are in the prospect APIs.

  • New reference field: Prospects can be referenced using the Salesforce CRM Identifier, the fid field. This fid field refers to the ID of the Lead or Contact record in Salesforce. You can find the lead ID (begins with 00Q) or the contact ID (begins with 003) in the URL when viewing a lead or contact record. Or, you can get multiple contacts or lead ID from Salesforce using the export tool. lead_identifier_example
  • Create: Prospects can still be created with a referenced email address. If you call the create API with the same email address multiple times, each call creates a prospect. Previously, you would get an error.
  • Read: When making a read query, querying by email returns all prospects that share that email address. Querying by Pardot id or Salesforce fid only returns the one matching prospect.
  • Update: Because there can be multiple prospects with the same email address, prospects can no longer be updated when referenced via email alone. Instead, use either the Pardot id or Salesforce fid references.
  • Upsert: Upsert query by email always creates a prospect. Upsert by Pardot id or Salesforce fid updates or creates as needed. See Upserting Prospects for more details.
  • Delete: Delete query must reference by Pardot id or Salesforce fid .
  • Batch processing: See examples of batch processing in the Prospect object documentation.

See the Prospect object documentation.

  • Create: Creating an opportunity using a prospect_email reference must correspond to an existing prospect. If there are multiple prospects with that email address, the prospect with the most recent activity date is used. If you want to apply the opportunity to a specific prospect, then reference the prospect using prospect_id .
  • Query: If you query using a prospect_email reference, you receive opportunities that correspond with any prospects that share that email address. if you want a specific prospect then query by the prospect_id .

See the Opportunity Object documentation.

  • Assign: Assigning by prospect_email alone (no prospect_id ) returns an error.

See the Visitor Object documentation.

Read article
Salesforce Developers

Bulk Data Pull via the Pardot API

This document outlines the approach and best practices for pulling large amounts of data out of Pardot via the API.

When you need large amounts of visitor activity data, use the Export API. If you need a different object, see Query the Pardot API for details on how to retrieve the information using the query endpoint.

The Export API is asynchronous and efficiently scales data retrieval based on the available resources. There are more server resources available for the Export API than the query endpoint, which provides faster results without hitting concurrency and API limits to process multiple queries.

Before getting started, review the documentation for the Export API.

Best Practice #1 - Polling for Status Updates

Because export is asynchronous, you can poll the Read endpoint of the Export API to see if the export is done processing. The time an export takes depends on how much data is being exported and the resources available for processing. Because export times can vary, we recommend that you start by setting a polling interval between 30 seconds and a few minutes.

If you run an integration regularly, set your polling intervals to the average of the time taken for a few runs of your integration. For example, if your integration runs daily and retrieves all visitor activity data for the previous day, start with a polling frequency of 1 minute. Note the export durations for a few days, then average those times to find a polling interval. In the example, over a few days you notice that your export finishes with an average duration of 15 minutes. Polling every minute is too often and polls 15 times. If you set the polling interval to 5 minutes, it polls three or four times.

If you run integrations sporadically or infrequently, try increasing the polling interval over time. For example, if you track the number of times the integration has polled, you can calculate a gradually increasing polling interval using this function:

Where n is the index of the poll, starting with 0

Using this function to calculate polling interval, you poll a minute the first time, 2 minutes for the second and continue to increase at larger intervals each time. This process allows the integration to check frequently soon after an export is created to catch the quick running exports but also limit the number of polls for exports that are long-running.

Remember that the Read endpoint of the Export API counts toward API limits, so these tips let you adjust how much of that limit is used by your integration.

Best Practice #2 - Specify Limited Date Ranges

Because the results of the export API are returned only after the query has executed, limiting the date range of the export returns results faster. A way limit date range is to break large date ranges into several smaller ranges.

For example, it's OK to create an export to retrieve a year's worth of visitor activity within a single export by specifying a year duration, like the following.

The issue is that all 12 months of data must be queried in order for the results to be returned. There are cases where your integration can use a smaller data set up front and be refined later as more data from the export becomes available. For example, an integration can work off the last month of data while waiting on a three-month range and then increasing to a twelve-month range.

In this example, you could create three different exports with the three different ranges:

Last month

Three months prior

Eight months prior

Instead of waiting for all twelve months of data to be exported at once, the same data is returned in smaller increments, so you can see the newest data sooner.

Pulling data from a query endpoint in the Pardot API is a straightforward, two-step process. First, log in with your Pardot user email, password, and user key to acquire an API key. Then, use the query endpoint for each data set to pull the data.

Before getting started, review the object documentation and determine which data set you are going to pull. For a data set to be eligible for a bulk data pull, it must have a query operation that supports at least one of the following three sets of search filter criteria parameters:

  • created_before and created_after
  • updated_before and updated_after
  • id_greater_than and id_less_than

Issue an HTTP GET to the appropriate query endpoint to pull the data back. The query response contains up to 200 rows from the data set you have requested.

Best Practice #1 ‐ Use the Bulk Output Format

For bulk data pulls, we strongly recommended that you use the bulk output format, which is highly optimized for performance. The bulk output format disables functionality that displays additional data in the API response such as nested object relationships (for example, campaign name for activities). Additionally, the bulk output format omits information about the total number of rows that matched your query, which enables the API to return a response more quickly.

Best Practice #2 ‐ Avoid Offset

For bulk data pulls, we strongly discourage use of the offset parameter. Instead, iterate through the data set using one of the supported search filter criteria parameters.

As you process the query results in your code, store a high water mark value like the largest id or most recent created_at or updated_at value. Then, on your next query, send that high water mark value as the id_greater_than , created_after , or updated_after search filter parameter value.

Bulk API Request & Response Samples

Example Request & Response (XML)

Example Request & Response (JSON)

Because using the offset parameter is discouraged, let’s see how you can use a high water mark value to iterate through multiple pages of results instead. In this example, you query for all visitor activities that occurred yesterday. The created_after and created_before search filter criteria parameters are perfect for this use case.

To keep things simple, assume there were a total of 5 activities created yesterday (at time of writing, 2016-03-29) at times 02:00, 06:00, 10:00, 14:00, and 18:00. Also assume the API page size limit is 2 rather than 200.

To iterate over the results in the suggested approach, your API integration process would proceed as follows:

  1. Log in to the Pardot API
  2. Pull all visitor activity created after yesterday at midnight ( 2016-03-29T00:00:00 ) and before tonight at midnight ( 2016-03-30T00:00:00 ):

Example Request & Response (JSON)

Note : The example was edited for brevity.

  1. The API has returned two results - the activities from 02:00 and 06:00. Since you are paging by created_at , set your high water mark value to the created_at value of the last record you pull back, 2016-03-30T06:00:00 . You have now retrieved all activities up to that time.
  2. Pull all visitor activity created after your high water mark ( 2016-03-29T06:00:00 ) and before tonight at midnight ( 2016-03-30T00:00:00 ):

Example Request & Response (JSON)

Note : The example was edited for brevity.

  1. The API returns two more results back - the activities from 10:00 and 14:00. Since you are paging by created_at , update your high water mark value to the created_at value of the last record you pull back, 2021-03-29T14:00:00 . You have now retrieved all activities up to that time.
  2. Pull all visitor activity created after your high water mark ( 2021-03-29T14:00:00 ) and before tonight at midnight ( 2021-03-30T00:00:00 ):

Example Request & Response (JSON)

Note : The example was edited for brevity.

  1. The API returns one result back, the activity from 18:00. As the max page size is 2 and the API returned one record, you know you are at the end of the list of records and do not need to query any further. If the API had returned 2 records you would repeat the query process again with a new high water mark. You know it’s safe to stop when the number of records returned by the API is less than the max page size.
Read article
Salesforce Developers

Object Field References

  • Requests create , update , and upsert manipulate fields marked as 'Editable'.
  • 'Required' means that the specified field can't be left without a value during insert and some upsert requests. Pardot declines any update request that clears a required field.
  • During update requests, unless otherwise specified the parameter names submitted to the API and tag names in the API's response match field names within the Pardot user interface.
Field Name Data Type Required Editable Description
<id> integer Pardot ID for this account.
<level> string The level of product for the account.
<website> string Account website.
<vanity_domain> string Custom vanity domain name.
<plugin_campaign_id> integer Plugin ID for account campaign.
<tracking_code_template> string Markup and code for use in tracking templates.
<address1> string Account contact address, line 1.
<address2> string Account contact address, line 2.
<city> string Account contact city.
<state> string Account contact state.
<territory> string Account contact territory.
<zip> integer Account contact ZIP code.
<country> string Account contact country (full string).
<phone> string Account contact phone number.
<fax> string Account contact fax number.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this campaign.
<name> string X Campaign's name.
<cost> integer X Cost related to the campaign.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this custom field.
<name> string X Custom field's name.
<field_id> string API ID for custom field
<type> string X Type of field.
<type_id> integer Pardot ID for custom field's type.
<created_at> timestamp Time custom field is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time custom field was updated. Time is reported in API user's preferred timezone.
<is_record_multiple_responses> boolean X If true, this custom field records multiple responses.
<crm_id> string X The CRM ID of the field you want to map to this custom field.
<is_use_values> boolean X If true, this custom field uses predefined values.
<is_analytics_synced> boolean If true, this custom field is marked to sync with Tableau CRM.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this custom redirect.
<name> string Custom redirect's name.
<Url> string URL for the custom redirect.
<destination> string URL the custom redirect leads to
<campaign> string The campaign associated with this custom redirect.
<created_at> timestamp Time custom redirect is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time custom redirect was updated. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this dynamic content.
<name> string Dynamic content's name.
<embedCode> string Code to embed this dynamic content onto your webpage.
<embedUrl> string URL to embed this dynamic content.
<baseContent> string The default dynamic content.
<basedOn> string Field that this dynamic content is based on.
<variation> node The variation of content that the prospect sees based on the field's value. Note: Information about a variation is returned in a <variation> node in the XML response. It contains the value of the field in the <comparison> tag and the content of the variation in the <content> tag.
<created_at> timestamp Time dynamic content is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time dynamic content was updated. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this email.
<name> string Name of this email.
<subject> string Email subject.
<message> XML Object Contains text and html elements of different formats.
<created_at> Timestamp Time the email is created.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this email click.
<prospect_id> integer Pardot ID for the associated prospect.
<url> string URL of the email click.
<list_email_id> integer Pardot ID for the associated list email. Value not present if null.
<drip_program_action_id> integer Pardot ID for the associated drip program action. Value not present if null.
<email_template_id> integer Pardot ID for the associated email template. Value not present if null.
<tracker_redirect_id> integer Pardot ID for the associated tracker redirect. Value not present if null.
<created_at> timestamp Time that email click occurs. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this form.
<name> string Form's name.
<campaign_id> string Pardot ID of the campaign associated with this form.
<embed_code> string The code used to embed the form on your webpage.
<created_at> timestamp Time form is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time form was updated. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this identified company.
<name> string Identified Company's name.
<street_address> string Identified Company's street address.
<city> string Identified Company's city.
<state> string Identified Company's state.
<postal_code> string Identified Company's postal code.
<country> string Identified Company's country.
<email> string Identified Company's email address.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID of this lifecycle history.
<prospect_id> integer Pardot's ID for the prospect in this stage.
<previous_stage_id> integer Pardot ID of the stage this prospect previously was in.
<next_stage_id> integer Pardot ID of the stage this prospect is in next.
<seconds_elapsed> integer Number of seconds for prospect to get to current stage.
<created_at> timestamp Time lifecycle history is created in Pardot. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID of this lifecycle stage.
<name> string Lifecycle stage's name.
<position> integer Lifecycle stage's position in lifecycle.
<is_locked> boolean If true, lifecycle stage is locked.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID of this list.
<name> string X List's name (internal to Pardot).
<is_public> boolean X If true, list shows on EPC pages to prospects.
<is_dynamic> boolean If true, list has prospects dynamically added to it via a set of chosen rules.
<title> string X List's title (visible to subscribers)
<description> string X List's description.
<is_crm_visible> boolean X If true, list is visible in CRM, and can be added to, or removed from.
<created_at> timestamp Time list is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time list was updated. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this list membership.
<list_id> integer X Pardot ID of the list for this membership.
<prospect_id> integer X Pardot ID of the prospect for this membership.
<opted_out> integer X If value is 1, the prospect is unsubscribed from receiving emails from this list.
<created_at> timestamp Time that this membership is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time that this membership was updated. Time is reported in API user's preferred timezone.

Additional prospect fields available for Export

When using the v3 Export API or v4 Export API to export list membership, the following fields are selectable for export in addition to the list membership fields listed above.
Note : The following fields are only available via the Export API and are only exported if selected via fields parameter specified in export create request.

Field Name Data Type Description
<created_by> integer Pardot ID for the user who created this object.
<updated_by> integer Pardot ID for the user who last updated this object.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this opportunity.
<campaign_id> integer X X Pardot ID of the campaign associated with this opportunity.
Note : Information about an opportunity's campaign association is returned in a <campaign> node in the XML response. However, updates to campaign associations are made by providing campaign_id= <campaign_id> during an <UPDATE> request. See XML Response in the Campaign documentation for more details.
<name> string X X Opportunity's name
<value> float X X Opportunity's value.
Restrictions : The value must be a positive numeric value.
<probability> integer X X Opportunity's probability.
Restrictions : The value must be a positive integer from 0 through 100, inclusive.
<type> string X Opportunity's type.
<stage> string X Opportunity's stage.
<status> string X Opportunity's status.
Restrictions : status must be either won, lost, or open.
<closed_at> timestamp X Opportunity's closed date.
Note If this field is left blank, the closed_at timestamp (Closed Date within the app) is not set, even when the Opportunity's stage, status, or probability are set to indicate opportunity closure.
<created_at> timestamp Time opportunity is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time opportunity was updated in Pardot. Time is reported in the API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this profile.
<name> string Profile's name.
Field Name Data Type Required Editable Description
<id> integer X Required. Pardot ID for this profile criteria.
<name> string Profile criteria's name.
<matches> string X The matching status of this profile criteria with the current prospect.
Restrictions: Updates can be performed by using the values match , nomatch , or unknown .
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this prospect.
<campaign_id> integer X Pardot ID of the campaign associated with this prospect
Note : Information about a prospect's campaign association is returned in a <campaign> node in the XML response. However, updates to campaign associations are made by providing campaign_id= <campaign_id> during an <UPDATE> request. See XML Response Formats in Prospects for more details.
<salutation> string X Prospect's formal prefix.
<first_name> string X Prospect's first name.
<last_name> string X Prospect's last name.
<email> string X X Prospect's email address.
<password> string X Prospect's password.
<company> string X Prospect's company.
<prospect_account_id> integer X Prospect's account ID.
<website> string X Prospect's website URL.
<job_title> string X Prospect's job title.
<department> string X Prospect's department.
<country> string X Prospect's country.
<address_one> string X Prospect's address, line 1.
<address_two> string X Prospect's address, line 2.
<city> string X Prospect's city.
<state> string X Prospect's US state.
<territory> string X Prospect's territory.
<zip> string X Prospect's postal code.
<phone> string X Prospect's phone number.
<fax> string X Prospect's fax number.
<source> string X Prospect's source.
<annual_revenue> string X Prospect's annual revenue.
<employees> string X Prospect's number of employees.
<industry> string X Prospect's industry.
<years_in_business> string X Prospect's number of years in business.
<comments> string X Comments about this prospect.
<notes> string X Notes about this prospect
Note : Available for export, but only exported if selected via fields parameter specified in export create request.
<score> integer X Prospect's score.
<grade> string Prospect's letter grade
Note : Available for export, but only exported if selected via fields parameter specified in export create request.
<last_activity_at> timestamp Time stamp of this prospect's latest visitor activity; Time is reported in API user's preferred timezone.
<recent_interaction> string Describes the prospect's most recent interaction with Pardot (Not available for V3/V4 export) .
<crm_lead_fid> string Prospect's lead ID in a supported CRM system.
<crm_contact_fid> string Prospect's contact ID in a supported CRM system.
<crm_owner_fid> string Prospect's owner ID in a supported CRM system.
<crm_account_fid> string Account ID in a supported CRM system.
<crm_last_sync> timestamp Last time this prospect was synced with a supported CRM system.
<crm_url> string URL to view the prospect within the CRM system (Not available for V3/V4 export) .
<is_do_not_email> boolean X If value is 1, prospect prefers not to be emailed.
<is_do_not_call> boolean X If value is 1, prospect prefers not to be called.
<opted_out> boolean If value is 1, prospect has opted out of marketing communications.
<is_reviewed> boolean X If value is 1, prospect has been reviewed.
<is_starred> boolean X If value is 1, prospect has been starred.
<is_archived> boolean X If value is 1, prospect has been archived.
<created_at> timestamp Time prospect is created in Pardot; Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time prospect was updated in Pardot; Time is reported in API user's preferred timezone.

Additional prospect fields available for Export

When using the v3 Export API or v4 Export API to export prospects, the following prospect fields are selectable for export in addition to the prospect fields listed above.
Note : The following fields are only available via the Export API and are only exported if selected via fields parameter specified in export create request.

Field Name Data Type Description
<converted_at> timestamp Time when prospect was converted from visitor; Time is reported in API user's preferred timezone
<converted_from_object_type> string Type of object associated with visitor activity that resulted in prospect being converted from visitor. Supported values include 'Form', 'FormHandler', 'LandingPage', 'MultivariateTestVariation', and 'Video'.
<converted_from_object_name> string Name of object associated with visitor activity that resulted in prospect being converted from visitor.
<do_not_sell> boolean Indicates whether the visitor recorded an activity with the Global Privacy Control Header enabled.
<is_email_hard_bounced> boolean if value is 1, prospect email address has hard bounced.
<email_bounced_at> timestamp Time when prospect email address hard bounced; Time is reported in API user's preferred timezone.
<email_bounced_reason> string Reason why prospect email address hard bounced.
<first_assigned_at> timestamp Time prospect was first assigned to a user; Time is reported in API user's preferred timezone.
<first_activity_at> timestamp Time when first visitor activity occurred for this prospect; Time is reported in API user's preferred timezone.
<first_referrer_url> string First referrer's URL.
<first_referrer_type> string First referrer's vendor and type (such as 'Google Natural Search').
<first_referrer_query> string First referrer's search query.
<campaign_parameter> string Prospect's campaign parameter utm_campaign from Google Analytics.
<medium_parameter> string Prospect's medium parameter utm_medium from Google Analytics.
<source_parameter> string Prospect's source parameter utm_source from Google Analytics.
<content_parameter> string Prospect's content parameter utm_content from Google Analytics.
<term_parameter> string Prospect's term parameter utm_term from Google Analytics.
<created_by> integer Pardot ID for the user who created this object.
<updated_by> integer Pardot ID for the user who last updated this object.
x

Note: Prospect account fields are fully customizable. To get the most accurate field metadata for your Pardot account, use the describe operation on the prospectAccount API endpoint.

Field Name Data Type Required Editable Description
<id> integer X Pardot ID of the prospect account.
<name> string X The name of the prospect account.

Additional prospect account fields available for Export

When using the v3 Export API or v4 Export API to export prospect account, the following fields are selectable for export in addition to the prospect account fields listed above.
Note : The following fields are only available via the Export API and are only exported if selected via fields parameter specified in export create request.

Field Name Data Type Description
<created_by> integer Pardot ID for the user who created this object.
<updated_by> integer Pardot ID for the user who last updated this object.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this tag.
<name> string Tag's name.
<created_at> timestamp Time tag is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time tag was updated. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID of the tag object.
<tag_id> integer The Pardot ID of the tag.
<type> string The type of object associated with the tag.
<object_id> integer The Pardot ID of the object.
<created_at> timestamp Time tag is associated with the object in Pardot. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID of the user.
<email> string User's email address.
<first_name> string User's first name.
<last_name> string User's last name.
<job_title> string User's job title
<role> string User's role.
<created_at> timestamp Time user is created in Pardot. Time is reported in the API user's preferred timezone.
<updated_at> timestamp Last time user was updated in Pardot. Time is reported in the API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer Pardot ID for this visit.
<visitor_id> integer Pardot ID for the associated visitor.
<prospect_id> integer Pardot ID for the associated prospect.
<visitor_page_view_count> integer Number of page views for this visit.
<first_visitor_page_view_at> timestamp Time of first page view for this visit. Time is reported in API user's preferred timezone
<last_visitor_page_view_at> timestamp Time of last page view for this visit. Time is reported in API user's preferred timezone.
<duration_in_seconds> integer Length of this visit.
<campaign_parameter> string Visit's campaign parameter utm_campaign from Google Analytics.
<medium_parameter> string Visit's medium parameter utm_medium from Google Analytics.
<source_parameter> string Visit's source parameter utm_source from Google Analytics.
<content_parameter> string Visit's content parameter utm_content from Google Analytics.
<term_parameter> string Visit's term parameter utm_term from Google Analytics.
<created_at> timestamp Time visit is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time visit was updated in Pardot. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this visitor.
<page_view_count> integer Number of page views by this visitor.
<ip_address> string Visitor's IP address.
<hostname> string Visitor's hostname.
<campaign_parameter> string Visitor's campaign parameter utm_campaign from Google Analytics
<medium_parameter> string Visitor's medium parameter utm_medium from Google Analytics.
<source_parameter> string Visitor's source parameter utm_source from Google Analytics.
<content_parameter> string Visitor's content parameter utm_content from Google Analytics
<term_parameter> string Visitor's term parameter utm_term from Google Analytics.
<created_at> timestamp Time visitor is created in Pardot. Time is reported in API user's preferred timezone.
<updated_at> timestamp Last time visitor was updated in Pardot. Time is reported in API user's preferred timezone.

When using either the v3 Export API or the v4 Export API to export visitors, the following prospect fields are selectable for export in addition to the Visitor fields listed earlier.

Field Name Data Type Description
< do_not_sell > boolean Indicates whether the visitor recorded an activity with the Global Privacy Control Header enabled.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this visitor activity
<prospect_id> integer Pardot ID for the associated prospect
<visitor_id> integer Pardot ID for the associated visitor
<type> integer Visitor activity's type number. See the listing that follows.
<type_name> string Visitor activity's type name. See the listing that follows.
<details> string Details about this visitor activity. Examples include:
- The name of the object associated with this activity.
- The search phrase used in a site search query.
- Others as your needs require.
<email_id> integer Pardot ID of the email associated with this visitor activity.
Note: This node appears only if this visitor activity has an email associated with it.
<email_template_id> integer Pardot ID of the email template associated with this visitor activity.
Note: This node appears only if this visitor activity has an email associated with it.
<list_email_id> integer Pardot ID of the list email associated with this visitor activity.
Note: This node appears only if this visitor activity has an email associated with it.
<form_id> integer Pardot ID of the form associated with this visitor activity.
Note: This node appears only if this visitor activity has a form associated with it.
<form_handler_id> integer Pardot ID of the form handler associated with this visitor activity.
Note: This node appears only if this visitor activity has a form handler associated with it.
<site_search_query_id> integer Pardot ID of the site search query associated with this visitor activity.
Note: This node appears only if this visitor activity has a site search query associated with it.
<landing_page_id> integer Pardot ID of the landing page associated with this visitor activity.
Note: This node appears only if this visitor activity has a landing page associated with it.
<paid_search_ad_id> integer Pardot ID of the paid search ad associated with this visitor activity.
Note: This node appears only if this visitor activity has a paid search ad associated with it.
<multivariate_test_variation_id> integer Pardot ID of the multivariate test variation associated with this visitor activity.
Note: This node appears only if this visitor activity has a multivariate test variation associated with it.
<file_id> integer Pardot ID of the file associated with this visitor activity.
Note: This node appears only if this visitor activity has a file associated with it.
<custom_redirect_id> integer Pardot ID of the custom redirect associated with this visitor activity. Note: This node appears only if this visitor activity has a custom redirect associated with it.
<campaign> object Campaign information including id, name, and cost. (Not available for V3/V4 export) .
<created_at> timestamp Time that visitor activity occurred. Time is reported in API user's preferred timezone.
<updated_at> timestamp Time that visitor activity update occurred. Time is reported in API user's preferred timezone.

Visitor Activity Types

Visitor Activities have the following values for <type>

  • 1 - Click
  • 2 - View
  • 3 - Error
  • 4 - Success
  • 5 - Session (Omitted from Synchronous and Export endpoints)
  • 6 - Sent
  • 7 - Search
  • 8 - New Opportunity
  • 9 - Opportunity Won
  • 10 - Opportunity Lost
  • 11 - Open
  • 12 - Unsubscribe Page
  • 13 - Bounced
  • 14 - Spam Complaint
  • 15 - Email Preference Page
  • 16 - Resubscribed
  • 17 - Click (Third Party)
  • 18 - Opportunity Reopened
  • 19 - Opportunity Linked
  • 20 - Visit
  • 21 - Custom URL click
  • 22 - Olark Chat
  • 23 - Invited to Webinar
  • 24 - Attended Webinar
  • 25 - Registered for Webinar
  • 26 - Social Post Click
  • 27 - Video View
  • 28 - Event Registered
  • 29 - Event Checked In
  • 30 - Video Conversion
  • 31 - UserVoice Suggestion
  • 32 - UserVoice Comment
  • 33 - UserVoice Ticket
  • 34 - Video Watched (≥ 75% watched)
  • 35 - Indirect Unsubscribe Open
  • 36 - Indirect Bounce
  • 37 - Indirect Resubscribed
  • 38 - Opportunity Unlinked
  • Other - Unknown
Field Name Data Type Required Editable Description
<id> integer Pardot ID for this visitor page view.
<url> string Page view. URL
<title> string Page title.
<created_at> timestamp Time page view occurred. Time is reported in API user's preferred timezone.
Field Name Data Type Required Editable Description
<id> integer X Pardot ID for this visitor referrer.
<referrer> string Referrer's URL.
<vendor> string Referrer's vendor (such as 'Google' or 'Yahoo').
<type> string Referrer's type (such as 'Natural Search').
<query> string Referrer's search query.
Read article
Salesforce Developers

Pardot API Quick Start

Getting started can be daunting, especially if you're not an experienced developer. This tutorial walks you through a few real-life tasks so you can start automating and extending Pardot.

In this guide:

  • We implement authentication using an OAuth2.0 flow.
  • Make some example calls and complete a basic task.

Before you begin, make sure you have:

  • A Salesforce admin to create a connected app and gather information.
  • A Salesforce user with SSO enabled for Pardot.
  • A configured Pardot Business Unit.
  • Selected which OAuth flow works best for your case. This tutorial uses the Web Server OAuth flow.

This tutorial requires background knowledge of connected apps and authentication. If you're unfamiliar with these topics, we strongly recommend that you check out these resources first:

  • Salesforce Help: Connected App and OAuth Terminology
  • Trailhead module: Connected App Basics
  • Trailhead module: Build a Connected App for API Integration

After you familiarize yourself with the basics, come back to this tutorial.

Warning

The calls you make during this tutorial have the potential to impact both your Salesforce and Pardot settings and data. If you’re just testing the API, make sure that you’re using a sandbox account. If you’re using this tutorial to set up your production account, use caution.

To authenticate to use Pardot APIs, you must use an SSO-enabled Salesforce user who has Pardot access, and an OAuth flow with a connected app. Implementing authentication can be tricky, so we walk through an example here.

Step 1: Create the Connected App

The first step in authentication is creating a connected app. A connected app is a framework that enables an external application to integrate with Salesforce using APIs and standard protocols like OAuth. Connected apps use these protocols to authenticate, authorize, and provide single sign-on (SSO) for external apps. To put it simply, a connected app represents an integration.

To set up a connected app, have a Salesforce admin follow these steps:

  1. From Salesforce Setup, in the Quick Find box, enter App Manager , and then select App Manager .
  2. Click New Connected App .
  3. Name the connected app, and enter contact details for the app owner.
  4. In the API section, select the Enable OAuth Flows .
  5. Enter a Callback URL. The callback URL is used to redirect users after authentication in browser-based flows. In this example, we use https://my.example.com/myapp . If you’re using a browser-based flow (such as Web Server Flow or User Agent Flow), the URL must match the URL you pass as a callback to OAuth endpoints. If you aren’t using a browser-based flow, the URL entered isn't used.
  6. Under Selected OAuth Scopes , add Access Pardot services , which give the app access to Pardot. For more complex scenarios, such as using refresh tokens, select other scopes as well.
  7. Save the connected app.

This just scratches the surface of connected apps. If you’d like to learn more, like how to restrict access to certain users, check out these resources:

  • Connected App Salesforce Help
  • Connected App Trailhead

Step 2: Gather Important Information

Now that you have a connected app, let’s gather some important information you need handy to finish setting up authentication.

The primary details are:

  • Connected App Consumer Key: a unique identifier for your connected app.
  • Connected App Consumer Secret: a password for the connected app.
  • Business Unit IDs: Because a Salesforce org can have multiple business units, the ID routes the API request to the correct business unit. You need the ID even if you have only one business unit.
  • Salesforce User: A Salesforce user with SSO enabled for Pardot.

Since all this information is sensitive, carefully consider how to securely share these details with other team members.

Find the Consumer Key and Secret

  1. From Salesforce Setup, in the Quick Find box, enter App Manager , and then select App Manager .
  2. Go to your connected app and select View .
  3. Copy your consumer key.
  4. Reveal and copy your consumer secret.

Find the Pardot Business Unit IDs

  1. From Marketing Setup, in the Quick Find box, enter Pardot , and then select Pardot Account Setup .
  2. Copy the business unit ID for the Pardot instance you want to use.

Choose the Integration User

For the integration user, we recommend that you create a unique user for each specific app integration. The user must be SSO-enabled and have access to Pardot.

Step 3: Implement OAuth Flow

Salesforce has several OAuth flows to meet your unique security and integration needs. In this tutorial, we use the Web Server OAuth flow. This flow is ideal for when you don't want to store the end user's credentials in your system. To learn more about your options and how to choose the best OAuth flow for your integration, check out Salesforce OAuth Help Documentation.

  1. Have your integration direct the user to Salesforce’s OAuth authorization endpoint:

    https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://my.example.com/myapp

    • Replace CLIENT_ID with your connected app consumer key.
    • Replace https://my.example.com/myapp with your redirect URI.

  2. If the user doesn't have an active session, they’re prompted to log into Salesforce.

  3. The user grants the app permission.

  4. After the user has logged in and allowed the app, Salesforce redirects you back to the redirect_uri passed in to the authorize endpoint: https://my.example.com/myapp?code=<CODE>

  5. Your server-side code exchanges this code for an access token by making a POST request to the Salesforce OAuth token endpoint:

  1. After Salesforce validates the connected app credentials and authorization code, the endpoint responds with an access token:

The access token can be used to make calls to the Pardot API. The code was exchanged for the access token on the server side and not from the user’s browser. Because of how the code was exchanged, there's no opportunity for malicious JavaScript to steal the access token.

After you've implemented authorization, you can start working with the Pardot API.

The Pardot API lets your application access current data within Pardot. Through the API, you can perform several common operations on Pardot objects including the following:

  • create : Creates an instance of the object with the specified parameters.
  • read : Retrieves information about the specified object.
  • query : Retrieves objects that match specified criteria.
  • update : Updates elements of an existing object.
  • upsert : Updates elements of an existing object if it exists. If the object doesn’t exist, one is created using the supplied parameters.

Developers must authenticate using a Salesforce OAuth endpoint or the Pardot API login endpoint before issuing Pardot API requests. Refer to the Authentication section for details about this procedure.

Keep in mind a few considerations when you perform requests. For update requests, only the fields specified in the request are updated. All others are left unchanged. If a required field is cleared during an update, the request is declined.

Request Format

All requests to the API must:

  • Use either HTTP GET or POST. Version 5 also supports PUT and DELETE requests.
  • Pass access token in an HTTP Authorization header.
  • Pass Pardot Business Unit ID in an HTTP Pardot-Business-Unit-Id header.
  • Use the correct URL for your Pardot environment.

Our First GET Request

In this example, we want to get a list of all custom fields in a business unit.

Before you begin, make sure you've authenticated and have a valid access token. For simplicity in this example, these calls are written in HTTP.

Breaking Down the Request

Let's break down the call and identify its parts, starting with the uniform resource identifier (URI). GET 'https://<ENVIRONMENT_URL>/api/<OBJECT>/version/<API_VERSION>/do/<OPERATION>?format=<FORMAT>

  • Environment URL : In the example, we use pi.pardot.com, but you use the URL that matches your environment type. Demos, developer orgs, and sandbox environments are hosted on the domain pi.demo.pardot.com. Training and production environments are hosted on the domain pi.pardot.com.
  • Object : The object we're requesting data for. In our example, we're querying the CustomField object.
  • API version : The version of the API you're using. Here, we use v4.
  • Operation : The operation you're performing. Here, we use query .
  • Format : The output format, either XML or JSON. Here, we use json .

Now that we've explained the URI, let's examine the header lines in the call.

  • 'Authorization: Bearer <ACCESS TOKEN>' lets Pardot know that you’ve authenticated and have permission to access data.
  • 'Pardot-Business-Unit-Id: <BUSINESS UNIT ID>' lets Pardot know which business unit you want data from.
  • Host : The URL for your Pardot environment.

Breaking Down the Response

The call returns the business unit's custom fields and their metadata.

Learn more about each object's fields in the Object Field Reference documentation.

Our First POST Request

Warning: If you’re following along with your Pardot account, this next example creates a list in your account. Either use a sandbox account, or tailor the example to fit your needs.

In this example, we create a list for a spring nurturing campaign.

Before you begin, make sure you've authenticated and have a valid access token.

Breaking Down the Request

We went over the URI and the authorization and business unit headers in the GET example. Let's cover the other components:

  • Content-Type: application/x-www-form-urlencoded : Lets the server know what kind of data the request includes.
  • name=Spring Leads Nurture : Sets the list's internal name to "Spring Leads Nurture".
  • title=Spring Leads : Titles the list "Spring Leads".
  • description=A list to nurture spring leads : Adds a text description to the list.

Breaking Down the Response

When we send this request to the server, Pardot responds by creating a list with the criteria that we specified. The response looks like this:

Going Further

Let's take the example a step further and add a prospect to our new list. Remember that completing this task changes data in Pardot, so proceed with caution.

Before you begin, make sure you've authorized and have a valid access token. For simplicity in this example, we make these calls in our command-line interface using cURL.

First, copy the list ID for the list you want to add a prospect to. Then, find the IDs for the prospect you want to add to the list. You can use query on the Prospect object to get ID.

  • List ID: 1000
  • Prospect ID: XXXXX

Notice that the URI includes the prospect's ID: XXXXX. When we send this request, Pardot adds that prospect to the list with the ID 1000.

That's a wrap! Now that you've made some basic calls, we hope you feel confident about using the Pardot API to extend and automate your business!

  • Connected Apps
  • Authorize Apps with OAuth
  • Connected App and OAuth Terminology
  • Find a Trailblazer Community Group near you and talk with other Pardot developers about how they use APIs.
Read article
Salesforce Developers

Version 3 Home

Version 3 of Pardot APIs are for accounts that don't have the allow multiple prospects with the same email address (AMPSEA) feature enabled. See Version 3 and 4 Overview to learn more.

Object APIs Description
Accounts View information about the Pardot account the API user is logged in to
Batch Email Clicks View email link click statistics
Campaigns Work with Pardot Campaigns
Custom Fields Work with user-created fields for tracking prospect data
Custom Redirects View custom Pardot links that track link clicks
Dynamic Content Work with personalized content that displays based on what you know about the viewer
Email Templates View information about reusable email layouts
Emails Send emails to prospects and view data about those emails
Forms View information about forms that collect visitor data
Lifecycle History View how a prospect moves through the sales journey
Lifecycle Stage View which stage a prospect is in during the sales journey
List Membership Add and remove prospects to and from lists
Lists Work with lists of prospects used to send list emails or to feed engagement programs
Opportunities View Pardot read-only opportunities
Prospect Accounts Group prospects that work for the same company
Prospects Work with identified visitors
Tags View tags used to organize Pardot assets and prospects
TagObject Identify objects that are tagged
Users Work with Pardot users in your organization
Visitors Work with people who interact with your website and other assets
Visits Work with visits to your website and other assets
Visitor Activities View how visitors have interacted with your website and other assets
Other APIs Description
Export Lets you retrieve large amounts of Pardot data
Import Lets you add or update large amounts of Pardot data
Read article