Visitors
Visitor Object
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 Account Engagement tracking code on it, but hasn’t converted to a prospect yet. Learn more about visitors in Salesforce Help.
Include the authentication header with every request. For information on how to authenticate, see Authentication.
Note
Visitor Resources
| 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 Account Engagement ID of the visitor. Replace <prospect ID> with the Account Engagement 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=5678Visitor Read
Request information for a single visitor.
URI
/api/visitor/version/4/do/read/id/<ID>?..Replace <ID> with the Account Engagement ID of the visitor.
Example
Request information for the visitor with ID 1234
/api/visitor/version/4/do/read/id/1234Visitor 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.
To request information about a specific visitor, use Visitor Read.
Tip
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 an Account Engagement ID greater than the specified number. |
id_less_than | integer | Any positive integer | Request visitors that have an Account Engagement 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 Account Engagement 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. |
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_atXML 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. |