Responses API

Retrieve, filter, delete, and export form responses.

The Responses API lets you retrieve, filter, delete, and export the submissions collected by your forms. All responses are scoped to a specific form.

All request and response bodies use snake_case field names.

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

List Responses

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

Returns a paginated list of responses for a form, ordered by submission date (most recent first).

Path Parameters

idstringrequired

The form ID

Query Parameters

pageinteger

Page number (default: 1)

per_pageinteger

Results per page (default: 50)

sincestring

ISO 8601 date. Only return responses submitted on or after this date.

untilstring

ISO 8601 date. Only return responses submitted on or before this date.

completedboolean

Filter by completion status. true returns only completed responses, false returns only partial responses.

Answer Value Types

short_textstring

Example: "Jane Smith"

long_textstring

Example: "I really enjoyed the product..."

multiple_choicestring

Example: "Option A"

multiple_choice (multi)array of strings

Example: ["Option A", "Option C"]

ratingnumber

Example: 4

opinion_scalenumber

Example: 8

numbernumber

Example: 42

emailstring

Example: "jane@example.com"

datestring (ISO 8601)

Example: "2026-03-15"

yes_noboolean

Example: true

file_uploadobject

Example: { "url": "...", "name": "doc.pdf" }

dropdownstring

Example: "United States"

Response

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
}

Code Examples

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 Response

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

Retrieves a single response by ID.

Path Parameters

idstringrequired

The form ID

responseIdstringrequired

The response ID

Quiz Results

For forms using quiz modes (knowledge_quiz, lead_qualification, match_quiz), the quiz_results field contains scoring data.

Response

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
}

Quiz Results Example

json

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

Code Examples

bash

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

Delete Response

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

Permanently deletes a single response.

This action is irreversible. The response data cannot be recovered after deletion.

Path Parameters

idstringrequired

The form ID

responseIdstringrequired

The response ID

Response

json

{
  "success": true
}

Code Examples

bash

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

Bulk Delete Responses

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

Deletes multiple responses in a single request. Maximum of 100 responses per request. All specified response IDs must belong to the given form.

Path Parameters

idstringrequired

The form ID

Request Body

response_idsarray of stringsrequired

IDs of the responses to delete (max 100)

Request Example

json

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

Response

json

{
  "deleted": 3
}

Code Examples

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"
    ]
  }'

Export Responses (CSV)

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

Exports all responses for a form as a CSV file. The CSV includes columns for responseId, submittedAt, completedAt, and one column per question (using the question title as the column header).

For group questions (question_group, multi_question_page, contact_info, address), each sub-field gets its own column.

Path Parameters

idstringrequired

The form ID

Response

Returns a CSV file with Content-Type: text/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,

Code Examples

bash

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

Error Responses

All endpoints return standard error responses:

Status Codes

400Bad Request

Invalid parameters, bulk delete exceeds 100 items

401Unauthorized

Missing or invalid API key

403Forbidden

Insufficient team permissions

404Not Found

Form or response not found

500Internal Server Error

Internal server error

Error Example

json

{
  "error": "Response not found"
}

Last updated: April 6, 2026