Form Handler Field Object

Form handlers are an alternative to Account Engagement forms. Form handlers contain form handler fields to gather information from prospects. 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 Field 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-handler-fields`	Forms > Form Handlers > Create ability
Read	`GET`	`https://pi.pardot.com/api/v5/objects/form-handler-fields/<id>?<params>`	Forms > Form Handlers > View ability
Update	`PATCH`	`https://pi.pardot.com/api/v5/objects/form-handler-fields/<id>`	Forms > Form Handlers > Create ability
Delete	`DELETE`	`https://pi.pardot.com/api/v5/objects/form-handler-fields/<id>`	Forms > Form Handlers > Delete ability
Query	`GET`	`https://pi.pardot.com/api/v5/objects/form-handler-fields?<params>`	Forms > Form Handlers > View ability

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.
`formHandlerId`	Integer	The ID of the form handler this field belongs to.
`dataFormat`	Enum	The field’s data format. Values are “text”, “number”,“email”, “email not from isps and free email providers”, and “email with valid mail server”.
`prospectApiFieldId`	String	The name of the Account Engagement prospect field that the form handler field is mapped to. On standard fields the value is the name of the field. For example, “firstName”. If mapping to a custom field, the value is the field name followed by __c. For example, the custom field “foodChoice” becomes “foodChoice__c”.

Optional Editable Fields

Field	Type	Description
`isMaintainInitialValue`	Boolean	When `true`, the field maintains the initial value upon subsequent form submissions.
`errorMessage`	String	Error message for the field. If `isRequired` is `true`, and `errorMessage` is not provided, it assumes a default value: `This field is required.`
`isRequired`	Boolean	Defaults to `false`. When `true`, the field will be required for a valid submission of the form handler.

Read-Only Fields

Field	Type	Description
`id`	Integer	ID of this object.
`createdAt`	DateTime	Creation time of this object.
`createdById`	Integer	ID of the user who created the object.
`createdBy`	User	User object representing the user who created the object. See documentation for User for fields.
`formHandler`	Form Handler	Form Handler object that the field belongs to. See documentation for Form Handler for fields.

Form Handler Field Create

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

Example request:

1POST /api/v5/objects/form-handler-fields HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4
5{
6    "dataFormat": "text",
7    "errorMessage": "This field is required.",
8    "formHandlerId": 1000,
9    "isMaintainInitialValue": false,
10    "isRequired": true,
11    "name": "Salutation",
12    "prospectApiFieldId": "salutation"
13}

Example response:

201 Created

1{
2  "id": 9423
3}

Form Handler Field Read

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

Example request:

1ET /api/v5/objects/form-handler-fields/3000?fields=id,name,formHandlerId,isMaintainInitialValue,isRequired,createdAt,createdById,dataFormat,errorMessage,prospectApiFieldId HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example Response

1{
2  "id": 3000,
3  "createdAt": "2021-05-27T06:58:58-07:00",
4  "createdById": null,
5  "dataFormat": "email",
6  "errorMessage": "This field is required.",
7  "formHandlerId": 1000,
8  "isMaintainInitialValue": false,
9  "isRequired": true,
10  "name": "email",
11  "prospectApiFieldId": "email"
12}

Form Handler Field Update

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

Form Handler Field Delete

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

Form Handler Field Query

Retrieving a collection of form handler fields 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
formHandlerId

Example Request

1GET /api/v5/objects/form-handler-fields?fields=id,name,formHandlerId&orderBy=ID HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example Response

1"values": [
2        {
3            "id": 2913,
4            "formHandlerId": 1000,
5            "name": "email"
6        },
7        {
8            "id": 2915,
9            "formHandlerId": 1000,
10            "name": "first_name"
11        },
12        {
13            "id": 2917,
14            "formHandlerId": 1000,
15            "name": "last_name"
16        }
17]

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 field where ID is equal to the given integer value.
`idList`	Returns any form handler field where ID is included in the given list of values.
`idGreaterThan`	Returns any form handler field where ID is greater than the specified value, non-inclusive.
`idGreaterThanOrEqualTo`	Returns any form handler field where ID is greater than or equal to the specified value.
`idLessThan`	Returns any form handler field where ID is less than the specified value, non-inclusive.
`idLessThanOrEqualTo`	Returns any form handler field where ID is less than or equal to the specified value.
`formHandlerId`	Returns any form handler field where formHandlerId is equal to the given integer.
`createdAt`	Returns any form handler field where CreatedAt is equal to the given datetime value.
`createdAtAfter`	Returns any form handler field where CreatedAt is after the given datetime value, non-inclusive.
`createdAtAfterOrEqualTo`	Returns any form handler field where CreatedAt is after or equal to the given datetime value.
`createdAtBefore`	Returns any form handler field where CreatedAt is before the given datetime value, non-inclusive.
`createdAtBeforeOrEqualTo`	Returns any form handler field where CreatedAt is before or equal to the given datetime value.

Example Request

1GET /api/v5/objects/form-handler-fields?orderBy=ID&fields=id,name,formHandlerId&formHandlerId=1000 HTTP/1.1
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example Response

1"values": [
2        {
3            "id": 2913,
4            "formHandlerId": 1000,
5            "name": "email"
6        },
7        {
8            "id": 2915,
9            "formHandlerId": 1000,
10            "name": "first_name"
11        },
12        {
13            "id": 2917,
14            "formHandlerId": 1000,
15            "name": "last_name"
16        },
17        {
18            "id": 9421,
19            "formHandlerId": 1000,
20            "name": "Salutation"
21        }
22    ]