Visitor Resources
Use visitor resources to learn about the people who interact with your website, including their IP address and Google Analytics information. A visitor is someone who has visited a page with your Pardot tracking code on it, but hasn’t converted to a prospect yet. Learn more about visitors in Salesforce Help.
Note: Include the authentication header with every request. For information on how to authenticate, see Authentication.
| Resource Name | Operation | Description |
|---|---|---|
| Visitor Assign | POST |
Assign a visitor record to a prospect. |
| Visitor Query | GET |
Request information for the visitors that match the specified criteria. |
| Visitor Read | GET |
Request information for a single visitor. |
Visitor Assign
Associate a visitor to a prospect. Most prospects are related to their visitor activity when they convert, but you can manually associate a visitor with a prospect. This feature comes in handy when you’re in contact with a potential prospect whose company is in your visitor's report.
URI
/api/visitor/version/4/do/assign/id/<ID>?prospect_id=<prospect ID>
Replace <ID> with the Pardot ID of the visitor. Replace <prospect ID> with the Pardot ID of the prospect.
Parameters
Include <prospect ID> to identify the prospect that the visitor is assigned to.
Example
Assign the visitor 1234 to the prospect 5678
POST /api/visitor/version/4/do/assign/id/1234?format=json HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>
prospect_id=5678
Visitor Read
Request information for a single visitor.
URI
/api/visitor/version/4/do/read/id/<ID>?..
Replace <ID> with the Pardot ID of the visitor.
Example
Request information for the visitor with ID 1234
/api/visitor/version/4/do/read/id/1234
Visitor Query
Request information about the visitors that match the specified criteria. You can specify which visitors and which fields to request. A maximum of 200 visitors are returned, unless you specify the output as mobile. If you specify the output as mobile, then all visitors are returned.
Note: To request information about a specific visitor, use Visitor Read.
URI
/api/visitor/version/4/do/query?...
Parameters to Select Visitors
Use these parameters to specify which visitors 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:mm).
- For a full listing of visitor 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 visitors created after the specified date and time. Example: To request forms created in 2020, use /api/visitors/version/4/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 visitors created before the specified date and time. Doesn’t include visitors created at the specified time. <custom_time> Example: to request visitors created before today (but not created today), use /api/visitor/version/4/do/query?created_before=today. |
id_greater_than |
integer |
Any positive integer | Request visitors that have a Pardot ID greater than the specified number. |
id_less_than |
integer |
Any positive integer | Request visitors that have a Pardot ID less than the specified number. |
only_identified |
boolean |
true, false |
Request visitors that have an identified company. Default value is true. |
prospect_ids |
array |
any set of valid prospect IDs, false |
Request visitors with the specified prospect IDs. Separate prospect IDs with a comma. |
updated_after |
string |
today, yesterday, last_7_days, this_month, last_month, <custom_time> |
Request visitors 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 visitors that were last updated before the specified date and time. |
Parameters to Specify Which Results Are Returned
Use these parameters to specify which visitor fields are returned, and how the visitors are sorted.
| Parameter | Type | Possible Values | Description |
|---|---|---|---|
fields |
array |
Any valid field names. | Lists the fields to return. The visitor ID is always returned. Separate field names with a comma. |
limit |
integer |
Any integer from 1 through 200. | The number of visitors to return. Default value is 200. |
offset |
integer |
Any positive integer | The number of visitors to omit from the response (the number to "skip over"). Example: Retrieve a list of visitors, omitting the 50 most recently updated visitors. Sort the query by the updated_at field and use offset=50: api/visitor/version/4/do/query?sort_by=updated_at&offset=50 |
output |
string |
simple, mobile, full |
The format to use for the query results. mobile returns fewer fields. full returns all fields including prospect information. simple returns all fields except for prospect information - only prospect ID is returned. |
sort_by |
string |
created_at, id, updated_at |
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 visitors' created_at timestamps. |
id |
ascending | Sort the results by the visitors' id fields. |
updated_at |
descending | Sort the results by the visitors' updated_at timestamps. |
Example
Request a list of visitors, sorted in ascending order by the records' creation time.
/api/visitor/version/4/do/query?sort_order=ascending&sort_by=created_at
XML Response
The XML response for a query request contains information about multiple visitors. The XML response for a read request contains information about a single visitor.
XML Response for Visitor Query
<rsp stat="ok" version="1.0">
<result>
<total_results>...</total_results>
<visitor>...</visitor>
<visitor>...</visitor>
<visitor>...</visitor>
</result>
</rsp>
| Tag | Description |
|---|---|
<result> |
Parent tag. Contains the visitors that match the parameters specified in your query. |
<total_results> |
The number of visitors selected by the query. Note: The query request returns a maximum of 200 visitors. If your query matches more than 200 visitors, you can make several requests to retrieve all matching records. |
<visitor> |
The information for a single visitor. For information about visitor fields, see Visitor. |