Work with API Requests
Learning Objectives
After completing this unit, you’ll be able to:
- Describe how calls to the Pardot API work.
- Explain the basics of an API request.
Work with the Pardot API
For this module, we assume that you have basic Apex and Developer Console knowledge.
The Pardot API lets your application access data within Pardot. An attempt to access data is referred to as a call or request. Through requests, you can perform several common operations on Pardot objects:
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.
Note: The examples in this unit are based on v3 and v4 of Pardot APIs. Version 5 works slightly differently, so if you’re using v5 review the Pardot Developer documentation.
There are many ways to submit requests to the Pardot API; however, we won’t cover them all here. In this unit, we show the requests in plain HTTP to help guide you through the basics.
Regardless of the language and method you use, all requests to the API must:
- Use either HTTP GET or POST. Version 5 also supports PATCH and DELETE requests.
- Pass an access token in an HTTP Authorization header.
- Pass the Pardot Business Unit ID in an HTTP Pardot-Business-Unit-Id header.
- Use the correct URL for your Pardot environment.
Like we covered in Salesforce OAuth for the Pardot API, you must authenticate using a Salesforce OAuth endpoint before issuing Pardot API requests.
If you are following these examples in your Pardot account, we recommend using a sandbox. Some of the tasks in this module can change data in your account.
In this module, we assume you are a Pardot developer with the proper permissions to authenticate and call the API. If you’re not a developer for Pardot, that’s OK. Read along to learn how a developer would take the steps in a production org. Don't try to follow these steps in your Trailhead Playground. Pardot isn’t available in the Trailhead Playground.
Make a GET Request
A GET request lets you use the query and read operations to get data from Pardot. Let’s look at a simple GET request that lists all the custom fields in a business unit.
GET https://pi.pardot.com/api/customField/version/4/do/query?format=json HTTP/1.1 Host: pi.pardot.com Authorization: Bearer <ACCESS TOKEN> Pardot-Business-Unit-Id: <BUSINESS UNIT ID>
Let's break down the request 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 can 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 you’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.
The call returns the business unit's custom fields and their metadata.
{
"@attributes" : {
"version" : 1,
"stat" : "ok"
},
"result" : {
"customField" : [
{
"id" : 14141,
"is_use_values" : false,
"crm_id" : null,
"is_record_multiple_responses" : false,
"field_id" : "Attended_Event",
"type_id" : 1,
"updated_at" : "2020-08-04 05:45:36",
"is_analytics_synced" : false,
"type" : "Text",
"created_at" : "2020-08-04 05:45:36",
"name" : "Attended Event?"
},
],
"total_results" : 1
}
}
Learn more about each object's fields in the Object Field Reference documentation.
Make a POST Request
A POST request lets you use operations that add or change Pardot data. The example below uses a POST request to create a list called Spring Leads.
POST /api/list/version/4/do/create?format=json HTTP/1.1 Host: pi.pardot.com Content-Type: application/x-www-form-urlencoded Authorization: Bearer <ACCESS TOKEN> Pardot-Business-Unit-Id: <BUSINESS UNIT ID> name=Spring Leads Nurture&title=Spring Leads title&description=A list to nurture spring leads
Let’s break down this 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. Version 5 of the API supports only the JSON type.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.
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:
{
"@attributes": {
"stat": "ok",
"version": 1
},
"list": {
"id": 1000,
"name": "Spring Leads Nurture",
"is_public": false,
"is_dynamic": false,
"title": "Spring Leads",
"description": "A list to nurture spring leads",
"is_crm_visible": false,
"created_at": "2021-02-12 08:09:10",
"updated_at": "2021-02-12 08:09:10"
}
}
The response includes the list you created and its metadata.
Let’s take the example a step further and use a POST request to add a prospect to our new list. Since we’re updating an existing instance of an object, our new list, we use the update method.
Remember that completing this task changes data in Pardot, so proceed with caution.
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 the query operation on the Prospect object to get the ID.
- List ID: 1000
- Prospect ID: XXXXX
POST /api/prospect/version/4/do/update/id/XXXXX?format=json HTTP/1.1 Host: pi.pardot.com Content-Type: application/x-www-form-urlencoded Authorization: Bearer <ACCESS TOKEN> Pardot-Business-Unit-Id: <BUSINESS UNIT ID> list_<ID>=1000
That’s all. Now that you understand the basics of making calls to the Pardot API, you can start working on your own integrations. In the next unit, we give an example of making a request using APEX.
