Form Handler Object

Form handlers are an alternative to Account Engagement forms. You can use a form handler to integrate your third-party or custom forms with Account Engagement to track submission data. Learn more about form handlers in Salesforce Help.

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

Supported Operations

Operation	HTTP Verb	URL Format	Ability Requirements
Create	`POST`	`https://pi.pardot.com/api/v5/objects/form-handlers`	Marketing > Forms > Form Handlers > Create
Read	`GET`	`https://pi.pardot.com/api/v5/objects/form-handlers/<id>?<params>`	Marketing > Forms > Form Handlers > View
Update	`PATCH`	`https://pi.pardot.com/api/v5/objects/form-handlers/<id>`	Marketing > Forms > Form Handlers > Create
Delete	`DELETE`	`https://pi.pardot.com/api/v5/objects/form-handlers/<id>`	Marketing > Forms > Form Handlers > Delete
Query	`GET`	`https://pi.pardot.com/api/v5/objects/form-handlers?<params>`	Marketing > Forms > Form Handlers > View
Add Tag	`POST`	`https://pi.pardot.com/api/v5/objects/form-handlers/<id>/do/addTag`	Marketing > Forms > Form Handlers > Create AND Marketing > Segmentation > Tags > Create
Remove Tag	`POST`	`https://pi.pardot.com/api/v5/objects/form-handlers/<id>/do/removeTag`	Marketing > Forms > Form Handlers > Create AND Marketing > Segmentation > Tags > Create

Fields

Required Editable Fields

These fields are required only for the create operation.

Field	Type	Description
`name`	String	Name of the object for identification in Account Engagement.
`folderId`	Integer	ID of the folder containing this object.
`campaignId`	Integer	The ID of the campaign associated with this object.

Optional Editable Fields

Field	Type	Description
`trackerDomainId`	Integer	The ID of the tracker domain associated with this object.
`isDataForwarded`	Boolean	When `true`, enables data forwarding to the success location.
`successLocation`	String	The URL the user is forwarded to if the submission is successful.
`errorLocation`	String	The URL the user is forwarded to if the submission has an error.
`isAlwaysEmail`	Boolean	When `true`, disables visitor activity throttling and sends autoresponder emails after every submission. Learn more about throttling in Salesforce Help.
`isCookieless`	Boolean	When `true`, the form handler is in Kiosk/Data Entry Mode, and does not cookie browser as a submitted prospect.

Read-Only Fields

Field	Type	Description
`id`	Integer	ID of this object.
`salesforceId`	String	Salesforce Id of the object.
`embedCode`	String	Code to embed this form handler in a webpage.
`createdAt`	DateTime	Creation time of this object.
`createdById`	Integer	ID of the user who created the object.
`isDeleted`	Boolean	True if the object is in the Account Engagement recycle bin.
`updatedById`	Integer	ID of the user who last updated the object.
`createdBy`	User	User object representing the user who created the object. See documentation for User for fields.
`updatedBy`	User	User object representing the user who last updated the object. See documentation for User for fields.
`campaign`	Campaign	Campaign object representing the campaign that was set on Create. See documentation for Campaign for fields.
`folder`	Folder	JSON object representing the folder for this object. See documentation for Folder for fields.
`trackerDomain`	Tracker Domain	Tracker Domain object representing the tracker domain associated with the form handler. See documentation for Tracker Domain for fields.

Form Handler Create

Create a single form handler following the conventions described in the Version 5 Overview.

When form handlers are created, an email field is included automatically.

Tip

Example request:

1POST /api/v5/objects/form-handlers?fields=id,name,campaignId,folderId HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5Content-Length: 142
6
7{
8  "name": "My New Form Handler",
9  "campaignId": 10000,
10  "isDataForwarded": false,
11  "trackerDomainId": 555555,
12  "folderId": 7777
13}

Example response:

1{
2  "id": 30000,
3  "campaignId": 10000,
4  "folderId": 7777,
5  "name": "My Newe Form Handler"
6}

Form Handler Read

Retrieve a single form handler object following the conventions described in the Version 5 Overview.

Example request:

1GET /api/v5/objects/form-handlers/<ID>?Fields=id,name,salesforceId,campaignId,embedCode,createdAt,createdById,updatedById,trackerDomainId,isDataForwarded,successLocation,errorLocation,isAlwaysEmail,isCookieless,isNotifyUsers,isNotifyAssigned,isDeleted,folderId,createdBy.username,updatedBy.username,trackerDomain.domain,campaign.id,campaign.name,campaign.folderId,campaign.folder.name,folder.id,folder.name HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example Response

1{
2  "id": 101,
3  "campaign": {
4    "id": 300,
5    "folder": {
6      "name": "Website"
7    },
8    "folderId": 2000,
9    "name": "Website Tracking"
10  },
11  "campaignId": 1000,
12  "createdAt": "2021-11-03T12:07:52-07:00",
13  "createdBy": {
14    "username": "user@example.com"
15  },
16  "createdById": 500,
17  "embedCode": null,
18  "errorLocation": "Referring URL",
19  "folder": {
20    "id": 2000,
21    "name": "Form Handler Folder"
22  },
23  "folderId": 2000,
24  "isAlwaysEmail": false,
25  "isCookieless": false,
26  "isDataForwarded": false,
27  "isDeleted": false,
28  "isNotifyAssigned": false,
29  "isNotifyUsers": false,
30  "name": "My Newest Form Handler",
31  "salesforceId": null,
32  "successLocation": "Referring URL",
33  "trackerDomain": {
34    "domain": "www3.example.com"
35  },
36  "trackerDomainId": 50000,
37  "updatedBy": {
38    "username": "user@example.com"
39  },
40  "updatedById": 90000
41}

Form Handler Update

Updating a form handler follows the conventions described in the Version 5 Overview.

Form Handler Delete

Deleting a form handler follows the conventions described in the Version 5 Overview.

Form Handler Query

Retrieving a collection of form handlers 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
createdAt

Example Request

1GET /api/v5/objects/form-handlers?Fields=id,name,campaignId,createdAt,trackerDomainId,isDeleted&orderBy=id HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example Response

1"values": [
2        {
3            "id": 001,
4            "campaignId": 3000,
5            "createdAt": "2020-11-02T21:00:00-08:00",
6            "isDeleted": false,
7            "name": "Free Trial Signup",
8            "trackerDomainId": null,
9        },
10        {
11            "id": 002,
12            "campaignId": 2000,
13            "createdAt": "2021-10-28T09:09:05-07:00",
14            "isDeleted": false,
15            "name": "Grey Guideworks Form Handler",
16            "trackerDomainId": null,
17        },
18]

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 form handler where ID is equal to the given integer value.
`idList`	Returns any form handler where ID is included in the given list of values.
`idGreaterThan`	Returns any form handler where ID is greater than the specified value, non-inclusive.
`idGreaterThanOrEqualTo`	Returns any form handler where ID is greater than or equal to the specified value.
`idLessThan`	Returns any form handler where ID is less than the specified value, non-inclusive.
`idLessThanOrEqualTo`	Returns any form handler where ID is less than or equal to the specified value.
`name`	Returns any form handler where Name is equal to the given string value.
`createdAt`	Returns any form handler where CreatedAt is equal to the given datetime value.
`createdAtAfter`	Returns any form handler where CreatedAt is after the given datetime value, non-inclusive.
`createdAtAfterOrEqualTo`	Returns any form handler where CreatedAt is after or equal to the given datetime value.
`createdAtBefore`	Returns any form handler where CreatedAt is before the given datetime value, non-inclusive.
`createdAtBeforeOrEqualTo`	Returns any form handler where CreatedAt is before or equal to the given datetime value.
`deleted`	Determines whether to return deleted records. The value can be `false` (default), `true`, or `all`.

Example Request

1GET /api/v5/objects/form-handlers?Fields=id,name,campaignId,createdAt,trackerDomainId,isDeleted&createdAtAfter=2021-10-31T00:00:00-07:00 HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example Response

1{
2  "nextPageToken": null,
3  "nextPageUrl": null,
4  "values": [
5    {
6      "id": 1000,
7      "campaignId": 30000,
8      "createdAt": "2021-11-03T12:06:29-07:00",
9      "isDeleted": false,
10      "name": "My New Form Handler"
11    },
12    {
13      "id": 1002,
14      "campaignId": 30000,
15      "createdAt": "2021-11-03T12:07:52-07:00",
16      "isDeleted": false,
17      "name": "My Newest Form Handler"
18    }
19  ]
20}

Add Tag

Adds a Tag to the Form Handler object, which creates a TaggedObject.

Example Request

1POST https://pi.pardot.com/api/v5/objects/form-handlers/1000/do/addTag
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "tagId": 100
8}

Example Response

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "id": 610,
5    "createdAt": "2024-09-23T18:26:49-04:00",
6    "createdById": 250,
7    "objectId": 1000,
8    "objectType": "form-handler",
9    "tagId": 100
10}

Remove Tag

Remove a tag from a Form Handler object. When you remove a tag, the associated TaggedObject record is deleted.

Example Request

1POST https://pi.pardot.com/api/v5/objects/form-handlers/1000/do/removeTag
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "tagId": 100
8}

Example Response

Returns code 204 no content.