API de Respostas

Recupere, filtre, exclua e exporte respostas de formulários.

A API de Respostas permite recuperar, filtrar, excluir e exportar os envios coletados pelos seus formulários. Todas as respostas são vinculadas a um formulário específico.

Todos os corpos de requisição e resposta usam nomes de campos em 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

Listar respostas

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

Retorna uma lista paginada de respostas de um formulário, ordenada pela data de envio (mais recentes primeiro).

Parâmetros de caminho

idstringobrigatório

O ID do formulário

Parâmetros de consulta

pageinteger

Número da página (padrão: 1)

per_pageinteger

Resultados por página (padrão: 50)

sincestring

Data em formato ISO 8601. Retorna apenas respostas enviadas nessa data ou depois dela.

untilstring

Data em formato ISO 8601. Retorna apenas respostas enviadas nessa data ou antes dela.

completedboolean

Filtra pelo status de conclusão. true retorna apenas respostas concluídas, false retorna apenas respostas parciais.

Tipos de valor de resposta

short_textstring

Exemplo: "Jane Smith"

long_textstring

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

multiple_choicestring

Exemplo: "Option A"

multiple_choice (multi)array of strings

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

ratingnumber

Exemplo: 4

opinion_scalenumber

Exemplo: 8

numbernumber

Exemplo: 42

emailstring

Exemplo: "jane@example.com"

datestring (ISO 8601)

Exemplo: "2026-03-15"

yes_noboolean

Exemplo: true

file_uploadobject

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

dropdownstring

Exemplo: "United States"

Resposta

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
}

Exemplos de código

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"

Obter resposta

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

Recupera uma única resposta pelo ID.

Parâmetros de caminho

idstringobrigatório

O ID do formulário

responseIdstringobrigatório

O ID da resposta

Resultados do questionário

Para formulários que usam modos de questionário (knowledge_quiz, lead_qualification, match_quiz), o campo quiz_results contém os dados de pontuação.

Resposta

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
}

Exemplo de resultados do questionário

json

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

Exemplos de código

bash

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

Excluir resposta

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

Exclui permanentemente uma única resposta.

Esta ação é irreversível. Os dados da resposta não podem ser recuperados após a exclusão.

Parâmetros de caminho

idstringobrigatório

O ID do formulário

responseIdstringobrigatório

O ID da resposta

Resposta

json

{
  "success": true
}

Exemplos de código

bash

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

Excluir respostas em massa

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

Exclui várias respostas em uma única requisição. Máximo de 100 respostas por requisição. Todos os IDs de resposta especificados devem pertencer ao formulário indicado.

Parâmetros de caminho

idstringobrigatório

O ID do formulário

Corpo da requisição

response_idsarray of stringsobrigatório

IDs das respostas a excluir (máx. 100)

Exemplo de requisição

json

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

Resposta

json

{
  "deleted": 3
}

Exemplos de código

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

Exporta todas as respostas de um formulário como arquivo CSV. O CSV inclui colunas para responseId, submittedAt, completedAt e uma coluna por pergunta (usando o título da pergunta como cabeçalho da coluna).

Para perguntas de grupo (question_group, multi_question_page, contact_info, address), cada subcampo recebe sua própria coluna.

Parâmetros de caminho

idstringobrigatório

O ID do formulário

Resposta

Retorna um arquivo CSV com 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,

Exemplos de código

bash

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

Respostas de erro

Todos os endpoints retornam respostas de erro padrão:

Códigos de status

400Bad Request

Parâmetros inválidos, exclusão em massa excede 100 itens

401Unauthorized

Chave de API ausente ou inválida

403Forbidden

Permissões de equipe insuficientes

404Not Found

Formulário ou resposta não encontrado

500Internal Server Error

Erro interno do servidor

Exemplo de erro

json

{
  "error": "Response not found"
}

Última atualização: 20 de julho de 2026