Forms

使用此端点来操作并获取有关 Mautic 表单的详细信息。

使用 Mautic API 库

您可以使用以下 :xref:`Mautic API 库 与此 API 进行交互，或者使用本文档中描述的各种 HTTP 端点。

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth = new ApiAuth();
$auth     = $initAuth->newAuth($settings);
$apiUrl   = "https://example.com";
$api      = new MauticApi();
$formApi  = $api->newApi("forms", $auth, $apiUrl);

获取表单

检索单个表单。

<?php

//...
$form = $formApi->get($id);

HTTP 请求

GET /forms/ID

响应

  • 当请求成功检索到表单时，返回 200 OK。
{
“form”: {

“isPublished”: true, “dateAdded”: “2026-02-19T07:06:12+00:00”, “dateModified”: “2026-02-19T07:10:06+00:00”, “createdBy”: 1, “createdByUser”: “Admin Mautic”, “modifiedBy”: 1, “modifiedByUser”: “Admin Mautic”, “id”: 2, “name”: “Acme Global Conference Registration”, “alias”: “acme_globa”, “category”: {

“createdByUser”: “Admin Mautic”, “modifiedByUser”: null, “id”: 1, “title”: “Company attendees”, “alias”: “company-attendees”, “description”: null, “color”: null, “bundle”: “form”

}, “description”: “<p><span style="color:rgb(186,33,33);"><span class="s2" style="box-sizing:border-box;">Acme Global Conference registration.</span></span></p>”, “cachedHtml”: “n<style type="text/css" scoped>n .mauticform_wrapper { max-width: 600px; margin: 10px auto; }n .mauticform-innerform {}n .mauticform-post-success {}n .mauticform-name { font-weight: bold; font-size: 1.5em; margin-bottom: 3px; }n .mauticform-description { margin-top: 2px; margin-bottom: 10px; }n .mauticform-error { margin-bottom: 10px; color: red; }n .mauticform-message { margin-bottom: 10px; color: green; }n .mauticform-row { display: block; margin-bottom: 20px; }n .mauticform-label { font-size: 1.1em; display: block; font-weight: bold; margin-bottom: 5px; }n .mauticform-row.mauticform-required .mauticform-label:after { color: #e32; content: " "; display: inline; }n .mauticform-helpmessage { display: block; font-size: 0.9em; margin-bottom: 3px; }n .mauticform-errormsg { display: block; color: red; margin-top: 2px; }n .mauticform-selectbox, .mauticform-input, .mauticform-textarea { width: 100%; padding: 0.5em 0.5em; border: 1px solid #CCC; background: #fff; box-shadow: 0px 0px 0px #fff inset; border-radius: 4px; box-sizing: border-box; }n .mauticform-checkboxgrp-row {}n .mauticform-checkboxgrp-label { font-weight: normal; }n .mauticform-checkboxgrp-checkbox {}n .mauticform-radiogrp-row {}n .mauticform-radiogrp-label { font-weight: normal; }n .mauticform-radiogrp-radio {}n .mauticform-button-wrapper .mauticform-button.btn-ghost, .mauticform-pagebreak-wrapper .mauticform-pagebreak.btn-ghost { color: #5d6c7c;background-color: #ffffff;border-color: #dddddd;}n .mauticform-button-wrapper .mauticform-button, .mauticform-pagebreak-wrapper .mauticform-pagebreak { display: inline-block;margin-bottom: 0;font-weight: 600;text-align: center;vertical-align: middle;cursor: pointer;background-image: none;border: 1px solid transparent;white-space: nowrap;padding: 6px 12px;font-size: 13px;line-height: 1.3856;border-radius: 3px;-webkit-user-select: none;-moz-user-select: none;-ms-user-select: none;user-select: none;}n .mauticform-button-wrapper .mauticform-button.btn-ghost[disabled], .mauticform-pagebreak-wrapper .mauticform-pagebreak.btn-ghost[disabled] { background-color: #ffffff; border-color: #dddddd; opacity: 0.75; cursor: not-allowed; }n .mauticform-pagebreak-wrapper .mauticform-button-wrapper { display: inline; }nn /*n * @see https://github.com/TarekRaafat/autoComplete.js/blob/master/dist/css/autoComplete.02.css.n */n .autoComplete_wrapper {position: relative;}n .autoComplete_wrapper > input::placeholder {transition: all 0.3s ease;}n .autoComplete_wrapper > ul {position: absolute;max-height: 226px;overflow-y: scroll;top: 100%;left: 0;right: 0;padding: 0;margin: 0.5rem 0 0 0;border-radius: 4px;background-color: #fff;border: 1px solid rgba(33, 33, 33, 0.1);z-index: 1000;outline: none;}n .autoComplete_wrapper > ul > li {padding: 10px 20px;list-style: none;text-align: left;font-size: 16px;color: #212121;transition: all 0.1s ease-in-out;border-radius: 3px;background-color: rgba(255, 255, 255, 1);white-space: nowrap;overflow: hidden;text-overflow: ellipsis;transition: all 0.2s ease;}n .autoComplete_wrapper > ul > li > span {float: right;}n .autoComplete_wrapper > ul > li::selection {color: rgba(#ffffff, 0);background-color: rgba(#ffffff, 0);}n .autoComplete_wrapper > ul > li:hover {cursor: pointer;background-color: rgba(123, 123, 123, 0.1);}n .autoComplete_wrapper > ul > li mark {background-color: transparent;font-weight: bold;}n .autoComplete_wrapper > ul > li mark::selection {background-color: rgba(#ffffff, 0);}n .autoComplete_wrapper > ul > li[aria-selected="true"] {background-color: rgba(123, 123, 123, 0.1);}n @media only screen and (max-width: 600px) {n .autoComplete_wrapper > input {width: 18rem;}n }n</style>nn<style type="text/css" scoped>n .mauticform-field-hidden { display:none }n</style>n<div id="mauticform_wrapper_acmeglobalconferenceregistration" class="mauticform_wrapper">n <form autocomplete="false" role="form" method="post" action="https://m5-tester.ddev.site/form/submit?formId=2" id="mauticform_acmeglobalconferenceregistration" data-mautic-form="acmeglobalconferenceregistration" enctype="multipart/form-data" ><div class="mauticform-error" id="mauticform_acmeglobalconferenceregistration_error"></div>n <div class="mauticform-message" id="mauticform_acmeglobalconferenceregistration_message"></div><div class="mauticform-innerform">n <div class="mauticform-page-wrapper mauticform-page-1" data-mautic-form-page="1" >n nnn nn nnn nnn<div id="mauticform_acmeglobalconferenceregistration_topic_preference"class="mauticform-row mauticform-text mauticform-field-1">n <label id="mauticform_label_acmeglobalconferenceregistration_topic_preference"for="mauticform_input_acmeglobalconferenceregistration_topic_preference"class="mauticform-label">Topic preference</label>n <span class="mauticform-helpmessage">The talk that you’re looking forward to</span>n <textarea name="mauticform[topic_preference]"id="mauticform_input_acmeglobalconferenceregistration_topic_preference"class="mauticform-textarea"></textarea>n n <span class="mauticform-errormsg" style="display:none;"></span>n</div>n n n n n n<div id="mauticform_acmeglobalconferenceregistration_submit"class="mauticform-row mauticform-button-wrapper mauticform-field-2">n <button class="btn btn-ghost mauticform-button"name="mauticform[submit]"value="1"id="mauticform_input_acmeglobalconferenceregistration_submit"type="submit">Submit</button>n</div>n </div></div><input type="hidden" name="mauticform[formId]" id="mauticform_acmeglobalconferenceregistration_id" value="2"/>n <input type="hidden" name="mauticform[return]" id="mauticform_acmeglobalconferenceregistration_return" value=""/>n <input type="hidden" name="mauticform[formName]" id="mauticform_acmeglobalconferenceregistration_name" value="acmeglobalconferenceregistration"/>n n </form>n</div>n”, “publishUp”: “2026-02-19T07:00:00+00:00”, “publishDown”: “2026-03-06T08:05:00+00:00”, “fields”: [

{

“id”: 2, “label”: “Topic preference”, “showLabel”: true, “alias”: “topic_preference”, “type”: “textarea”, “defaultValue”: null, “isRequired”: false, “validationMessage”: null, “helpMessage”: “The talk that you’re looking forward to”, “order”: 1, “properties”: [], “validation”: [], “parent”: null, “conditions”: [], “labelAttributes”: null, “inputAttributes”: null, “containerAttributes”: null, “leadField”: null, “saveResult”: true, “isAutoFill”: true, “mappedObject”: “company”, “mappedField”: null

}, {

“id”: 3, “label”: “Submit”, “showLabel”: true, “alias”: “submit”, “type”: “button”, “defaultValue”: null, “isRequired”: false, “validationMessage”: null, “helpMessage”: null, “order”: 2, “properties”: [], “validation”: [], “parent”: null, “conditions”: [], “labelAttributes”: null, “inputAttributes”: “class="btn btn-ghost"”, “containerAttributes”: null, “leadField”: null, “saveResult”: true, “isAutoFill”: false, “mappedObject”: null, “mappedField”: null

}

], “actions”: [

{

“id”: 13, “name”: “Add company score”, “description”: null, “type”: “lead.scorecontactscompanies”, “order”: 1, “properties”: {

“score”: 5

}

}

], “template”: “goldstar”, “inKioskMode”: true, “renderStyle”: true, “formType”: “standalone”, “postAction”: “message”, “postActionProperty”: “Thank you for registering and see you there!”, “noIndex”: false, “formAttributes”: null, “language”: “en_US”

}

}

表单属性

    • Name

      • Type

      • Description

      • isPublished

      • boolean

      • 表单的发布状态

      • dateAdded

      • datetime

      • 表单记录的创建日期和时间

      • dateModified

      • datetime

      • 表单记录的最后修改日期和时间

      • createdBy

      • integer

      • 创建表单的用户ID

      • createdByUser

      • string

      • 创建表单用户的姓名

      • modifiedBy

      • integer

      • 最后修改表单的用户ID

      • modifiedByUser

      • string

      • 最后修改表单用户的姓名

      • id

      • integer

      • 表单的ID

      • name

      • string

      • 表单名称

      • alias

      • string

      • 表单自动生成的别名或 slug

      • category

      • object

      • 赋给表单的类别

      • description

      • string

      • 表单描述

      • cachedHtml

      • string

      • 表单自动生成的 HTML 和 CSS 代码

      • publishUp

      • datetime

      • 表单的激活日期和时间

      • publishDown

      • datetime

      • 表单的停用日期和时间

      • fields

      • associative array

      • 包含表单字段的关联数组。键必须与 :ref: 中描述的“表单字段属性”<get Form Field properties> 中的字段别名对应

      • actions

      • associative array

      • 包含表单操作的关联数组。键必须与 :ref: 中描述的“表单操作属性”<get Form action properties> 中的操作别名对应

      • template

      • string

      • 用于设置表单样式的主题

      • inKioskMode

      • boolean

      • Kiosk 模式状态 - 设置为 1 或 true 可禁用提交的 cookie 跟踪和 IP 关联。如果未设置，则默认情况下会跟踪访问者数据

      • renderStyle

      • boolean

      • 渲染样式状态 - 设置为 0 或 false 可禁用在表单输出中包含模板 CSS。如果未设置，则默认为启用

      • formType

      • string

      • 表单类型 - standalone 或 campaign

      • postAction

      • string

      • 提交后执行的操作。必须是以下之一：

        • return: 不执行任何操作

        • redirect: 重定向到指定的 URL

        • message: 显示成功消息

      • postActionProperty

      • string

      • 与 postAction 相关联的数据。当设置为 redirect 时，包含重定向的 URL；当设置为 message 时，包含成功消息

      • noIndex

      • boolean

      • 搜索索引状态 - 设置为 1 或 true 可发送 noindex HTTP 头部。如果未设置，则默认为启用索引

      • formAttributes

      • string

      • 添加到 <form> 标签的自定义 HTML 属性

      • language

      • string

      • 表单的语言代码，例如 en_US、fr 等

表单字段属性

名称

类型

描述

id

integer

字段的 ID

label

string

显示在字段上的标签

showLabel

boolean

标签可见性状态 - 0 或 false 会在表单上隐藏标签。如果未设置，系统默认显示标签

alias

string

字段的自动生成的别名或 slug

type

string

字段类型，例如 text、email、select 等。请参阅 表单字段类型 以获取详细信息

defaultValue

string

分配给该字段的初始值

isRequired

boolean

必填状态 - 1 或 true 表示该字段是提交时必须填写的。如果未设置，默认为可选

validationMessage

string

用户在离开必填字段时显示的自定义消息

helpMessage

string

帮助用户填写该字段的文本

order

integer

表单中字段的数值位置

properties

object

基于字段类型的特定配置选项

validation

object

应用于该字段的验证规则列表

parent

integer

用于条件逻辑的父字段的 ID

conditions

object

条件逻辑的配置，包含：

  • expr: 比较运算符。接受“包含” - in 或 “排除” - notIn

  • values: 用于与父字段匹配的值数组

  • any: 匹配逻辑，其中 1 匹配任何值，而 0 只匹配提供的特定值

labelAttributes

string

标签元素的 HTML 属性

inputAttributes

string

输入元素的 HTML 属性

containerAttributes

string

字段包装器或容器的 HTML 属性

leadField

string

映射到目标对象的内部引用名称

saveResult

boolean

结果存储状态 - 0 或 false 会阻止 Mautic 将提交的值存储在数据库中。如果未设置，则默认为保存提交的内容

isAutoFill

boolean

自动填充状态 - 0 或 false 会阻止该字段预先填充已知数据，并且会阻止 Mautic 将值保存到数据库中。Mautic 默认情况下会自动填充并保存数据

mappedObject

string

该字段映射到的对象类型 - contact 或 company

mappedField

string

表单字段映射到的特定联系人或公司字段

Form action properties

Name

Type

Description

id

integer

ID of the action

name

string

Name of the action

description

string

Description of the action

type

string

Type of action, such as lead.scorecontactscompanies, email.send.lead, and so on. Refer to Form action types for details

order

integer

The numerical position of the action within the Form

properties

object

The settings for the specific action type

List Forms

Retrieves a list of Forms.

<?php

//...
$forms = $formApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP request

GET /forms

Query parameters

Name

Type

Description

searchFilter

string

String or search command to filter entities

start

integer

Starting row for the returned entities - defaults to 0

limit

integer

Maximum number of entities to return - defaults to 30

orderBy

string

Column to sort by. Any column in the response is valid.

Note: convert camelCase properties to snake_case. For example, dateAdded becomes date_added, webhookUrl becomes webhook_url, and so on

orderByDir

string

Order direction - asc or desc

publishedOnly

boolean

Returns only currently published entities

minimal

boolean

Returns only a simple mapped object of entities without additional lists in it

Response

  • Returns 200 OK when the request successfully retrieves the Forms list.
{

“total”: 2, “forms”: [

{

“isPublished”: true, “dateAdded”: “2026-02-19T07:06:12+00:00”, “dateModified”: “2026-02-19T07:10:06+00:00”, “createdBy”: 1, “createdByUser”: “Admin Mautic”, “modifiedBy”: 1, “modifiedByUser”: “Admin Mautic”, “id”: 2, “name”: “Acme Global Conference Registration”, “alias”: “acme_globa”, “category”: {

“createdByUser”: “Admin Mautic”, “modifiedByUser”: null, “id”: 1, “title”: “Company attendees”, “alias”: “company-attendees”, “description”: null, “color”: null, “bundle”: “form”

}, “description”: “<p><span style="color:rgb(186,33,33);"><span class="s2" style="box-sizing:border-box;">Acme Global Conference registration.</span></span></p>”, “cachedHtml”: “n<style type="text/css" scoped>n .mauticform_wrapper { max-width: 600px; margin: 10px auto; }n .mauticform-innerform {}n .mauticform-post-success {}n .mauticform-name { font-weight: bold; font-size: 1.5em; margin-bottom: 3px; }n .mauticform-description { margin-top: 2px; margin-bottom: 10px; }n .mauticform-error { margin-bottom: 10px; color: red; }n .mauticform-message { margin-bottom: 10px; color: green; }n .mauticform-row { display: block; margin-bottom: 20px; }n .mauticform-label { font-size: 1.1em; display: block; font-weight: bold; margin-bottom: 5px; }n .mauticform-row.mauticform-required .mauticform-label:after { color: #e32; content: " "; display: inline; }n .mauticform-helpmessage { display: block; font-size: 0.9em; margin-bottom: 3px; }n .mauticform-errormsg { display: block; color: red; margin-top: 2px; }n .mauticform-selectbox, .mauticform-input, .mauticform-textarea { width: 100%; padding: 0.5em 0.5em; border: 1px solid #CCC; background: #fff; box-shadow: 0px 0px 0px #fff inset; border-radius: 4px; box-sizing: border-box; }n .mauticform-checkboxgrp-row {}n .mauticform-checkboxgrp-label { font-weight: normal; }n .mauticform-checkboxgrp-checkbox {}n .mauticform-radiogrp-row {}n .mauticform-radiogrp-label { font-weight: normal; }n .mauticform-radiogrp-radio {}n .mauticform-button-wrapper .mauticform-button.btn-ghost, .mauticform-pagebreak-wrapper .mauticform-pagebreak.btn-ghost { color: #5d6c7c;background-color: #ffffff;border-color: #dddddd;}n .mauticform-button-wrapper .mauticform-button, .mauticform-pagebreak-wrapper .mauticform-pagebreak { display: inline-block;margin-bottom: 0;font-weight: 600;text-align: center;vertical-align: middle;cursor: pointer;background-image: none;border: 1px solid transparent;white-space: nowrap;padding: 6px 12px;font-size: 13px;line-height: 1.3856;border-radius: 3px;-webkit-user-select: none;-moz-user-select: none;-ms-user-select: none;user-select: none;}n .mauticform-button-wrapper .mauticform-button.btn-ghost[disabled], .mauticform-pagebreak-wrapper .mauticform-pagebreak.btn-ghost[disabled] { background-color: #ffffff; border-color: #dddddd; opacity: 0.75; cursor: not-allowed; }n .mauticform-pagebreak-wrapper .mauticform-button-wrapper { display: inline; }nn /*n * @see https://github.com/TarekRaafat/autoComplete.js/blob/master/dist/css/autoComplete.02.css.n */n .autoComplete_wrapper {position: relative;}n .autoComplete_wrapper > input::placeholder {transition: all 0.3s ease;}n .autoComplete_wrapper > ul {position: absolute;max-height: 226px;overflow-y: scroll;top: 100%;left: 0;right: 0;padding: 0;margin: 0.5rem 0 0 0;border-radius: 4px;background-color: #fff;border: 1px solid rgba(33, 33, 33, 0.1);z-index: 1000;outline: none;}n .autoComplete_wrapper > ul > li {padding: 10px 20px;list-style: none;text-align: left;font-size: 16px;color: #212121;transition: all 0.1s ease-in-out;border-radius: 3px;background-color: rgba(255, 255, 255, 1);white-space: nowrap;overflow: hidden;text-overflow: ellipsis;transition: all 0.2s ease;}n .autoComplete_wrapper > ul > li > span {float: right;}n .autoComplete_wrapper > ul > li::selection {color: rgba(#ffffff, 0);background-color: rgba(#ffffff, 0);}n .autoComplete_wrapper > ul > li:hover {cursor: pointer;background-color: rgba(123, 123, 123, 0.1);}n .autoComplete_wrapper > ul > li mark {background-color: transparent;font-weight: bold;}n .autoComplete_wrapper > ul > li mark::selection {background-color: rgba(#ffffff, 0);}n .autoComplete_wrapper > ul > li[aria-selected="true"] {background-color: rgba(123, 123, 123, 0.1);}n @media only screen and (max-width: 600px) {n .autoComplete_wrapper > input {width: 18rem;}n }n</style>nn<style type="text/css" scoped>n .mauticform-field-hidden { display:none }n</style>n<div id="mauticform_wrapper_acmeglobalconferenceregistration" class="mauticform_wrapper">n <form autocomplete="false" role="form" method="post" action="https://m5-tester.ddev.site/form/submit?formId=2" id="mauticform_acmeglobalconferenceregistration" data-mautic-form="acmeglobalconferenceregistration" enctype="multipart/form-data" ><div class="mauticform-error" id="mauticform_acmeglobalconferenceregistration_error"></div>n <div class="mauticform-message" id="mauticform_acmeglobalconferenceregistration_message"></div><div class="mauticform-innerform">n <div class="mauticform-page-wrapper mauticform-page-1" data-mautic-form-page="1" >n nnn nn nnn nnn<div id="mauticform_acmeglobalconferenceregistration_topic_preference"class="mauticform-row mauticform-text mauticform-field-1">n <label id="mauticform_label_acmeglobalconferenceregistration_topic_preference"for="mauticform_input_acmeglobalconferenceregistration_topic_preference"class="mauticform-label">Topic preference</label>n <span class="mauticform-helpmessage">The talk that you’re looking forward to</span>n <textarea name="mauticform[topic_preference]"id="mauticform_input_acmeglobalconferenceregistration_topic_preference"class="mauticform-textarea"></textarea>n n <span class="mauticform-errormsg" style="display:none;"></span>n</div>n n n n n n<div id="mauticform_acmeglobalconferenceregistration_submit"class="mauticform-row mauticform-button-wrapper mauticform-field-2">n <button class="btn btn-ghost mauticform-button"name="mauticform[submit]"value="1"id="mauticform_input_acmeglobalconferenceregistration_submit"type="submit">Submit</button>n</div>n </div></div><input type="hidden" name="mauticform[formId]" id="mauticform_acmeglobalconferenceregistration_id" value="2"/>n <input type="hidden" name="mauticform[return]" id="mauticform_acmeglobalconferenceregistration_return" value=""/>n <input type="hidden" name="mauticform[formName]" id="mauticform_acmeglobalconferenceregistration_name" value="acmeglobalconferenceregistration"/>n n </form>n</div>n”, “publishUp”: “2026-02-19T07:00:00+00:00”, “publishDown”: “2026-03-06T08:05:00+00:00”, “fields”: [

{

“id”: 2, “label”: “Topic preference”, “showLabel”: true, “alias”: “topic_preference”, “type”: “textarea”, “defaultValue”: null, “isRequired”: false, “validationMessage”: null, “helpMessage”: “The talk that you’re looking forward to”, “order”: 1, “properties”: [], “validation”: [], “parent”: null, “conditions”: [], “labelAttributes”: null, “inputAttributes”: null, “containerAttributes”: null, “leadField”: null, “saveResult”: true, “isAutoFill”: true, “mappedObject”: “company”, “mappedField”: null

}, {

“id”: 3, “label”: “Submit”, “showLabel”: true, “alias”: “submit”, “type”: “button”, “defaultValue”: null, “isRequired”: false, “validationMessage”: null, “helpMessage”: null, “order”: 2, “properties”: [], “validation”: [], “parent”: null, “conditions”: [], “labelAttributes”: null, “inputAttributes”: “class="btn btn-ghost"”, “containerAttributes”: null, “leadField”: null, “saveResult”: true, “isAutoFill”: false, “mappedObject”: null, “mappedField”: null

}

], “actions”: [

{

“id”: 13, “name”: “Add company score”, “description”: null, “type”: “lead.scorecontactscompanies”, “order”: 1, “properties”: {

“score”: 5

}

}

], “template”: “goldstar”, “inKioskMode”: true, “renderStyle”: true, “formType”: “standalone”, “postAction”: “message”, “postActionProperty”: “Thank you for registering and see you there!”, “noIndex”: false, “formAttributes”: null, “language”: “en_US”

}, // …

]

}

Properties

Name

Type

Description

total

integer

Total count of Forms

forms

array

Array of Forms

For the rest of the properties, refer to Form properties.

Create Form

Creates a new Form.

<?php

$data = array(
    'name'               => 'Form created via API',           // Required
    'postActionProperty' => 'Thank you for your submission!', // Required
    'fields'             => array(                            // Required
        array(
            'label'        => 'Email',                        // Required
            'type'         => 'text',
            'alias'        => 'email',
            'mappedObject' => 'contact',
            'mappedField'  => 'email',
            'isRequired'   => true,
        ),
        array(
            'label' =>    'Submit',                           // Required
            'type'  => 'button',
        ),
    ),
    'actions' => array(                                       // Required
        array(
            'properties'  => array(                           // Required
                'subject' => 'New form submission',
                'message' => 'A new form submission has been received.',
                'email'   => 'admin@example.com'
            ),
            'name'        => 'Send notification',
            'type'        => 'email.send.lead',
        ),
    ),
    'formType'           => 'standalone',
    'postAction'         => 'message',
    'description'        => 'This is a test form created via API',
);

$form = $formApi->create($data);

HTTP request

POST /forms/new

POST parameters

    • Name

      • Type

      • Description

      • name

      • string

      • Required.

        表单名称

      • postActionProperty

      • string

      • Required.

        与 postAction 关联的数据。当设置为 redirect 时，包含重定向 URL；当设置为 message 时，包含成功消息。

      • fields

      • array

      • Required.

        表单字段数组。请参阅 字段参数 表格以了解可用选项。

      • actions

      • array

      • Required.

        表单操作数组。请参阅 操作参数 表格以了解可用选项。

      • formType

      • string

      • 表单类型，可以是 standalone 或 campaign

      • postAction

      • string

      • 提交后执行的操作。必须是以下之一：

        • return: 不执行任何操作

        • redirect: 重定向到指定的 URL

        • message: 显示成功消息

      • isPublished

      • boolean

      • 表单发布状态

字段参数

这些参数位于 fields 数组中。

Name

Type

Description

label

string

Required.

显示的字段标签

type

string

字段类型，例如 text、email 或 select

mappedObject

string

该字段映射的对象类型，可以是 contact 或 company

mappedField

string

表单字段映射到的特定联系人或公司字段

isRequired

boolean

字段的强制性状态

操作参数

这些参数位于 actions 数组中。

Name

Type

Description

properties

array

Required.

特定操作类型的设置，例如电子邮件 ID 或主题。

name

string

操作名称

type

string

操作类型，例如 email.send.lead

响应

  • 当请求成功创建表单时，返回 201 Created。

响应是一个类似于 Get Form 的 JSON 对象。

属性

请参阅 Form properties。

编辑表单

编辑一个表单。

此操作支持 PUT 或 PATCH，具体取决于所需的行为：

  • PUT: 完全替换。如果 ID 缺失，则请求会创建一个新的表单。如果 ID 存在，则请求会清除所有现有数据并用提供的值进行替换。

  • PATCH: 部分更新。该请求仅根据请求数据更新字段值。如果表单 ID 不存在，则请求失败。

```php <?php

$id = 1; $data = array(

‘name’ => ‘更新后的表单名称’, ‘description’ => ‘更新后的描述’, ‘fields’ => array(

array(

‘id’ => 1, // 现有字段 ‘label’ => ‘更新后的电子邮件标签’, ‘type’ => ‘text’, ‘alias’ => ‘email’, ‘mappedObject’ => ‘contact’, ‘mappedField’ => ‘email’, ‘isRequired’ => true,

), array(

‘label’ => ‘名字’, // 新字段 ‘type’ => ‘text’, ‘alias’ => ‘first_name’, ‘mappedObject’ => ‘contact’, ‘mappedField’ => ‘firstname’,

),

),

);

// 如果 ID 1 未找到，则创建一个新的表单 $createIfNotFound = true;

$form = $formApi->edit($id, $data, $createIfNotFound);

HTTP 请求

  • PUT /forms/ID/edit: 更新现有的表单，或者当 ID 不存在时创建一个新的表单。

  • PATCH /forms/ID/edit: 更新现有的表单。如果 ID 不存在，则请求失败。

POST 参数

接受与 创建表单 中描述的相同参数。所有参数都是可选的。

响应

  • PUT: 当请求成功更新表单时返回 200 OK，或者当请求创建表单时返回 201 Created。

  • PATCH: 当请求成功更新表单时返回 200 OK，或者当表单 ID 不存在时返回 404 Not Found 错误。

响应是一个类似于 获取表单 的 JSON 对象。

属性

请参考 表单属性.

删除表单

删除一个表单。

<?php

$form = $formApi->delete($id);

HTTP 请求

DELETE /forms/ID/delete

响应

  • 当请求成功删除表单时，返回 200 OK。

响应是一个包含已删除表单数据的 JSON 对象，类似于 获取表单。

属性

请参考 表单属性.

删除表单字段

从一个表单中删除特定的字段。

<?php

$formApi->deleteFields($formId, array(1, 2, 3));

HTTP 请求

DELETE /forms/ID/fields/delete

参数

Name

Type

Description

fields

array

必需。

要删除的表单字段 ID 的数组。

响应

  • 当请求成功删除表单字段时，返回 200 OK。

```

The response is a JSON object containing the data of the deleted Form Fields, similar to Get Form.

Properties

Refer to Form properties.

Delete Form actions

Deletes specific actions from a Form.

<?php

$formApi->deleteActions($formId, array(1, 2));

HTTP request

DELETE /forms/ID/actions/delete

Parameters

Name

Type

Description

actions

array

Required.

Array of Form action IDs to delete

Response

  • Returns 200 OK when the request successfully deletes the Form actions.

The response is a JSON object containing the data of the deleted Form actions, similar to Get Form.

Properties

Refer to Form properties.

Get Form submission

Get an individual submission for a specific Form.

<?php

$submission = $formApi->getSubmission($formId, $submissionId);

HTTP request

GET /forms/FORM_ID/submissions/SUBMISSION_ID

Response

  • Returns 200 OK when the request successfully retrieves the Form submission.

{
   "submission": {
       "id": 2,
       "ipAddress": {
           "ipAddress": "127.0.0.1"
       },
       "form": {
           "id": 2,
           "name": "Acme Global Conference Registration",
           "alias": "acme_globa",
           "category": {}
       },
       "lead": {
           "id": 3,
           "points": 0,
           "color": null,
           "title": null,
           "firstname": "Jack",
           "lastname": "Smith",
           "company": "Beta Inc.",
           "position": null,
           "email": null,
           "phone": null,
           "mobile": null,
           "address1": null,
           "address2": null,
           "city": null,
           "state": null,
           "zipcode": null,
           "timezone": null,
           "country": null
       },
       "trackingId": null,
       "dateSubmitted": "2026-02-19T07:27:18+00:00",
       "referer": "https://example.com/forms/2",
       "page": null,
       "results": {
             "form_id": "2",
             "topic_preference": "The Rising of Open Source",
             "company_name": "Beta Inc.",
             "availability": "2026-02-20",
             "email": null,
             "first_name": "Jack",
             "last_name": "Smith"
       }
   }
}

Form submission properties

Name

Type

Description

id

integer

ID of the Form submission

ipAddress

object

Information about the IP address used for the submission

form

object

Information about the Form that received the submission

lead

object

The Contact record associated with the submission

trackingId

string

ID used for tracking the submission source

dateSubmitted

datetime

Date and time of the submission

referer

string

The URL of the page where the User submitted the Form

page

object

The specific Mautic Landing Page where the submission occurred

results

object

The values submitted for each Form Field

List Form submissions

Retrieves a list of submissions for a specific Form.

<?php

$submissions = $formApi->getSubmissions($formId, $searchFilter, $start, $limit, $orderBy, $orderByDir);

HTTP request

GET /forms/ID/submissions

Query parameters

Name

Type

Description

searchFilter

string

String or search command to filter entities

start

integer

Starting row for the returned entities - defaults to 0

limit

integer

Maximum number of entities to return - defaults to 30

orderBy

string

Column to sort by. Any column in the response is valid

Note: convert camelCase properties to snake_case. For example, dateAdded becomes date_added, webhookUrl becomes webhook_url, and so on

orderByDir

string

Order direction - asc or desc

Response

  • Returns 200 OK when the request successfully retrieves the Form submissions.
{

“total”: “4”, “submissions”: [

{

“id”: 2, “ipAddress”: {

“ipAddress”: “127.0.0.1”

}, “form”: {

“id”: 2, “name”: “Acme Global Conference Registration”, “alias”: “acme_globa”, “category”: {}

}, “lead”: {

“id”: 3, “points”: 0, “color”: null, “title”: null, “firstname”: “Jack”, “lastname”: “Smith”, “company”: “Beta Inc.”, “position”: null, “email”: null, “phone”: null, “mobile”: null, “address1”: null, “address2”: null, “city”: null, “state”: null, “zipcode”: null, “timezone”: null, “country”: null

}, “trackingId”: null, “dateSubmitted”: “2026-02-19T07:27:18+00:00”, “referer”: “https://example.com/forms/2”, “page”: null, “results”: {

“first_name”: “Jack”, “last_name”: “Smith”, “company_name”: “Beta Inc.”, “availability”: “2026-02-20”, “topic_preference”: “The Rising of Open Source”

}

}, // …

]

}

Properties

Name

Type

Description

total

integer

Total count of Form submissions

forms

array

Array of Form submissions

For the rest of the Form properties, refer to Form submission properties.

Get Contact Form submissions

Retrieves a Contact from a specific Form submission.

<?php

$submissions = $formApi->getContactSubmissions($formId, $contactId, $searchFilter, $start, $limit, $orderBy, $orderByDir);

HTTP request

GET /forms/FORM_ID/submissions/contact/CONTACT_ID

Query parameters

    • Name

      • Type

      • Description

      • searchFilter

      • string

      • 用于过滤实体的字符串或搜索命令。

      • start

      • integer

      • 返回的实体起始行，默认为 0。

      • limit

      • integer

      • 要返回的最大实体数量，默认为 30。

      • orderBy

      • string

      • 用于排序的列。响应中的任何列都有效。

        注意: 将 camelCase 属性转换为 snake_case。例如，dateAdded 变为 date_added，webhookUrl 变为 webhook_url，依此类推。

      • orderByDir

      • string

      • 排序方向，可以是 asc 或 desc。

Response

  • 当请求成功检索到表单提交的联系人时，返回 200 OK。

{
   "total": "1",
   "submissions": [
       {
           "id": 2,
           "ipAddress": {
               "ipAddress": "127.0.0.1"
           },
           "form": {
               "id": 2,
               "name": "Acme Global Conference Registration",
               "alias": "acme_globa",
               "category": {}
           },
           "lead": {
               "id": 3,
               "points": 0,
               "color": null,
               "title": null,
               "firstname": "Jack",
               "lastname": "Smith",
               "company": "Beta Inc.",
               "position": null,
               "email": null,
               "phone": null,
               "mobile": null,
               "address1": null,
               "address2": null,
               "city": null,
               "state": null,
               "zipcode": null,
               "timezone": null,
               "country": null
           },
           "trackingId": null,
           "dateSubmitted": "2026-02-19T07:27:18+00:00",
           "referer": "https://example.com/forms/2",
           "page": null,
           "results": {
               "first_name": "Jack",
               "last_name": "Smith",
               "company_name": "Beta Inc.",
               "availability": "2026-02-20",
               "topic_preference": "The Rising of Open Source"
           }
       }
   ]
}

Properties

Name

Type

Description

total

integer

表单提交的总数。

submissions

array

表单提交的数组。

有关其他表单属性，请参阅 Form submission properties。

Form Field types

Mautic 支持各种表单字段类型，用于收集和验证联系人数据。每种字段类型在表单提交过程中都具有特定的用途：

Field type

Description

Properties

captcha

CAPTCHA field

placeholder, captcha, errorMessage

checkboxgrp

Checkbox group

syncList, optionlist - an object of list arrays, labelAttributes

companyLookup

Company lookup

None

date

Date picker

format, placeholder

datetime

Date and time picker

format

freetext

Description area

text

email

Email input with validation

placeholder

file

File upload

allowed_file_size, allowed_file_extensions, public, profile_image

freehtml

HTML area

text

hidden

Hidden field

None

number

Number input

placeholder, precision

pagebreak

Page break for multi-page Forms

next_page_label, prev_page_label

password

Password

None

tel

Telephone input

placeholder

radiogrp

Radio group

syncList, optionlist - an object of list arrays, labelAttributes

country

Country selection dropdown

placeholder, multiple

select

Dropdown selection

placeholder, syncList, list - an object of list arrays, multiple

textarea

Multi-line text input

placeholder, rows, maxlength

text

Single line text input

placeholder, maxlength

url

URL input with validation

placeholder

button

Submit button

None

表单操作类型

表单操作在联系人提交表单后立即执行特定任务。Mautic 支持以下操作类型：

    • Action type

      • Description

      • Properties

      • lead.scorecontactscompanies

      • Add to Company’s score

      • score

      • lead.pointschange

      • Adjust Contact’s Points

      • operator, points, group

      • lead.changelist

      • Modify Contact’s Segments

      • addToLists, removeFromLists

      • lead.changetags

      • Modify Contact’s tags

      • add_tags, remove_tags

      • lead.addutmtags

      • Record UTM Tags

      • None

      • lead.remove_do_not_contact

      • Remove Contact from Do Not Contact list

      • None

      • asset.download

      • Download an Asset

      • asset, category

      • form.repost

      • Forwards submission results to an external URL or Form

      • post_url, authorization_header, failure_email

      • plugin.leadpush

      • Push Contact to Integration

      • integration

      • email.send.lead

      • Send Email to Contact

      • email

      • email.send.user

      • Send Email to User

      • useremail, user_id

      • form.email

      • Send Form results

      • subject, immediately, set_replyto, message, email_to_owner, copy_lead, templates, to, cc, bcc

分阶段收集信息

分阶段收集信息通过根据之前的提交情况显示不同的字段，从而在一段时间内从联系人那里收集更多信息。 要启用分阶段收集信息：

  1. 在表单中设置 progressiveProfilingLimit

  2. 配置具有 showAfterXSubmissions 属性的字段

  3. 使用 showWhenValueExists 来隐藏如果该联系人的某个字段已经存在值时，则隐藏该字段

条件字段

Mautic 会根据其他字段的值有条件地显示字段：

  1. 设置 parent 字段 ID

  2. 配置 conditions，使用表达式类型 - eq, neq, in 和 !in

  3. 将 isConditionallyHidden 设置为 true

映射字段

Mautic 可以将表单字段映射到联系人或公司字段：

  • 使用 mappedObject 指定 contact 或 company

  • 使用 mappedField 指定目标字段名称

  • Mautic 仍然支持用于向后兼容性的已弃用的 leadField 属性