表单

Forms端点引用

表单字段端点引用

使用表单端点管理远程系统中的表单。 表单可以包含多种对象类型:

  • 表单
  • 字段
  • 字段集
  • 可见性规则
  • 跟进页面规则

查询

Forms支持标准资源检索方法:按id按名称浏览。 表单响应包含除字段列表之外的每个表单属性。

按ID

将表单id作为路径参数传递给按ID获取表单。 端点返回匹配的表单记录。

GET /rest/asset/v1/form/{id}.json
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "948f#154e3bad8e3",
    "result": [
        {
            "id": 736,
            "name": "newForm",
            "description": "test",
            "createdAt": "2016-05-24T17:05:54Z+0000",
            "updatedAt": "2016-05-24T17:05:54Z+0000",
            "url": "https://app-devlocal1.marketo.com/#FO736B2",
            "status": "draft",
            "theme": "simple",
            "language": "French",
            "locale": "fr_FR",
            "progressiveProfiling": false,
            "labelPosition": "left",
            "fontFamily": "Helvetica",
            "fontSize": "13px",
            "folder": {
                "type": "Folder",
                "value": 293,
                "folderName": "yyLNLHzgOM"
            },
            "knownVisitor": {
                "type": "form",
                "template": null
            },
            "thankYouList": [
                {
                    "followupType": "none",
                    "followupValue": null,
                    "default": true
                }
            ],
            "buttonLocation": 120,
            "buttonLabel": "Envoyer",
            "waitingLabel": "Veuillez patienter"
        }
    ]
}

按名称

将表单name传递给按名称获取表单。 端点返回匹配的表单记录。

GET /rest/asset/v1/form/byName.json?name=newForm
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "948f#154e3bad8e3",
    "result": [
        {
            "id": 736,
            "name": "newForm",
            "description": "test",
            "createdAt": "2016-05-24T17:05:54Z+0000",
            "updatedAt": "2016-05-24T17:05:54Z+0000",
            "url": "https://app-devlocal1.marketo.com/#FO736B2",
            "status": "draft",
            "theme": "simple",
            "language": "French",
            "locale": "fr_FR",
            "progressiveProfiling": false,
            "labelPosition": "left",
            "fontFamily": "Helvetica",
            "fontSize": "13px",
            "folder": {
                "type": "Folder",
                "value": 293,
                "folderName": "yyLNLHzgOM"
            },
            "knownVisitor": {
                "type": "form",
                "template": null
            },
            "thankYouList": [
                {
                    "followupType": "none",
                    "followupValue": null,
                    "default": true
                }
            ],
            "buttonLocation": 120,
            "buttonLabel": "Envoyer",
            "waitingLabel": "Veuillez patienter"
        }
    ]
}

浏览

获取Forms遵循标准Asset API浏览模式。 它支持以下可选过滤器:

  • status:按approvedapproved with draftdraft筛选条件。
  • maxReturn:限制返回的记录数。
  • offset:页面浏览结果集。
GET /rest/asset/v1/forms.json
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "645d#154e3d499ac",
    "result": [
        {
            "id": 227,
            "name": "aKAUVDfbsX",
            "description": "",
            "createdAt": "2016-05-18T20:36:20Z+0000",
            "updatedAt": "2016-05-18T20:36:20Z+0000",
            "url": "https://app-devlocal1.marketo.com/#FO227B2",
            "status": "draft",
            "theme": "simple",
            "language": "English",
            "locale": "en_US",
            "progressiveProfiling": false,
            "labelPosition": "left",
            "fontFamily": "Helvetica",
            "fontSize": "13px",
            "folder": {
                "type": "Folder",
                "value": 293,
                "folderName": "yyLNLHzgOM"
            },
            "knownVisitor": {
                "type": "form",
                "template": null
            },
            "thankYouList": [
                {
                    "followupType": "none",
                    "followupValue": null,
                    "default": true
                }
            ],
            "buttonLocation": 120,
            "buttonLabel": "Submit",
            "waitingLabel": "Please Wait"
        },
        {
            "id": 695,
            "name": "AoMXgfFbma",
            "description": "",
            "createdAt": "2016-05-19T18:50:40Z+0000",
            "updatedAt": "2016-05-19T18:50:40Z+0000",
            "url": "https://app-devlocal1.marketo.com/#FO695B2",
            "status": "draft",
            "theme": "simple",
            "language": "English",
            "locale": "en_US",
            "progressiveProfiling": true,
            "labelPosition": "left",
            "fontFamily": "Helvetica",
            "fontSize": "13px",
            "folder": {
                "type": "Folder",
                "value": 565,
                "folderName": "WfUvYmlcyT"
            },
            "knownVisitor": {
                "type": "form",
                "template": null
            },
            "thankYouList": [
                {
                    "followupType": "none",
                    "followupValue": null,
                    "default": true
                }
            ],
            "buttonLocation": 120,
            "buttonLabel": "Submit",
            "waitingLabel": "Please Wait"
        }
    ]
}

字段列表

通过传递表单ID分别检索每个表单的字段列表。

GET /rest/asset/v1/form/{id}/fields.json
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "2165#154eee00d01",
    "result": [
        {
            "id": "FirstName",
            "label": "First Name:",
            "dataType": "text",
            "validationMessage": "This field is required.",
            "rowNumber": 0,
            "columnNumber": 0,
            "maxLength": 255,
            "required": false,
            "formPrefill": true,
            "visibilityRules": {
                "ruleType": "alwaysShow"
            }
        },
        {
            "id": "LastName",
            "label": "Last Name:",
            "dataType": "text",
            "validationMessage": "This field is required.",
            "rowNumber": 1,
            "columnNumber": 0,
            "maxLength": 255,
            "required": false,
            "formPrefill": true,
            "visibilityRules": {
                "ruleType": "alwaysShow"
            }
        },
        {
            "id": "Email",
            "label": "Email Address:",
            "dataType": "email",
            "validationMessage": "Must be valid email. <span class='mktoErrorDetail'>example@yourdomain.com</span>",
            "rowNumber": 2,
            "columnNumber": 0,
            "required": false,
            "formPrefill": true,
            "visibilityRules": {
                "ruleType": "alwaysShow"
            }
        },
        {
            "id": "Profiling",
            "dataType": "profiling",
            "rowNumber": 3,
            "columnNumber": 0
        }
    ]
}

在更新或删除字段或更改其行为之前,请检索表单的字段列表。 在后续请求中使用返回的字段ID。

字段类型

UI类型
API名称
复选框
复选框
单选按钮
无线电
文本区域
文本区域
选取列表
选取列表
字符串
字符串
电子邮件
电子邮件
日期
日期
数值
数字
双精度
double
电话
电话
URL
url
货币
货币
复选框
single_checkbox
滑块
范围

依赖关系

将表单id作为路径参数传递给获取使用的表单。 端点会返回依赖于表单的资源。

以下资源类型可以使用表单:

  • 登陆页面
  • 智能列表
  • 智能营销活动
  • 报告
  • 电子邮件项目
GET /rest/asset/v1/form/{id}/usedBy.json
{
    "success": true,
    "errors": [],
    "requestId": "fdf4#17285b25038",
    "warnings": [],
    "result": [
        {
            "id": 1038,
            "name": "LP Redirect Rules Program.LP Test 01",
            "type": "Landing Page",
            "status": "approved",
            "updatedAt": "2020-02-23T01:31:21Z+0000"
        }
    ]
}

创建和更新

创建表单,请提供两个必填字段:

  • 表单的父文件夹。
  • 表单名称。

所有其他参数均为可选参数,并具有默认值。 新表单包含三个默认字段:名字、姓氏和电子邮件。

POST /rest/asset/v1/forms.json
Content-Type: application/x-www-form-urlencoded
name=newForm&description=test&folder={"type": "Folder","id": 293}&language=French
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "948f#154e3bad8e3",
    "result": [
        {
            "id": 736,
            "name": "newForm",
            "description": "test",
            "createdAt": "2016-05-24T17:05:54Z+0000",
            "updatedAt": "2016-05-24T17:05:54Z+0000",
            "url": "https://app-devlocal1.marketo.com/#FO736B2",
            "status": "draft",
            "theme": "simple",
            "language": "French",
            "locale": "fr_FR",
            "progressiveProfiling": false,
            "labelPosition": "left",
            "fontFamily": "Helvetica",
            "fontSize": "13px",
            "folder": {
                "type": "Folder",
                "value": 293,
                "folderName": "yyLNLHzgOM"
            },
            "knownVisitor": {
                "type": "form",
                "template": null
            },
            "thankYouList": [
                {
                    "followupType": "none",
                    "followupValue": null,
                    "default": true
                }
            ],
            "buttonLocation": 120,
            "buttonLabel": "Envoyer",
            "waitingLabel": "Veuillez patienter"
        }
    ]
}

更新表单,请传递其ID。 在创建或更新过程中,您可以设置基本样式参数,用于控制向用户显示表单的方式。

POST /rest/asset/v1/form/736.json
Content-Type: application/x-www-form-urlencoded
name=updated name&description=This is a test for updateapi&language=English&progressiveProfiling=true&locale=en_US
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "6307#154e3cf6efe",
    "result": [
        {
            "id": 736,
            "name": "updated name",
            "description": "This is a test for update api",
            "createdAt": "2016-05-24T17:05:54Z+0000",
            "updatedAt": "2016-05-24T17:28:23Z+0000",
            "status": "draft",
            "theme": "simple",
            "language": "English",
            "locale": "en_US",
            "progressiveProfiling": true,
            "labelPosition": "left",
            "fontFamily": "Helvetica",
            "fontSize": "13px",
            "folder": {
                "type": "Folder",
                "value": 293,
                "folderName": "yyLNLHzgOM"
            },
            "knownVisitor": {
                "type": "form",
                "template": null
            },
            "thankYouList": [
                {
                    "followupType": "none",
                    "followupValue": null,
                    "default": true
                }
            ],
            "buttonLocation": 120,
            "buttonLabel": "Submit",
            "waitingLabel": "Please Wait"
        }
    ]
}

创建和更新表单端点不会修改已知访客或感谢页面行为。 使用相应的端点管理这些行为。

字段元数据

在添加或编辑表单字段之前,请检索目标实例的有效字段。 字段操作使用针对每个字段返回的id属性。

对于潜在客户字段,请使用获取可用的表单字段终结点。 响应包括每个字段的数据类型以及在将字段添加到表单时应用的默认元数据。

GET /rest/asset/v1/form/fields.json
{
    "success": true,
    "errors": [],
    "requestId": "176ca#167a9808f4c",
    "warnings": [],
    "result": [
        {
            "id": "AnnualRevenue",
            "isRequired": false,
            "dataType": "currency"
        },
        {
            "id": "City",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "Company",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "Country",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "Description",
            "isRequired": false,
            "dataType": "textarea",
            "maxLength": 32000,
            "visibleRows": 2
        },
        {
            "id": "Email",
            "isRequired": false,
            "dataType": "email"
        },
        {
            "id": "Fax",
            "isRequired": false,
            "dataType": "phone"
        },
        {
            "id": "FirstName",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "Industry",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "LastName",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "LeadSource",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "MobilePhone",
            "isRequired": false,
            "dataType": "phone"
        },
        {
            "id": "NumberOfEmployees",
            "isRequired": false,
            "dataType": "int"
        },
        {
            "id": "Phone",
            "isRequired": false,
            "dataType": "phone"
        },
        {
            "id": "PostalCode",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "Rating",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "Salutation",
            "isRequired": false,
            "dataType": "picklist",
            "picklistValues": "Mr.,Ms.,Mrs.,Dr.,Prof."
        },
        {
            "id": "State",
            "isRequired": false,
            "dataType": "picklist",
            "picklistValues": "AK::AK,AL::AL,AR::AR,AZ::AZ,CA::CA,CO::CO,CT::CT,DE::DE,FL::FL,GA::GA,HI::HI,IA::IA,ID::ID,IL::IL,IN::IN,KS::KS,KY::KY,LA::LA,MA::MA,MD::MD,ME::ME,MI::MI,MN::MN,MO::MO,MS::MS,MT::MT,NC::NC,ND::ND,NE::NE,NH::NH,NJ::NJ,NM::NM,NV::NV,NY::NY,OH::OH,OK::OK,OR::OR,PA::PA,RI::RI,SC::SC,SD::SD,TN::TN,TX::TX,UT::UT,VA::VA,VT::VT,WA::WA,WI::WI,WV::WV,WY::WY"
        },
        {
            "id": "Street",
            "isRequired": false,
            "dataType": "textarea",
            "maxLength": 2000,
            "visibleRows": 2
        },
        {
            "id": "Title",
            "isRequired": false,
            "dataType": "picklist"
        }
    ]
}

对于程序成员自定义字段,请调用获取可用的表单程序成员字段端点。 响应包括程序成员自定义字段数据类型和默认元数据。

要使用这些字段,表单必须位于程序下,而不是在Design Studio中。 包含具有这些字段的表单的登陆页面也必须位于项目下。 不能在Design Studio中或将其克隆到其中。

GET /rest/asset/v1/form/programMemberFields.json
{
    "success": true,
    "errors": [],
    "requestId": "109c6#16fa0b9c51a",
    "warnings": [],
    "result": [
        {
            "id": "pMCFCustomField01",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "pMCFCustomField02",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        },
        {
            "id": "myPMCF",
            "isRequired": false,
            "dataType": "string",
            "maxLength": 255
        }
    ]
}

编辑字段

每个表单都有一个可编辑的字段列表,在加载表单时向用户显示。 使用相应的端点一次添加、更新或删除一个字段。

添加字段,请提供父表单ID和字段fieldId。 所有其他属性为空,或使用基于字段数据类型和元数据的默认值。

将数据作为POST与application/x-www-form-urlencoded一起发送,而不是作为JSON发送。

POST /rest/asset/v1/form/{id}/fields.json
Content-Type: application/x-www-form-urlencoded
fieldId=NumberOfEmployees&maxLength=125&defaultValue=this is default&required=true&fieldWidth=100&validationMessage=hey, you there?&label=employee count&hintText=Hint me&minValue=10
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "1826e#154f41b214c",
    "result": [
        {
            "id": "NumberOfEmployees",
            "label": "employee count",
            "fieldWidth": 100,
            "dataType": "number",
            "defaultValue": "this is default",
            "validationMessage": "hey, you there?",
            "rowNumber": 5,
            "columnNumber": 0,
            "required": true,
            "formPrefill": true,
            "fieldMetaData": {
                "minValue": 10,
                "maxValue": null
            },
            "visibilityRules": {
                "ruleType": "alwaysShow"
            },
            "hintText": "Hint me"
        }
    ]
}

更新可以编辑添加字段时使用的相同属性。 它还需要表单ID和fieldId,但更新端点将fieldId作为路径参数而不是查询参数传递。

POST /rest/asset/v1/form/{id}/field/LastName.json
Content-Type: application/x-www-form-urlencoded
label=enter the last name here
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "5634#15508303abb",
    "result": [
        {
            "id": "LastName",
            "label": "enter the last name here",
            "dataType": "text",
            "validationMessage": "This field is required.",
            "rowNumber": 0,
            "columnNumber": 0,
            "maxLength": 255,
            "required": false,
            "formPrefill": true,
            "visibilityRules": {
                "ruleType": "alwaysShow"
            }
        }
    ]
}

上一个示例更新了简单字符串字段LastName。 其他表单字段的元数据更加复杂。 例如,Salutation是一个包含项列表和默认值的select字段。

添加或更新选择字段时,将一个选择的isDefault值设置为true。 否则,第一个选择没有值且标记为Select...

致敬

要更新列表项,请设置values参数的格式,如以下示例所示:

POST /rest/asset/v1/form/{id}/field/Salutation.json
Content-Type: application/x-www-form-urlencoded
values=[{"label":"Select...","value":"","isDefault":true,"selected":true}, {"label":"MR","value":"MR"}, {"label":"MS","value":"MS"}, {"label":"MRS","value":"MRS"}, {"label":"DR","value":"DR"}, {"label":"PROF","value":"PROF"}]
{
  "success": true,
  "warnings": [ ],
  "errors": [ ],
  "requestId": "71fd#1588d9d1b0c",
  "result": [
    {
      "id": "Salutation",
      "label": "Salutation:",
      "dataType": "select",
      "validationMessage": "This field is required.",
      "rowNumber": 3,
      "columnNumber": 0,
      "required": false,
      "formPrefill": true,
      "fieldMetaData": {
        "multiSelect": false,
        "values": [
          {
            "label": "Select...",
            "value": "",
            "isDefault": true,
            "selected": true
          },
          {
            "label": "MR",
            "value": "MR"
          },
          {
            "label": "MS",
            "value": "MS"
          },
          {
            "label": "MRS",
            "value": "MRS"
          },
          {
            "label": "DR",
            "value": "DR"
          },
          {
            "label": "PROF",
            "value": "PROF"
          }
        ],
        "visibleLines": 1
      },
      "visibilityRules": {
        "ruleType": "alwaysShow"
      }
    }
  ]
}

使用“将字段添加到表单”响应来确定如何设置复杂表单字段的格式。

重新排列字段

使用更改表单字段位置端点将所有表单字段重新排列为一个单元。 终结点需要positions,即具有三个成员的JSON对象数组:

  • columnNumber
  • rowNumber
  • fieldName,引用字段ID

表单字段使用类似表的排列,最多三列十行。 行索引和列索引从0开始,因此第一行和列都使用0。 每个字段都必须占据一个独特的位置。

如果目标字段是字段集,则其在positions中的记录还必须包含fieldList。 此参数是一个对象数组,具有相同的columnNumberrowNumberfieldName成员。

父列表将字段集视为一个字段。 fieldList中的位置决定其子字段的排列。

POST /rest/asset/v1/form/{id}/reArrange.json
Content-Type: application/x-www-form-urlencoded
positions=[{"columnNumber":0,"rowNumber":0,"fieldName":"FirstName"},{"columnNumber":0,"rowNumber":1,"fieldName":"LastName"}, {"columnNumber":0,"rowNumber":2, "fieldName":"Email"}]
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "bb18#15508ef9c04",
    "result": [
        {
            "id": 764
        }
    ]
}

富文本

使用单独的终结点添加RTF字段。 在multipart/form-data请求中将内容作为HTML传递。 HTML不得包含脚本、元标记或链接标记。

POST /rest/asset/v1/form/{id}/richText.json
Content-Type: multipart/form-data; boundary=---------------------------9051914041544843365972754266
-----------------------------9051914041544843365972754266
Content-Disposition: form-data; name="text"
Content-Type: text/html
<div>Fancy Rich Text Component</div>
-----------------------------9051914041544843365972754266--
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "82c8#154f423bf5c",
    "result": [
        {
            "id": "SHRtbFRleHRfMjAxNi0wNS0yN1QxNDozNDoyNC4xMTVa",
            "labelWidth": 260,
            "dataType": "htmltext",
            "rowNumber": 8,
            "columnNumber": 0,
            "visibilityRules": {
                "ruleType": "alwaysShow"
            },
            "text": "<div>Fancy Rich Text Component</div>"
        }
    ]
}

字段集

字段集是一组可选字段。 顶级字段列表将字段集视为一个用于定位和可见性规则的字段。 例如,为“Compliance Requirements(合规性要求)”字段选择yes可以显示包含HIPAA和PCI Compliance字段的字段集。

表单中的字段必须唯一。 同一字段不能同时出现在表单的父字段列表和子字段集中。

添加具有将字段集添加到Form终结点的字段集。 然后,该字段集将显示在表单🔗响应的获取字段中。 若要向字段集添加字段,请使用更新字段位置以将其移动到其fieldList中。

对于这些端点,将数据作为application/x-www-form-urlencoded的POST发送,而不是作为JSON发送。

可见性规则

可见性规则确定访客能否根据在表单中输入的值查看字段。 每个规则将表单中subjectField的值与规则中的值列表进行比较。

字段可以具有一个可见性规则类型: showhidealwaysShow。 API从上到下评估字段的规则,并将评估为true的第一个规则应用于此值。

更改可见性规则是一种破坏性更新。

POST /rest/asset/v1/form/{id}/field/Email/visibility.json
Content-Type: application/x-www-form-urlencoded
visibilityRule={"ruleType":"show", "rules":[{"subjectField": "LastName", "operator": "isNotEmpty", "values": [], "altLabel": "Email:"}]}
{
    "success": true,
    "warnings": [],
    "errors": [],
    "requestId": "ab4a#15509030601",
    "result": [
        {
            "formFieldId": "Email",
            "ruleType": "show",
            "rules": [
                {
                    "subjectField": "LastName",
                    "operator": "isNotEmpty",
                    "values": [],
                    "altLabel": "Email:"
                }
            ]
        }
    ]
}

有关运算符的完整列表,请参阅添加表单字段可见性规则

跟进

动态跟进规则可以将访客重定向到页面,或根据提交时指定的字段值将其保留在当前页面上。 感谢页面规则和跟进页面规则引用相同的行为。

将规则表示为JSON数组,其记录包含followupTypefollowupValueoperatorsubjectFieldvaluesdefault。 数组中只有一个记录可以将布尔值default设置为true。 当访客不符合其他规则的资格时,表单会使用该记录。

followupType值可以是lpurllp值表示followupValue是Marketo登陆页面ID。 url值指示followupValue是另一页的URL。 运算符将主题字段值与提供的值进行比较。

提交按钮

使用更新提交按钮端点修改提交按钮样式。 您可以更新buttonPositionbuttonStylelabelwaitingLabel。 提交待处理时显示waitingLabel

这是破坏性更新。

审批

Forms遵循草稿批准的生命周期。 表单可以具有草稿版本、已批准版本或同时具有两者。 更新始终应用于草稿,并且仅在获得批准后才生效。

批准表单会将现有的批准版本(如果有)替换为当前草稿。 取消批准实时表单会删除任何当前草稿,并将批准的版本降级为仅草稿状态。 在尝试删除表单之前,请始终取消批准该表单。

渐进式配置

启用渐进式分析时,表单字段列表包含一个名为Profiling的字段集。 使用“更新字段位置”端点在渐进式分析列表中添加或删除字段。

此端点执行破坏性更新,因此每个请求都必须包含表单中的所有字段。 以下示例将Phone添加到渐进式分析列表。

POST /rest/asset/v1/form/{id}/reArrange.json
Content-Type: application/x-www-form-urlencoded
positions=[{"columnNumber":0,"rowNumber":0,"fieldName":"Email"},{"columnNumber":0,"rowNumber":1,"fieldName":"LastName"},{"columnNumber":0,"rowNumber":2,"fieldName":"Company"},{"columnNumber":0,"rowNumber":3,"fieldName":"Website"},{"columnNumber":0,"rowNumber":4,"fieldName":"Profiling","fieldList":[{"columnNumber":0,"rowNumber":0,"fieldName":"Phone"}]}]
{
    "success": true,
    "errors": [],
    "requestId": "3d6a#164190dbdf2",
    "result": [
        {
            "id": 1031
        }
    ]
}
recommendation-more-help
marketo-developer-help