Pesquisas

Gerencie pesquisas, trabalhe com variáveis ocultas e configurações

Visão geral

A API de Pesquisas/Questionários permite criar pesquisas programaticamente, gerenciar perguntas, configurar ajustes, lidar com variáveis ocultas, controlar o ciclo de vida da pesquisa (duplicar, renomear, arquivar, excluir) e gerenciar os textos de rótulos padrão.

Navegação rápida

Visão geral Criar e editar Lista de pesquisas Dados da pesquisa Configurações da pesquisa Perguntas da pesquisa Variáveis URL ocultas Gerenciamento de pesquisas Pesquisas arquivadas

Baixe a versão em markdown da seção "Pesquisas" para usar no ChatGPT / outros LLMs:

AI Markdown

/static/api/quizzes.md

AI Markdown

Criar e editar

Esta seção abrange a criação de uma nova pesquisa e o salvamento de suas perguntas.

Criar pesquisa

POST /quiz

Cria uma nova pesquisa na pasta especificada e retorna o objeto da pesquisa.

Corpo da requisição (JSON)

Campo	Tipo	Obrigatório	Descrição
folder_id	integer	Sim	ID da pasta em que criar a pesquisa

Exemplo de requisição

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"folder_id": 5}'

Resposta bem-sucedida (201)

Campos principais

{ "id": 124, "workspace_id": 1, "name": "Survey #12", "virtual_id": "abc12xyz", "url_preview": "https://example.com/quiz/124/preview", "url_shared": "https://example.com/q/abc12xyz", "is_published": false }

Possíveis erros

HTTP	Código	Descrição
400	`workspace_not_found`, `folder_not_found`	Espaço de trabalho ou pasta não encontrado
401	`user_not_authenticated`	Token de autorização inválido ou ausente
403	`quiz_limit_today`	Limite diário de criação de pesquisas atingido para esta conta
422	`validation_error`	Erro de validação do corpo da requisição

Perguntas da pesquisa

Salve o conjunto completo de perguntas de uma pesquisa usando o endpoint /quiz/{id}/save.

POST /quiz/{id}/save

Salva a estrutura completa de perguntas da pesquisa. Substitui o conjunto de perguntas existente.

Corpo da requisição (JSON)

Campo	Tipo	Obrigatório	Descrição
ids	array	Sim	Array ordenado de identificadores de perguntas (UUIDs, "welcome", "submit")
entities	object	Sim	Objeto que mapeia cada ID de pergunta para seu objeto de dados completo

Valores de ids

O array ids contém identificadores de perguntas na ordem de exibição. Valores especiais:

Valor	Descrição
welcome	Tela de boas-vindas (página de introdução)
submit	Tela de conclusão (página de agradecimento)
UUID	UUID — uma pergunta regular

Campos comuns para todos os tipos de pergunta

Campo	Tipo	Descrição
type	string	Obrigatório. Identificador do tipo de pergunta (veja a tabela de tipos)
title	string	Título / texto do rótulo da pergunta
withTitle	boolean	Exibir o campo de título
description	string	Texto de descrição / subtítulo da pergunta
withDescription	boolean	Exibir o campo de descrição
isRequired	boolean	Tornar a pergunta obrigatória
isBlocked	boolean	Bloquear a pergunta (ocultar dos respondentes)
multimedia	object \\| null	Objeto multimídia (imagem, vídeo, áudio) ou null
filling_time_enabled	boolean	Habilitar limite de tempo por pergunta
filling_time_seconds	integer	Limite de tempo para a pergunta em segundos

Tipos de pergunta

type	Nome	Descrição
welcome	Tela de boas-vindas	Tela de introdução / boas-vindas
yesno	Sim / Não	Pergunta de Sim / Não
choice	Escolha	Seleção única ou múltipla de uma lista de opções
dropdown	Lista suspensa	Seleção de lista suspensa
ranking	Classificação	Classificação de opções por arrastar e soltar
slider	Controle deslizante	Controle deslizante com mín./máx./passo configuráveis
rating	Avaliação	Escala de avaliação com estrelas, corações ou emojis
scale	Escala	Escala numérica (ex.: 1–10)
input	Entrada de texto	Entrada de texto curto ou longo
email	E-mail	Campo de entrada de endereço de e-mail
phone	Telefone	Campo de entrada de número de telefone
datetime	Data e hora	Seletor de data e/ou hora
matrix	Matriz	Grade de matriz (linhas × colunas)
message	Mensagem	Bloco de mensagem estática ou informação
file	Upload de arquivo	Upload de arquivo
html	Bloco HTML	Bloco de conteúdo HTML personalizado
submit	Tela de envio	Tela de conclusão / agradecimento

Estrutura do objeto multimídia

Campo	Descrição
type	img, video, audio
imgUrl	URL da imagem
videoUrl	URL do vídeo
imgLocation	Posição da imagem: top, left, right, background
videoSettings	Objeto de configurações do player de vídeo

Campos adicionais por tipo de pergunta

welcome (welcome screen): welcomeLabel, welcomeWithResponseTime, welcomeWithQuestionCount

submit (completion screen): submitLabel, submitShowText, submitNextUrl, submitTerms, submitTermsTitle, submitTermsText

choice: choiceType (text/image), choiceMultiple, choiceRandomize, choiceTextOther; choiceTextIds + choiceTextEntities (UUID → {label, score, isCorrect}); choiceImageIds + choiceImageEntities

yesno: yesNoTextIds, yesNoTextEntities (UUID → {type: yes|no, label, score, isCorrect})

dropdown: dropdownIds, dropdownEntities (UUID → text), dropdownScores

ranking: rankingIds, rankingEntities, rankingRandomize, swapActive

slider: sliderMin, sliderMax, sliderStep, sliderValue

rating: ratingCount, ratingFigure (star/heart/thumb/smile), ratingValue, ratingWithNumber, ratingScores

scale: scaleCount, scaleStartValue (0/1), scaleLabelLeft/Central/Right, scaleLabelLeftValue, scaleLabelCentralValue, scaleLabelRightValue, scaleScores

input (text): inputPlaceholder, inputIsTextarea, inputWidth, inputHeight, inputLimit, inputLimitMin, inputLimitMax

email: emailPlaceholder, emailWidth

phone: phonePlaceholder, phoneWidth, phoneIsLimit, phoneLimitMin, phoneLimitMax

datetime: dateTimeType (dateAndTime/date/time), dateTimeFormatOfDate, dateTimeFormatOfTime (12/24), dateTimeSeparator (dot/slash/dash)

matrix: matrixChoiceType (radio/checkbox/text), matrixIsAllRequired, matrixRowIds, matrixColIds, matrixRowEntities, matrixColEntities, matrixTranspose

message: messageLabel, messageWithButton

html: htmlCode, htmlIsEmbedded

Regras de validação

Todos os valores em ids devem ser únicos
Cada valor em ids deve ter uma entrada correspondente em entities
Cada chave em entities deve estar presente em ids
Cada objeto de entidade deve ter um campo type

Exemplo: adicionar uma pergunta de avaliação

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/save" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ids": ["welcome", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "submit"], "entities": { "welcome": { "type": "welcome", "title": "Welcome", "welcomeLabel": "Start" }, "a1b2c3d4-e5f6-7890-abcd-ef1234567890": { "type": "rating", "title": "Rate the service", "ratingCount": 5, "ratingFigure": "star" }, "submit": { "type": "submit", "submitLabel": "Submit" } } }'

Erros

HTTP	Descrição
400	Pesquisa não encontrada
401	Autorização necessária
403	Acesso à pesquisa negado
422	Erro de validação: ids e entities são inconsistentes
500	Erro interno do servidor ao salvar a estrutura da pesquisa

Obter lista de pesquisas

GET /quiz

Retorna uma lista paginada de todas as pesquisas ativas (não arquivadas).

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
sort	string	Não	Campo pelo qual ordenar (ex.: name, created_at)
order	string	Não	Direção de ordenação: asc ou desc
limit	integer	Não	Número máximo de pesquisas a retornar
offset	integer	Não	Número de pesquisas a ignorar (deslocamento de paginação)

Exemplo de requisição

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz?sort=name&order=asc&limit=10&offset=0" \ -H "Authorization: Bearer YOUR_TOKEN"

Resposta da API

[ { "id": "survey ID", "name": "name", "url_shared": "survey URL", "is_published": true, "folder": { "id": 384, "workspace_id": 384, "user_id": 12, "name": "My Surveys", "pos": 1, "is_default": true, "created_at": "2022-04-01T08:37:14.000000Z", "updated_at": "2022-04-27T15:46:27.000000Z", "deleted_at": null } } ]

Obter dados da pesquisa

GET /quiz/{id}

Retorna o objeto de dados completo de uma pesquisa específica, incluindo todas as perguntas e configurações.

Exemplo de requisição

curl -X GET https://api.surveyninja.io/api/v3/service/quiz/123 \ -H "Authorization: Bearer YOUR_TOKEN"

Resposta da API

{ "id": "survey ID", "answer_count": "number of responses", "name": "name", "url_shared": "survey URL", "widgets": "question structure (ids, entities)", "hidden_options": "hidden variable", "folder": { "id": 384, "workspace_id": 384, "user_id": 12, "name": "My Surveys", "pos": 1, "is_default": true, "created_at": "2022-04-01T08:37:14.000000Z", "updated_at": "2022-04-27T15:46:27.000000Z", "deleted_at": null } }

Configurações da pesquisa

Atualiza um ou mais grupos de configuração de uma pesquisa. Todos os parâmetros são opcionais — apenas os campos enviados serão atualizados.

POST /quiz/{id}/settings/info

Básico

Parâmetro	Tipo	Descrição
name	string	Nome / título da pesquisa
lang	string	Código de idioma da interface da pesquisa (ex.: en, ru)
info_title	string	Título interno da pesquisa (exibido no painel)
description	string	Meta descrição SEO para a página da pesquisa

Exibição

Parâmetro	Tipo	Descrição
show_progressbar	boolean	Exibir barra de progresso
show_navigate	boolean	Exibir botões de navegação (Voltar / Próximo)
numeration	boolean	Exibir numeração das perguntas
auto_move_by_enter	boolean	Avançar automaticamente para a próxima pergunta ao pressionar Enter
show_by_one	boolean	Exibir uma pergunta por vez
allow_multiple_answer	boolean	Permitir múltiplos envios do mesmo respondente
show_copyright	boolean	Exibir o rodapé de direitos autorais do SurveyNinja

Acesso e restrições

Parâmetro	Tipo	Descrição
close_quiz_enabled	boolean	Fechar a pesquisa (parar de aceitar respostas)
limit_time_enabled	boolean	Habilitar prazo de resposta
limit_time_value	string	Prazo de resposta (string de data e hora)
limit_time_timezone	string	Fuso horário para o prazo de resposta (ex.: America/Sao_Paulo)
limit_answer_count_enabled	boolean	Limitar o número total de respostas
limit_answer_count_value	integer	Maximum number of responses
use_password	boolean	Proteger a pesquisa com senha
multiple_ip	boolean	Permitir múltiplas respostas do mesmo endereço IP
show_captcha	boolean	Exibir CAPTCHA antes do envio
ip_list_enabled	boolean	Habilitar filtragem por endereço IP
ip_whitelist	string	Lista de endereços IP permitidos separados por vírgula
ip_blacklist	string	Lista de endereços IP bloqueados separados por vírgula
available_devices[]	array	Dispositivos permitidos: desktop, mobile, tablet

Comportamento

Parâmetro	Tipo	Descrição
scoring_switcher	boolean	Habilitar modo de pontuação
question_required_mode	string	`individual` / `all_required` / `all_optional`
question_random_order	boolean	Aleatorizar a ordem das perguntas
disable_auto_redirect	boolean	Desabilitar redirecionamento automático após o envio
block_jump_to_prev_widget	boolean	Impedir que os respondentes voltem às perguntas anteriores
filling_time_enabled	boolean	Habilitar limite de tempo total da pesquisa
filling_time_seconds	integer	Limite de tempo da pesquisa em segundos

Análises e código QR

Parâmetro	Tipo	Descrição
scripts_in_head	string	Scripts personalizados inseridos no
scripts_in_body	string	Scripts personalizados inseridos antes de
scripts_in_head_enabled	boolean	Habilitar scripts no head
scripts_in_body_enabled	boolean	Habilitar scripts no body
sso_active	boolean	Habilitar Single Sign-On (SSO)
qr_code_size	integer	Tamanho do código QR em pixels
qr_code_color	string	Cor de primeiro plano do código QR (HEX)
qr_code_background_color	string	Cor de fundo do código QR (HEX)
qr_code_margin	integer	Margem do código QR em pixels

POST /api/v3/service/quiz/{id}/settings/info

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/settings/info" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "New survey name", "lang": "en", "show_progressbar": true, "limit_answer_count_enabled": true, "limit_answer_count_value": 500, "question_required_mode": "all_required" }'

Variáveis ocultas

Obter variáveis ocultas

GET /quiz/{id}/hidden/options

Retorna a lista de variáveis ocultas configuradas para a pesquisa.

Exemplo de requisição

curl -X GET https://api.surveyninja.io/api/v3/service/quiz/123/hidden/options \ -H "Authorization: Bearer YOUR_TOKEN"

Criar variável oculta

POST /quiz/{id}/hidden/options/create

Cria uma nova variável oculta para a pesquisa.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da variável
value	string	Sim	Valor padrão da variável

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/hidden/options/create \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "productType", "value": "clientShop" }'

Atualizar variável oculta

POST /quiz/{id}/hidden/options/update/{opt_id}

Atualiza o nome e o valor padrão de uma variável oculta.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Novo nome da variável
value	string	Sim	Novo valor da variável

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/hidden/options/update/123 \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "productType", "value": "updatedValue" }'

Excluir variável oculta

POST /quiz/{id}/hidden/options/delete/{opt_id}

Exclui uma variável oculta da pesquisa.

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/hidden/options/delete/123 \ -H "Authorization: Bearer YOUR_TOKEN"

Variáveis ocultas em perguntas

Obter variáveis ocultas em perguntas

GET /quiz/{id}/widgets/hidden/options

Retorna a lista de variáveis ocultas incorporadas nas perguntas da pesquisa.

Exemplo de requisição

curl -X GET https://api.surveyninja.io/api/v3/service/quiz/123/widgets/hidden/options \ -H "Authorization: Bearer YOUR_TOKEN"

Adicionar variável oculta à pergunta

POST /quiz/{id}/widgets/hidden/options/create

Adiciona uma variável oculta a uma pergunta específica.

Parâmetro	Tipo	Descrição	Obrigatório
name	string	Nome da variável	Sim
value	string	Valor padrão da variável	Sim
widget_uuid	string	UUID da pergunta (widget) à qual anexar a variável	Sim

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/widgets/hidden/options/create \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "productType", "value": "clientShop", "widget_uuid": "c63b9a88-2f1b-4735-a7ab-0b5fd84c90c2" }'

Atualizar variável oculta na pergunta

POST /quiz/{id}/widgets/hidden/options/update/{opt_id}

Atualiza o nome e o valor de uma variável oculta anexada a uma pergunta.

Parâmetro	Tipo	Descrição	Obrigatório
name	string	Novo nome da variável	Sim
value	string	Novo valor da variável	Sim

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/widgets/hidden/options/update/123 \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "productType", "value": "clientShop" }'

Excluir variável oculta da pergunta

POST /quiz/{id}/widgets/hidden/options/delete/{opt_id}

Remove uma variável oculta de uma pergunta específica.

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/widgets/hidden/options/delete/123 \ -H "Authorization: Bearer YOUR_TOKEN"

Gerenciamento de pesquisas

Os seguintes endpoints permitem gerenciar o ciclo de vida das pesquisas: adicionar notas, duplicar, renomear, converter em modelo, arquivar, mover e excluir.

Ciclo de vida da pesquisa

POST /quiz/{id}/save

Salva a estrutura completa de perguntas da pesquisa (substitui as perguntas existentes).

Exemplo de requisição

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/save" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ids": ["welcome", "question-1", "submit"], "entities": { "welcome": { "type": "welcome", "...": "..." }, "question-1": { "type": "choice", "title": "...", "...": "..." }, "submit": { "type": "submit", "...": "..." } } }'

POST /quiz/{id}/applyTheme/{theme_id}

Aplica um tema de design à pesquisa.

Exemplo de requisição

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/applyTheme/925" \ -H "Authorization: Bearer YOUR_API_TOKEN"

POST /quiz/{id}/publish

Publica o rascunho atual da pesquisa para que os respondentes possam acessá-la.

Exemplo de requisição

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/publish" \ -H "Authorization: Bearer YOUR_API_TOKEN"

POST /quiz/{id}/conditions

Salva a lógica de ramificação (condições de pulo/desvio) para a pesquisa.

Exemplo de requisição

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/conditions" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "conditions": { "...": "logic structure, same as in the builder" } }'

Adicionar nota

POST /quiz/{id}/note

Adiciona ou atualiza uma nota (comentário interno) anexada à pesquisa.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
notes	string	Sim	Texto da nota (máximo 1000 caracteres)

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/note \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "notes": "Note text (maximum 1000 characters)" }'

Resposta da API

{ "status": true, "notes": "Note text" }

Duplicar pesquisa

POST /quiz/{id}/duplicate

Cria uma cópia completa da pesquisa, incluindo todas as perguntas e configurações.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Não	Nome para a pesquisa duplicada (opcional; padrão é uma cópia do nome original)

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/duplicate \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Copy name (optional)" }'

Resposta da API

{ "status": true, "quiz": { "id": 123, "name": "Copy: Survey Name", "url_shared": "https://example.com/abc123", "is_published": false, "created_at": "2024-01-01T12:00:00Z", "updated_at": "2024-01-01T12:00:00Z", "folder": { "id": 1, "name": "My Folder" } } }

Renomear pesquisa

POST /quiz/{id}/rename

Renomeia a pesquisa.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Novo nome da pesquisa

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/rename \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "New survey name" }'

Resposta da API

{ "status": true, "name": "New survey name" }

Converter em modelo

POST /quiz/{id}/template

Marca a pesquisa como um modelo reutilizável disponível na galeria de modelos.

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/template \ -H "Authorization: Bearer YOUR_TOKEN"

Resposta da API

{ "status": true }

Arquivar pesquisa

POST /quiz/{id}/archive

Arquiva ou desarquiva uma pesquisa. Pesquisas arquivadas não aceitam novas respostas.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
archive	boolean	Sim	true — arquivar a pesquisa, false — desarquivar

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/archive \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "archive": true }'

Resposta da API

{ "status": true, "archive_at": "2024-01-01T12:00:00Z", "is_archived": true }

Mover pesquisa

POST /quiz/{id}/move

Move a pesquisa para uma pasta diferente dentro do mesmo espaço de trabalho.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
folder_id	integer	Sim	ID da pasta de destino

Exemplo de requisição

curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/move \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "folder_id": 5 }'

Resposta da API

{ "status": true, "folder_id": 5, "folder": { "id": 5, "name": "New Folder" } }

Excluir pesquisa

DELETE /quiz/{id}

Exclui permanentemente uma pesquisa junto com todas as suas respostas. Esta ação não pode ser desfeita.

Exemplo de requisição

curl -X DELETE https://api.surveyninja.io/api/v3/service/quiz/123 \ -H "Authorization: Bearer YOUR_TOKEN"

Resposta da API

{ "status": true }

Pesquisas arquivadas

GET /quiz/archived

Retorna a lista de pesquisas arquivadas.

Exemplo de requisição

curl -X GET https://api.surveyninja.io/api/v3/service/quiz/archived \ -H "Authorization: Bearer YOUR_TOKEN"

Resposta da API

[ { "id": 123, "name": "Archived survey", "url_shared": "https://example.com/abc123", "is_published": false, "created_at": "2024-01-01T12:00:00Z", "updated_at": "2024-01-01T12:00:00Z", "archive_at": "2024-01-02T12:00:00Z", "folder": { "id": 1, "name": "My Folder" } } ]

Variáveis URL ocultas

As variáveis URL ocultas são adicionadas ao link da pesquisa como parâmetros de consulta e capturadas automaticamente quando um respondente abre a pesquisa.

Listar variáveis URL ocultas GET /api/v3/service/quiz/{id}/hidden/variables

Retorna a lista de variáveis URL ocultas configuradas para a pesquisa.

GET /api/v3/service/quiz/{id}/hidden/variables

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/hidden/variables" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"

Response example:

[ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "utm_source" }, { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "user_id" } ]

Criar variável URL oculta POST /api/v3/service/quiz/{id}/hidden/variables/create

Parâmetro	Obrigatório	Descrição
name	yes	Nome da variável usado como chave do parâmetro de consulta
id	no	UUID personalizado para a variável (gerado automaticamente se não fornecido)

Erros: 422 se o nome já existe ou é inválido; 400 se a pesquisa não for encontrada.

POST /api/v3/service/quiz/{id}/hidden/variables/create

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/hidden/variables/create" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "utm_source" }'

Atualizar variável URL oculta POST /api/v3/service/quiz/{id}/hidden/variables/update/{field_id}

Parâmetro	Obrigatório	Descrição
name	yes	Novo nome da variável

POST /api/v3/service/quiz/{id}/hidden/variables/update/{field_id}

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/hidden/variables/update/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "utm_campaign" }'

Excluir variável URL oculta POST /api/v3/service/quiz/{id}/hidden/variables/delete/{field_id}

Nenhum corpo de requisição necessário.

POST /api/v3/service/quiz/{id}/hidden/variables/delete/{field_id}

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/hidden/variables/delete/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"

Textos padrão

Os textos padrão são os botões e rótulos de interface mostrados aos respondentes (ex.: Próximo, Voltar, Enviar). Recupere os valores atuais e personalize-os por pesquisa.

Obter textos padrão GET /api/v3/service/quiz/{id}/default-texts

Parâmetro	Tipo	Padrão	Descrição
lang	string	ru	Código de idioma para o qual recuperar os rótulos (ex.: ru, en)

Retorna um array de objetos de rótulo, cada um com code, standard_text e user_text (personalização ou null).

GET /api/v3/service/quiz/{id}/default-texts

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/default-texts?lang=ru" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"

Exemplo de resposta

[ { "code": "btn_next", "standard_text": "Next", "user_text": null }, { "code": "btn_back", "standard_text": "Back", "user_text": "Go Back" }, { "code": "btn_submit", "standard_text": "Submit", "user_text": null } ]

Atualizar textos padrão POST /api/v3/service/quiz/{id}/default-texts

Atualiza os textos de rótulos personalizados para a pesquisa. Envie text: null para redefinir ao texto padrão.

Parâmetro	Tipo	Descrição
texts[]	array	Array de objetos com os campos code e text
texts[].code	string	Código do rótulo da resposta GET
texts[].text	string\|null	Novo texto; null redefine para o valor padrão

Erro 400 blocked_by_tariff — o recurso não está disponível no plano atual.

POST /api/v3/service/quiz/{id}/default-texts

curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/default-texts" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "texts": [ { "code": "btn_next", "text": "Forward" }, { "code": "btn_back", "text": null } ] }'

Seção anterior

Próxima seção