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.

The API to access the Visit object follows the conventions described in Version 5 Overview.

Supported Operations

Operation	HTTP Verb	URL Format	Ability Requirements
Read	`GET`	`https://pi.pardot.com/api/v5/objects/visitors/<id>?<params>`	Prospect > Visitors > View ability
Query	`GET`	`https://pi.pardot.com/api/v5/objects/visitors?<params>`	Prospect > Visitors > View ability
Assign to Prospect	`POST`	`https://pi.pardot.com/api/v5/objects/visitors/{id}/do/assignToProspect`	Prospect > Visitors > View ability
Identify Company	`POST`	`https://pi.pardot.com/api/v5/objects/visitors/{id}/do/identifyCompany`	Prospect > Visitors > View ability

Fields

Read-Only Fields

Field	Type	Description
`id`	Integer	ID of the object.
`campaignParameter`	String	Visitor’s campaign parameter utm_campaign from Google Analytics.
`contentParameter`	String	Visitor’s content parameter utm_content from Google Analytics.
`createdAt`	DateTime	Time the object was created.
`doNotSell`	Boolean	Indicates whether the prospect, or a visitor associated with the propect, recorded an activity with the Global Privacy Control Header enabled.
`hostname`	String	Equivalent to visitor.hostname
`ipAddress`	String	Equivalent to visitor.ip_address
`mediumParameter`	String	Visitor’s medium parameter utm_medium from Google Analytics.
`pageViewCount`	Integer	Equivalent to visitor.visitor_page_view_count
`prospectId`	Prospect	Account Engagement ID for the associated prospect.
`campaignId`	Campaign	Campaign ID for the associated visitor.
`sourceParameter`	String	Visitor’s source parameter utm_source from Google Analytics.
`termParameter`	String	Visitor’s term parameter utm_term from Google Analytics.
`updatedAt`	Datetime	Last updated time for the object.
`isIdentified`	Boolean	If True, the visitor’s company is identified.

Assign to Prospect Fields

Field	Required	Type	Description
`prospectId`	True	Integer	The ID of the prospect to be assigned to the Visitor.
`assignDeletedProspect`	False	Boolean	True if the visitor can be assigned to a deleted prospect. If the Prospect isn’t deleted, the value of this property isn’t used. Defaults to false.

Visitor Read

Retrieve a single visitor following the conventions described in the Version 5 Overview.

Example request:

1GET /api/v5/objects/visitors/123456?fields=id,campaignId,hostname,ipAddress,isDeleted,pageViewCount,prospectId
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "id": 123456,
5    "campaignId": 1234,
6    "hostname": "XXX.XX.XXX.123",
7    "ipAddress": "XXX.XX.XXX.123",
8    "isDeleted": false,
9    "pageViewCount": 3,
10    "prospectId": null
11}

Visitor Query

Retrieving a collection of visitors follows the conventions described in Version 5 Overview.

Sortable Fields

When executing a query, the following fields can be specified in the orderBy parameter. See the conventions for query described in the Version 5 Overview.

id
prospectId
createdAt
updatedAt

Example request:

1GET /api/v5/objects/visitors?fields=id,campaignId,hostname,isDeleted,pageViewCount,prospectId&orderBy=id
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "values": [
5        {
6            "id": 12345678,
7            "campaignId": 100,
8            "hostname": "XXX.XX.XXX.123",
9            "ipAddress": "XXX.XX.XXX.123",
10            "isDeleted": false,
11            "pageViewCount": 3,
12            "prospectId": null
13        }
14        {
15            "id": 12345679,
16            "campaignId": 100,
17            "hostname": "XXX.XX.XXX.456",
18            "ipAddress": "XXX.XX.XXX.456",
19            "isDeleted": false,
20            "pageViewCount": 6,
21            "prospectId": null
22        }
23    ]
24}

Filtering Results

When executing a query, the following parameters can be used to filter the returned results. These parameters can be specified in the request along with any shared parameters defined in Version 5 Overview. When specifying more than one parameter, all parameters must match the record in order for it to be returned in the results.

Parameter	Description
`id`	Returns any visitor where ID is equal to the given integer.
`idList`	Returns any visitor where ID is included in the given list of values.
`prospectId`	Returns any visitor where ProspectId is equal to the given integer.
`createdAt`	Returns any visitor where CreatedAt is equal to the given datetime.
`updatedAt`	Returns any visitor where UpdatedAt is equal to the given datetime.
`isIdentified`	When `true`, returns only identified visitors.
`deleted`	Determines whether to return deleted records. The value can be `false` (default), `true`, or `all`.

Example request:

1GET /api/v5/objects/visitors?orderBy=id desc&idGreaterThan=10000000&idLessThan=2000000&fields=id,campaignId
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "values": [
5        {
6            "id": 1234567,
7            "campaignId": 987
8        },
9        {
10            "id": 1999999,
11            "campaignId": 100
12        }
13    ]
14}

Assign to Prospect

Assigns a visitor record to a prospect.

Example request

1POST /api/v5/objects/visitors/5000/do/assignToProspect HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4
5{
6    "prospectId": 1500
7}

Example Responses

Visitor assigned to prospect successfully

Status Code: SUCCESS (200)

1{
2  "id": 5000,
3  "prospectId": 1500
4}

Visitor not found

Status Code: NOT FOUND (404)

1{
2  "code": 109,
3  "message": "The requested record was not found."
4}

Prospect not found

Status Code: BAD REQUEST (400)

1{
2  "code": 3,
3  "message": "Invalid prospect ID"
4}

Prospect is deleted and “assignedDeletedProspect“ is false (or not defined)

Status Code: BAD REQUEST (400)

1{
2  "code": 3,
3  "message": "Invalid prospect ID: Prospect is in recycle bin."
4}

Identify Company

Returns information about the visitor’s company, if identified.

Example request

1POST /api/v5/objects/visitors/18587959/do/identifyCompany HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example Responses

If the visitor has an identified company, the request responds with the status SUCCESS 200, and returns these fields:

Field	Type	Description
`name`	String	Company name
`city`	String	Company city
`state`	String	Company state
`postalCode`	String	Company postal code
`country`	String	Company country

If the visitor doesn’t have an identified company, the request responds with the status NOT FOUND (404).