表单 API

创建、检索、更新、删除、发布和复制表单。

表单 API 允许您以编程方式管理 NueForm 表单。您可以列出、创建、检索、更新、删除、发布、取消发布和复制表单。

所有请求和响应体均使用 snake_case 字段命名。

Endpoints

GET/api/v1/formsPOST/api/v1/formsGET/api/v1/forms/:idPUT/api/v1/forms/:idDELETE/api/v1/forms/:idPOST/api/v1/forms/:id/publishDELETE/api/v1/forms/:id/publishPOST/api/v1/forms/:id/duplicate

列出表单

GET/api/v1/forms

返回已认证用户有权访问的表单分页列表，包括个人表单和用户所属团队的表单。

查询参数

pageinteger

页码（默认：1）

per_pageinteger

每页结果数（默认：50）

searchstring

按标题筛选表单（不区分大小写的模糊匹配）

team_idstring

仅返回属于此团队的表单

publishedboolean

按发布状态筛选（true 或 false）

响应

json

{
  "forms": [
    {
      "id": "665a1b2c3d4e5f6a7b8c9d0e",
      "title": "Customer Feedback Survey",
      "description": "Quarterly satisfaction survey for Q1 2026",
      "slug": "a1b2c3d4e5f6",
      "published": true,
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-02-20T14:22:00.000Z",
      "theme_color": "#6366f1",
      "background_color": "#0a0a0a",
      "response_count": 142,
      "team": {
        "id": "665b2c3d4e5f6a7b8c9d0e1f",
        "name": "Marketing"
      }
    }
  ],
  "total": 24,
  "page": 1,
  "per_page": 50
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/forms?page=1&per_page=10&published=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

创建表单

POST/api/v1/forms

创建新表单。您可以选择性地包含问题数组，与表单一起创建。

请求体

titlestring

表单标题（不能为空）

descriptionstring

表单描述

team_idstring

将表单分配给团队（需要 create_forms 权限）

publishedboolean

设为 true 可在创建表单后立即发布。发布会执行与发布表单相同的检查。如果某项检查未通过，表单仍会以草稿形式创建：响应为 201，其中 published: false，并附带 publish_error 对象（reason、message、question_ids、upgrade_required）。请勿再次创建该表单——修复问题后调用“发布表单”即可。默认：false（草稿）

theme_colorstring

主题主色调（十六进制，默认：#6366f1）

background_colorstring

背景颜色（十六进制，默认：#0a0a0a）

text_colorstring

问题文字颜色（十六进制）

answer_text_colorstring

答案输入文字颜色（十六进制）

placeholder_colorstring

输入占位符颜色（十六进制）

button_colorstring

按钮背景颜色（十六进制）

button_text_colorstring

按钮文字颜色（十六进制）

title_colorstring

标题文字颜色（十六进制）

description_colorstring

描述文字颜色（十六进制）

option_text_colorstring

选项文字颜色（十六进制）

indicator_bg_colorstring

步骤指示器背景颜色（十六进制）

indicator_text_colorstring

步骤指示器文字颜色（十六进制）

font_familystring

问题字体

font_family_answerstring

答案输入字体

font_family_buttonstring

按钮字体

font_family_descriptionstring

描述字体

font_family_optionstring

选项字体

font_family_indicatorstring

步骤指示器字体

question_font_sizestring

问题字号（例如 "24px"）

custom_cssstring

注入到表单渲染器的自定义 CSS

show_progress_barboolean

显示进度条（默认：true）

branding_logo_urlstring

品牌 Logo URL

branding_footer_textstring

自定义页脚文字

hide_brandingboolean

隐藏 NueForm 品牌标识（默认：false）

auto_translateboolean

NueLingo — 为填写者按需将已发布的表单翻译为任意支持的语言（Pro+；其他计划存为 false）。需要设置默认语言；发布后生效。

top_logo_urlstring

显示在表单顶部的 Logo URL

top_logo_sizestring

顶部 Logo 尺寸（例如 "120px"）

top_logo_alignmentstring

顶部 Logo 对齐方式（"left"、"center"、"right"）

top_logo_cssstring

顶部 Logo 的自定义 CSS

watermark_cssstring

水印的自定义 CSS

welcome_titlestring

欢迎页标题

welcome_descriptionstring

欢迎页描述

welcome_button_textstring

欢迎页按钮文字（默认："Start"）

thank_you_titlestring

感谢页标题（默认："Thank you!"）

thank_you_descriptionstring

感谢页描述

modestring

表单模式："standard"、"knowledge_quiz"、"lead_qualification"、"match_quiz"（默认："standard"）

quiz_settingsobject

测验配置（用于测验模式）

variablesobject

表单级别的逻辑变量

start_logic_jumpsarray

表单开始时应用的逻辑跳转规则

webhook_urlstring

提交时接收 POST 请求的 URL（需要 Pro 套餐）

limit_one_responseboolean

限制每位访客只能提交一次响应（默认：false）

incremental_submissionboolean

在受访者填写过程中增量保存答案（默认：false）

questionsarray

要创建的问题对象数组（详见下方）

请求示例

json

{
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "type": "short_text",
      "title": "What is your name?",
      "required": true
    },
    {
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "required": true,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      }
    },
    {
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "required": true,
      "properties": {
        "steps": 5,
        "shape": "star"
      }
    }
  ]
}

响应

返回创建的表单对象及所有问题：

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": false,
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d002",
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "description": null,
      "required": true,
      "order": 1,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      },
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d003",
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "description": null,
      "required": true,
      "order": 2,
      "properties": {
        "steps": 5,
        "shape": "star"
      },
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Feedback Survey",
    "description": "Help us improve our product",
    "questions": [
      {
        "type": "short_text",
        "title": "What is your name?",
        "required": true
      }
    ]
  }'

获取表单

GET/api/v1/forms/:id

通过 ID 检索单个表单，包括按位置排序的所有问题。

路径参数

idstring

表单 ID

响应

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-02-20T14:22:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "text_color": null,
  "answer_text_color": null,
  "placeholder_color": null,
  "button_color": null,
  "button_text_color": null,
  "font_family": null,
  "question_font_size": null,
  "custom_css": null,
  "show_progress_bar": true,
  "incremental_submission": false,
  "limit_one_response": false,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "branding_logo_url": null,
  "branding_footer_text": null,
  "hide_branding": false,
  "auto_translate": false,
  "mode": "standard",
  "webhook_url": null,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "response_count": 142,
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY"

更新表单

PUT/api/v1/forms/:id

更新表单字段并同步其问题。当您包含 questions 数组时，NueForm 将：

更新已有问题（通过 id 匹配）
创建新问题（没有 id 或 id 无法识别）
删除存在于表单上但不在数组中的问题

如果表单当前已发布，has_unpublished_changes 标志会自动设置为 true：您的更改会保存为草稿，受访者会继续看到已发布的版本，直到您再次发布。

published 会改变表单的状态，而不是作为字段直接保存：

对于草稿表单，published: true 会在保存您的更改后发布表单，并执行与发布表单相同的检查。如果某项检查未通过，您的更改仍会保存，API 返回 409 Conflict，并附带 form_id 和 saved_as_draft: true。
对于已上线的表单，published: true 不会产生任何变化——请调用发布表单使您的更改上线。
published: false 会让已上线的表单下线，效果与取消发布表单相同。

对于团队表单，只有团队管理员和所有者才能更改 published。

路径参数

idstring

表单 ID

请求体

接受创建表单中的所有字段（team_id 除外）。仅包含您想要更改的字段。

请求示例

json

{
  "title": "Updated Survey Title",
  "description": "Revised description for Q2",
  "theme_color": "#10b981",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your full name?",
      "required": true
    },
    {
      "type": "long_text",
      "title": "Any additional comments?",
      "required": false
    }
  ]
}

响应

返回更新后的表单对象及所有问题（与获取表单结构相同）。

代码示例

bash

curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Survey Title",
    "theme_color": "#10b981"
  }'

删除表单

DELETE/api/v1/forms/:id

永久删除表单及所有关联数据，包括问题、响应、版本和变更日志条目。关联的文件上传会异步清理。

此操作不可撤销。为此表单收集的所有响应将被永久删除。

路径参数

idstring

表单 ID

查询参数

delete_signed_contractsboolean

删除含有已完成签署合同的表单时必须为 true。这些合同会随表单一起被永久删除，包括已签署的 PDF 和审计跟踪。未传入时不会删除该表单：API 返回 409，并附带 reason: form_has_signed_contracts 和 signed_contracts（合同数量）。

响应

json

{
  "success": true
}

代码示例

bash

curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY"

发布表单

POST/api/v1/forms/:id/publish

通过创建当前表单及其问题的版本快照来发布表单——与构建器中“发布”按钮使用的是同一流程。每次发布都会递增版本号，表单将通过其可分享 URL 公开访问。

在发布之前，NueForm 会检查：

团队表单只能由团队管理员和所有者发布，个人表单只能由其所有者发布（其他人会收到 403 Forbidden；不是该表单所属团队成员的人会收到 404 Not Found）；
Pro 功能（预约问题、电子签名合同、数据节点、表单 webhook 以及收款到您自己的 Stripe 账户）包含在表单所有者的方案中（团队表单为团队所有者的方案）；
预约、邮件步骤、Fuse 和复合组件问题均已完整配置。

如果任何检查未通过，表单不会发布，API 返回 409 Conflict，并附带 reason 代码和需要修复的 question_ids（参见错误处理）。成功的响应包含 published_version 和一个 warnings 数组，其中列出不会阻止发布的提示。

路径参数

idstring

表单 ID

响应

返回已发布的表单，包含 published_version（新版本号）和 warnings（不会阻止发布的提示，通常为空）：

json

{
  "data": {
    "id": "665a1b2c3d4e5f6a7b8c9d0e",
    "title": "Customer Feedback Survey",
    "slug": "a1b2c3d4e5f6",
    "published": true,
    "has_unpublished_changes": false,
    "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
    "published_version": 3,
    "warnings": [
      {
        "code": "booking_attendee_ask",
        "question_id": "66a1b2c3d4e5f6a7b8c9d004",
        "question_title": "Book a demo",
        "message": "Booking question \"Book a demo\" has no attendee email mapping, so respondents will be asked for their email when they book."
      }
    ],
    "questions": [ ... ]
  }
}

发布被阻止（409）

不会发布任何内容。reason 说明哪项检查未通过，question_ids 列出需要修复的问题；当表单所有者的方案需要升级时，upgrade_required 为 true：

json

{
  "error": {
    "code": "CONFLICT",
    "message": "E-signature contracts need a Pro plan to go live. Upgrade to publish this form, or remove the contract question.",
    "status": 409,
    "reason": "contract_requires_pro",
    "question_ids": ["66a1b2c3d4e5f6a7b8c9d001"],
    "upgrade_required": true
  }
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

取消发布表单

DELETE/api/v1/forms/:id/publish

取消发布表单，使其不再通过公开 URL 访问。已发布的版本快照会被保留，以便您稍后重新发布。团队表单只能由团队管理员和所有者取消发布，个人表单只能由其所有者取消发布；其他人会收到 403 Forbidden，不是该表单所属团队成员的人会收到 404 Not Found。

路径参数

idstring

表单 ID

响应

返回 published 设置为 false 的更新后表单对象。

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "published": false,
  "questions": [ ... ]
}

代码示例

bash

curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

复制表单

POST/api/v1/forms/:id/duplicate

创建现有表单的副本，包括所有问题。逻辑跳转引用会自动重新映射到新的问题 ID。复制的表单始终以未发布状态创建。

路径参数

idstring

要复制的表单 ID

请求体

titlestring

新表单的标题（默认："原标题 (Copy)"）

team_idstring

将副本分配给不同的团队

请求示例

json

{
  "title": "Customer Feedback Survey v2",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f"
}

响应

返回新创建的表单对象（与获取表单结构相同），published 设置为 false。

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customer Feedback Survey v2" }'

错误响应

所有端点返回标准错误响应。

错误码

400Bad Request

验证错误或缺少必填字段

401Unauthorized

缺少或无效的 API 密钥

403Forbidden

团队表单权限不足

404Not Found

表单未找到

409Conflict

发布被阻止：某项发布检查未通过（参见发布表单）

500Server Error

服务器内部错误

错误示例

json

{
  "error": "Title is required"
}

最后更新：2026年10月8日