响应 API

检索、筛选、删除和导出表单响应。

响应 API 允许您检索、筛选、删除和导出表单收集的提交数据。所有响应都归属于特定表单。

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

Endpoints

GET/api/v1/forms/:id/responsesGET/api/v1/forms/:id/responses/:responseIdDELETE/api/v1/forms/:id/responses/:responseIdPOST/api/v1/forms/:id/responses/bulk-deleteGET/api/v1/forms/:id/responses/export

列出响应

GET/api/v1/forms/:id/responses

返回表单的响应分页列表，按提交日期排序（最新优先）。

路径参数

idstring必填

表单 ID

查询参数

pageinteger

页码（默认：1）

per_pageinteger

每页结果数（默认：50）

sincestring

ISO 8601 日期。仅返回在此日期或之后提交的响应。

untilstring

ISO 8601 日期。仅返回在此日期或之前提交的响应。

completedboolean

按完成状态筛选。true 仅返回已完成的响应，false 仅返回部分响应。

答案值类型

short_textstring

示例："Jane Smith"

long_textstring

示例："I really enjoyed the product..."

multiple_choicestring

示例："Option A"

multiple_choice (multi)array of strings

示例：["Option A", "Option C"]

ratingnumber

示例：4

opinion_scalenumber

示例：8

numbernumber

示例：42

emailstring

示例："jane@example.com"

datestring (ISO 8601)

示例："2026-03-15"

yes_noboolean

示例：true

file_uploadobject

示例：{ "url": "...", "name": "doc.pdf" }

dropdownstring

示例："United States"

响应

json

{
  "responses": [
    {
      "id": "667a1b2c3d4e5f6a7b8c9d01",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "visitor_id": "v_8f2k3j4l5m6n",
      "submitted_at": "2026-02-27T15:42:00.000Z",
      "completed_at": "2026-02-27T15:45:30.000Z",
      "metadata": {
        "user_agent": "Mozilla/5.0",
        "referrer": "https://example.com"
      },
      "answers": [
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d001",
          "value": "Jane Smith"
        },
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d002",
          "value": "Social media"
        },
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d003",
          "value": 5
        }
      ],
      "quiz_results": null
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 50
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses?page=1&per_page=25&completed=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

获取响应

GET/api/v1/forms/:id/responses/:responseId

通过 ID 检索单个响应。

路径参数

idstring必填

表单 ID

responseIdstring必填

响应 ID

测验结果

对于使用测验模式（knowledge_quiz、lead_qualification、match_quiz）的表单，quiz_results 字段包含评分数据。

响应

json

{
  "id": "667a1b2c3d4e5f6a7b8c9d01",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "visitor_id": "v_8f2k3j4l5m6n",
  "submitted_at": "2026-02-27T15:42:00.000Z",
  "completed_at": "2026-02-27T15:45:30.000Z",
  "metadata": {
    "user_agent": "Mozilla/5.0",
    "referrer": "https://example.com"
  },
  "answers": [
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d001",
      "value": "Jane Smith"
    },
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d002",
      "value": "Social media"
    },
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d003",
      "value": 5
    }
  ],
  "quiz_results": null
}

测验结果示例

json

{
  "quiz_results": {
    "score": 8,
    "correct_answers": 4,
    "total_scorable_questions": 5,
    "max_score": 10,
    "matched_ending_id": null,
    "form_mode": "knowledge_quiz"
  }
}

代码示例

bash

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

删除响应

DELETE/api/v1/forms/:id/responses/:responseId

永久删除单个响应。

此操作不可撤销。删除后响应数据无法恢复。

路径参数

idstring必填

表单 ID

responseIdstring必填

响应 ID

响应

json

{
  "success": true
}

代码示例

bash

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

批量删除响应

POST/api/v1/forms/:id/responses/bulk-delete

在单个请求中删除多个响应。每次请求最多删除 100 个响应。所有指定的响应 ID 必须属于给定的表单。

路径参数

idstring必填

表单 ID

请求体

response_idsarray of strings必填

要删除的响应 ID（最多 100 个）

请求示例

json

{
  "response_ids": [
    "667a1b2c3d4e5f6a7b8c9d01",
    "667a1b2c3d4e5f6a7b8c9d02",
    "667a1b2c3d4e5f6a7b8c9d03"
  ]
}

响应

json

{
  "deleted": 3
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "response_ids": [
      "667a1b2c3d4e5f6a7b8c9d01",
      "667a1b2c3d4e5f6a7b8c9d02"
    ]
  }'

导出响应 (CSV)

GET/api/v1/forms/:id/responses/export

将表单的所有响应导出为 CSV 文件。CSV 包含 responseId、submittedAt、completedAt 列，以及每个问题一列（使用问题标题作为列标题）。

对于分组问题（question_group、multi_question_page、contact_info、address），每个子字段都有独立的列。

路径参数

idstring必填

表单 ID

响应

返回 Content-Type: text/csv 的 CSV 文件。

text

responseId,submittedAt,completedAt,What is your name?,How did you hear about us?,How would you rate your overall experience?
667a1b2c3d4e5f6a7b8c9d01,2026-02-27T15:42:00.000Z,2026-02-27T15:45:30.000Z,Jane Smith,Social media,5
667a1b2c3d4e5f6a7b8c9d02,2026-02-26T10:15:00.000Z,2026-02-26T10:18:22.000Z,Bob Johnson,Search engine,4
667a1b2c3d4e5f6a7b8c9d03,2026-02-25T08:30:00.000Z,,Alex Chen,Friend or colleague,

代码示例

bash

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

错误响应

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

状态码

400Bad Request

参数无效，批量删除超过 100 条

401Unauthorized

缺少或无效的 API 密钥

403Forbidden

团队权限不足

404Not Found

表单或响应未找到

500Internal Server Error

服务器内部错误

错误示例

json

{
  "error": "Response not found"
}

最后更新：2026年4月6日