表单 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

表单是否已发布（默认：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）

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,
  "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。

路径参数

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

响应

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 公开访问。

路径参数

idstring

表单 ID

响应

返回包含 published_version 字段（表示新版本号）的表单对象：

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "published_version": 3,
  "questions": [ ... ]
}

代码示例

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 访问。已发布的版本快照会被保留，以便您稍后重新发布。

路径参数

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

表单未找到

500Server Error

服务器内部错误

错误示例

json

{
  "error": "Title is required"
}

最后更新：2026年4月6日