×

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
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.
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
Salesforce Developers

Account Object

Use the account resource to learn about the current user's Pardot account, such as the address, website URL, and account level. Learn more about accounts in Salesforce Help.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

Resource Name Operation Description
Account Read GET Request information about the Pardot account for the current user.

Request information about the Pardot account for the current user.

URI

Example

Request information about the Pardot account for the current user.

XML Response

Tag Description
<account> Parent tag. Contains information about the current user's Pardot account. For more information about account fields, see Account.
Read article
Salesforce Developers

Email Click Object

Pardot emails can contain links to download files. Use email click resources to learn more about how your prospects interact with the email links. Learn more about email clicks in Salesforce Help.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

Resource Name Operation Description
Email Clicks Query GET Request information for the email clicks that matches the specified criteria.

Request information for email clicks that match the specified criteria. You can specify the email clicks and the fields to request. A maximum of 200 are returned.

URI

Parameters to Select Email Clicks

Use these parameters to specify which email clicks are returned. Parameters can be used in any combination and in any order unless otherwise specified.

Notes:

  • Parameters must be URL-encoded.
  • Dates and times must use GNU Date Input Syntax (yyyy-mm-dd:hh:ss ).
  • For a full listing of email clicks fields see Object Field References.
Parameter Type Possible Values Description
created_after string today , yesterday , last_7_days , this_month , last_month , <custom_time> Request email clicks created after the specified time. Example: To request forms created in 2020, use /api/emailClicks/version/3/do/query?created_after=2019-12-31 24:59:59 .
created_before string today , yesterday , last_7_days , this_month , last_month , <custom_time> Request email clicks created before the specified time. Doesn’t include email clicks created at the specified time. Example : To request email clicks created before today (but not created today), use /api/emailClicks/version/3/do/query?created_before=today .
id_greater_than integer Any positive integer Request email clicks that have a Pardot ID greater than the specified number. Example: to request email clicks resulting from emails that were sent by the email list with Pardot ID 126xx, and that have a Pardot ID greater than 123, use api/emailClick/version/3/do/query?id_greater_than=123&list_email_id=126xx .
list_email_id integer Any positive integer Selects only email clicks generated by assets whose list email matches the specified Pardot ID. Example: to request email clicks from emails that were sent by the email list with Pardot ID 1263xx, use /api/emailClick/version/3/do/query?list_email_id=1263xx
drip_program_action_id integer Any positive integer Deprecated. Selects only email clicks generated by an engagement program action with the specified Pardot ID.
email_template_id integer Any positive integer Selects only email clicks generated by the email template with the specified Pardot ID.
tracker_redirect_id integer Any positive integer Selects only email clicks generated by the tracker redirect with the specified Pardot ID.
Tag Description
<result> Parent tag. Contains information about the email clicks that match the parameters specified in your query.
<total_results> Contains the number of email clicks selected by the query. Note: The query request returns a maximum of 200 email clicks. If your query matches more than 200 email clicks, you can make several requests to retrieve all matching records.
<emailClick> The information for a single email click. See Email Clicks in Object Field References.
Read article
Salesforce Developers

Campaign Object

A Pardot campaign tracks the first interaction that a person has with your online marketing materials. Associate your assets to a Pardot campaign to organize and track your marketing efforts. Learn more about Pardot campaigns in Salesforce Help.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

Resource Name Operations Description
Campaign Create POST Create a campaign record.
Campaign Read GET Request information for a single campaign.
Campaign Query GET Request information for the campaigns that match the specified criteria.
Campaign Update POST Update a campaign's information, including campaign fields.

Note: We recommend using Salesforce Connected Campaigns. When Connected Campaigns is enabled, only Campaign Read and Campaign Query are available.

Create a campaign with the specified fields.

URI

Parameters

You can use any campaign field as a parameter. For a list of campaign fields, see Campaign.

Example

Create a campaign with the name New Campaign and a cost of 2,000.

Request information for a single campaign.

URI

Replace <ID> with the Pardot ID of the campaign.

Example

Request information for the campaign with ID 12341xxx.

Request information about the campaigns that match the specified criteria. You can specify which campaigns and which fields to request. A maximum of 200 campaigns are returned, unless you specify the output as mobile. If you specify the output as mobile, then all campaigns are returned.

Note: To request information about a specific campaign, use Campaign Read.

URI

Parameters to Select Campaigns

Use these parameters to specify which campaigns are returned. Parameters can be used in any combination and in any order unless otherwise specified.

Notes:

  • Parameters must be URL-encoded.
  • Dates and times must use GNU Date Input Syntax (yyyy-mm-dd:hh:ss ).
  • For a full listing of campaign fields see Object Field References.
Parameter Type Possible Values Description
created_after string today , yesterday , last_7_days , this_month , last_month , <custom_time> Request campaigns created after the specified date and time. Example: To request forms created in 2020, use /api/campaigns/version/3/do/query?created_after=2019-12-31 24:59:59 .
created_before string today , yesterday , last_7_days , this_month , last_month , <custom_time> Request campaigns created before the specified date and time. Doesn’t include campaigns created at the specified time. <custom_time> Example : to request campaigns created before today (but not created today), use /api/campaign/version/3/do/query?created_before=today .
id_greater_than integer Any positive integer Request campaigns that have a Pardot ID greater than the specified number.
id_less_than integer Any positive integer Returns campaigns that have a Pardot ID less than the specified number.
name string string Request campaigns with the specified name.
updated_after string today , yesterday , last_7_days , this_month , last_month , <custom_time> Request campaigns that were last updated after the specified date and time.
updated_before string today , yesterday , last_7_days , this_month , last_month , <custom_time> Request campaigns that were last updated before the specified date and time.

Parameters to Specify Which Results Are Returned

Use these parameters to specify which campaign fields are returned, and how the campaigns are sorted.

Parameter Type Possible Values Description
limit integer Any integer from 1 through 200. The number of campaigns to return. Default value is 200.
offset integer Any positive integer The number of campaigns to omit from the response (the number to "skip over"). Example: Retrieve a list of campaigns, omitting the 50 most recently updated campaigns. Sort the query by the updated_at field and use offset=50: api/campaign/version/3/do/query?sort_by=updated_at&offset=50
sort_by string created_at , id , name , updated_at , cost The field by which the results are sorted. See Sort Order.
sort_order string ascending, descending The sort order. The default value depends on which sort_by value you specify. See Sort Order.

Sort Order

Use sort_by to specify which field Pardot uses to sort the results. Different fields have different default sort orders.

Value Default Sort Order Description
created_at descending Sort the results by the campaigns' created_at timestamps.
id ascending Sort the results by the campaigns' id fields.
name ascending Sort the results by the campaigns' name fields.
updated_at descending Sort the results by the campaigns' updated_at timestamps.
cost descending Sort the results by the campaigns' cost fields.

Example

Request a list of campaigns, sorted in ascending order by cost.

Update a campaign's information, including campaign fields. Fields that aren’t specified in the request aren’t changed. To clear a field, use a null value.

Returns an updated version of the campaign.

URI

Replace <ID> with the Pardot ID of the campaign.

Parameters

You can use any campaign field as a parameter. For a list of campaign fields, see Object Field References.

Example

To update a campaign's name to "March Webinar" and reset the cost as blank, use the following POST command:

The XML response for a query request contains information about multiple campaigns. The XML response for a read request contains information about a single campaign.

XML Response for Campaign Query

Tag Description
<result> Parent tag. Contains the campaigns that match the parameters specified in your query.
<total_results> The number of campaigns selected by the query. Note: The query request returns a maximum of 200 campaigns. If your query matches more than 200 campaigns, you can make several requests to retrieve all matching records.
<campaign> The information for a single campaign. For information about campaign fields, see Campaign.

XML Response for Campaign Read

Tag Description
<campaign> The information for a single campaign. For information about campaign fields, see Campaign.
Read article
Salesforce Developers

Custom Field Object

Use custom fields to capture and track more data about your prospects. You can use custom fields in forms and sync the Pardot fields with Salesforce fields. Learn more about Pardot fields in Salesforce Help.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

Resource Name Operation Description
Custom Field Create POST Create a custom field.
Custom Field Read GET Request detailed information for a single custom field.
Custom Field Update POST Update a custom field's value.
Custom Field Delete POST or DELETE Delete a custom field.
Custom Field Query GET Request information for the custom fields that match the specified criteria.

Create a custom field with the specified name and API name.

URI

Parameters

The following parameters are required to create a new custom field:

Parameter Type Description
name string The name of the custom field.
field_id string The API name of the custom field.

Parameters can include any editable field in the Custom Field object. For a list of fields in the Custom Field object, see Custom Field.

Example

Create a custom field of type integer with the name "Partner Level" and the API name "PARTNER_LEVEL_c," which doesn’t allow multiple values.

Delete a custom field specified by custom field ID.

URI

Replace <ID> with the ID of the custom field.

Example

Delete the custom field with ID 5746xx.

Request information about the specified custom field.

URI

Replace <ID> with the ID of the custom field.

Example

Request the information for the custom field with ID 12341xxx

Request information about custom fields that match the specified criteria. You can specify which custom field records and fields to request. A maximum of 200 custom fields are returned. To return all custom fields, specify the output as mobile .

To request information about a specific custom field, use Custom Field Read.

URI

Parameters to Select Custom Fields

Use these parameters to specify which custom fields are returned. Parameters can be used in any combination and any order unless otherwise specified.

Notes:

  • Parameters must be URL-encoded.
  • Dates and times must use GNU Date Input Syntax (yyyy-mm-dd:hh:ss ).
  • For a full listing of custom fields see Object Field References.
Parameter Type Options Description
created_after string today , yesterday , last_7_days , this_month , last_month , <custom_time> Request custom fields created after the specified time. Example: To request forms created in 2020, use /api/customField/version/3/do/query?created_after=2019-12-31 24:59:59 .
created_before string today , yesterday , last_7_days , this_month , last_month , <custom_time> Request custom fields created before the specified date and time. Does not include custom fields created at the specified time. <custom_time> Example : to request custom fields created before today (but not created today), use /api/customField/version/3/do/query?created_before=today .
id_greater_than integer Any positive integer Requests custom fields that have an ID greater than the specified number.
id_less_than integer Any positive integer Returns custom fields that have an ID less than the specified number.

Parameters to Specify Which Results Are Returned

Use these parameters to specify which custom fields are returned, and how the custom fields are sorted.

Parameter Type Options Description
limit integer Any integer from 1 through 200 The number of custom fields to return. Default value is 200.
offset integer Any positive integer The number of custom fields to omit from the response (the number to "skip over"). Example: Retrieve a list of custom fields, omitting the 50 most recently updated custom fields. Sort the query by the updated_at field and use offset=50: /api/customField/version/3/do/query?offset=50&sort_by=created_at
sort_by string created_at , id , probability , value The field by which the results are sorted. See Sort Order.
sort_order string ascending, descending The sort order. The default value depends on which sort_by parameter you specify. See Sort Order.

Sort Order

Use the sort_by parameter to specify which field Pardot uses to sort the results. Different fields have different default sort orders.

Value Default Sort Order Description
created_at descending Sort the results by the custom fields' created_at timestamps.
id ascending Sort the results by the custom fields' id fields.
name ascending Sort the results by the custom fields' name fields.

Updates information for the specified custom field. Specify the custom field by custom field ID. Fields that are not specified in the request are not changed. To clear a field, use a null value.

Returns an updated version of the custom field.

URI

Replace <ID> with the ID of the custom field.

Parameters

You can use any field in a Custom Field object as a parameter. For a list of fields in a Custom Field object, see Custom Field.

Example

To update a custom field's name to "CONTACTED", use the following POST command:

The XML response for a query request contains information about multiple custom fields. The XML response for a read request contains information about a single custom field.

XML Response for Custom Field Query

Tag Description
<result> Parent tag. Contains the custom fields that match the parameters specified in your query.
<total_results> The number of custom fields selected by the query. Note: The query request returns a maximum of 200 custom fields. If your query matches more than 200 custom fields, you can make several requests to retrieve all matching custom fields.
<customField> The information for a single custom field. See Custom Field.

XML Response for Custom Field Read

Tag Description
<customField> The information for a single custom field. See Custom Field.
Read article

Still Thinking?
Give us a try!

We embrace agility in everything we do.
Our onboarding process is both simple and meaningful.
We can't wait to welcome you on AiDOOS!