Forms

Forms Endpoint Reference

Form Fields Endpoint Reference

Marketo forms have a complex set of endpoints allowing full control of form management from remote systems.  The structure of forms can be quite complex, as there are many different types of objects which must be managed as part of a form: Forms, Fields, Fieldsets, Visibility Rules, and Followup Page Rules.

Query

Forms support the standard methods of asset retrieval, by id, by name, and by browsing.  Each form response will contain all of its properties except for its field list.

By Id

Get Form by Id takes a form id as a path parameter and returns a form record.

By Name

Get Form by Name takes a form name as a path parameter and returns a form record.

Browse

Get Forms forms works like other Asset API browse endpoints, and allows optional filtering on statusmaxReturn, and offset.  status can be: approved, approved with draft, or draft.

Field List

Retrieving the field list for a form is done on a per form basis.

When editing fields, or their behavior inside a form, the field list should always be retrieved before attempting edits.  This ensures that you give the proper field id when updating or deleting.

Field Types

UI Type API Name
Checkboxes checkbox
Radio Button radio
Text Area textarea
Picklist picklist
String string
Email email
Date date
Number number
Double double
Phone phone
URL url
Currency currency
Checkbox single_checkbox
Slider range

Dependencies

The Get Form Used By endpoint takes a form id as path parameter and returns the list of assets that depend on the form.  Forms may be used by the following asset types: Landing Pages, Smart Lists, Smart Campaigns, Reports, Email Programs.

Create and Update

When creating a form there are only two required fields: the parent folder of the form, the name of the form.  All of the other parameters are optional with default value values.  When the form is created it will come with three default fields: First Name, Last Name, Email.

Forms are updated with a similar call via their id.  During either creation or update, any of the base styling parameters are accessible and editable, allowing you to modify how the form is displayed to the end user.

The known visitor and thank you page behaviors cannot be modified via the create or update form calls, and need to be accessed via their respective endpoints.

Field Metadata

In order to properly add or edit fields belonging to a form, you need to retrieve the list of valid fields for the target instance. Field interactions are always done on the basis of the field’s id property which is shown for each item in the result.

For Lead fields, this is done by using the Get Available Form Fields endpoint and includes the data type and default metadata for the field when it is added to a form.

For Program Member custom fields, call Get Available Form Program Member Fields  endpoint to retrieve Program Member custom field data types and default metadata.  Note that to leverage these fields in a form, the form must reside underneath a Program (not in Design Studio).  Landing Pages containing forms leveraging these fields fields must also reside underneath a Program (cannot reside in Design Studio, or be cloned into Design Studio).

Edit Field

Each form will contain an editable list of fields, which will be displayed to the end user when loaded.  Each field is added, updated or deleted from the field list one at a time via their respective endpoints.

Adding a field only requires the id of the parent form and the fieldId of the field.  All other fields will either be empty or have default values based on their datatype and field metadata.  Data is passed as POST x-www-form-urlencoded, not as JSON.

Updates may edit all of the same fields as adding a field, and similarly require form id and the fieldId, except that the fieldId is a path parameter and not a query parameter when performing updates.

In the example above we are updating LastName field which is a simple string.  Some form fields are more complex.  For example, the Salutation field is a “select” field type that contains list of items, and a default value.  Note that if you add or update a select type field, unless you set one of the choices to have an isDefault value of true, then the first choice will have no value, and be labeled “Select…”

doc-rest-api-form-field-salutation

To update the list items, the format of the “values” parameter is as follows:

 

To determine how to format a complex form field, look at the response from Add Field to Form.

Rearranging Field

Fields in a form need to be rearranged all as a single unit via the Change Form Field Positions endpoint.  The endpoint requires a parameter called positions, which is a JSON Array of objects with three members:

  • columnNumber
  • rowNumber
  • fieldName (refers to the id of the field)

Fields in a form are arranged in a table-like interface, with up to three columns, and up to ten rows.  Both row and column are indexed from 0, so the first row and first column are both indicated by passing a 0.  All fields must occupy a unique position

If the target field is also a fieldset, then its record within the positions array, should also contain a parameter called fieldList, an array of objects containing the same columnNumber, rowNumber, and fieldName members.  The fieldset itself is treated as a single field for its position in the parent list, while its subfields are positioned according to the given positions in the fieldList parameter.

Rich Text

Rich text fields are added through a separate endpoint from lead fields. The field content is passed as multipart/form-data.  It should be structured as HTML content which does not contain any script, meta tags, or link tags.

Fieldset

Marketo forms feature an optional component called fieldsets.  Fieldsets are groups of fields which are treated as a single field within the top-level field list for purposes of movement and treatment by visibility rules.  For example, if there is a field for Compliance Requirements, and a client selects yes it might reveal a fieldset containing fields for HIPAA and PCI Compliance requirements.

Fields within fieldsets are unique to the form as a whole, so duplicate fields may not be in both the form’s parent field list, and a child fieldset.  Fieldsets are added via the Add Fieldset to Form endpoint and will then appear in the result of Get Fields for Form.  Fields are added to a fieldset by moving them into the fieldset’s fieldList via Update Field Positions.  For these endpoints, data is passed as POST x-www-form-urlencoded, not as JSON.

Visibility Rule

Each field may have a set of visibility rules which determine whether the field can be seen by a visitor depending the values that they have inputted into the form.  The rules make a comparison between the value of a subjectField which is present in the form, and a list of values given in the rule.  Each field may have one type of visibility rule, show, hide, or alwaysShow, and then a list of rules to evaluate.  The rules are evaluated as from top to bottom, and the first rule which evaluates to true is the one which will be applied.

Changing visibility rules is a destructive update.

For the full list of available operators, see the endpoint reference page for Add Form Field Visibility Rules.

Followup

Marketo forms may have dynamic follow-up page behavior where rules to redirect to a given page, or stay on the current page may be applied based on the content of designated fields upon submission.  Rules may be called Thank You Page rules or Followup Page rules interchangeably.  These rules are represented as a JSON array with the members followupType, followupValue, operator, subjectField, values, and default.  default is a Boolean value for which only one record in the array may be true.  When a visitor qualifies for no other rules, the rule designated as default will be used.  followupType may be either lp or url, where lp will indicate a Marketo Landing Page id for followupValue, and url will indicate a URL to another page.  The operator will be used to make a comparison of the value of subject field against the list of values provided.

Submit Button

The submit button styling of the form is managed with the Update Submit Button endpoint.  The buttonPosition, buttonStyle, label, and waitingLabel (the label shown while submission is pending) can be modified.

This is a destructive update.

Approval

Like most other assets, forms follow a draft-approved model, where there can be a draft version and/or an approved version.  Whenever updates are applied to a form, they are always applied to the draft version first, and will only be seen live when the form has been approved.  Approving a form will take the current draft version and replace the approved version, if there is one, with the draft.  If the form needs to be taken down from live, it must first be unapproved, which will delete any current drafts, and demote the approved version to a draft-only state.  Forms should always be unapproved prior to attempting deletion.

Progressive Profiling

When progressive profiling is enabled for a form, a fieldset called “Profiling” will be included in its field list.  In order to add or remove fields from the progressive profiling list, you will need to use the Update Field Positions endpoint.  This endpoint makes destructive updates, so all fields in the form must be included in each request.  The below example adds the field “Phone” to the progressive profiling list.