API de Formulários

Crie, recupere, atualize, exclua, publique e duplique formulários.

A API de Formulários permite gerenciar seus formulários NueForm de forma programática. Você pode listar, criar, recuperar, atualizar, excluir, publicar, despublicar e duplicar formulários.

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

Listar Formulários

GET/api/v1/forms

Retorna uma lista paginada de formulários aos quais o usuário autenticado tem acesso, incluindo formulários pessoais e formulários de equipes às quais o usuário pertence.

Parâmetros de Consulta

pageinteger

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

per_pageinteger

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

searchstring

Filtra formulários por título (correspondência parcial sem diferenciar maiúsculas de minúsculas)

team_idstring

Retorna apenas formulários pertencentes a esta equipe

publishedboolean

Filtra pelo status de publicação (true ou false)

Resposta

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
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/forms?page=1&per_page=10&published=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Criar Formulário

POST/api/v1/forms

Cria um novo formulário. Opcionalmente, você pode incluir um array de perguntas para criar junto com o formulário.

Corpo da Requisição

titlestring

Título do formulário (não pode ficar em branco)

descriptionstring

Descrição do formulário

team_idstring

Atribui o formulário a uma equipe (requer a permissão create_forms)

publishedboolean

Se o formulário está publicado (padrão: false)

theme_colorstring

Cor primária do tema (hex, padrão: #6366f1)

background_colorstring

Cor de fundo (hex, padrão: #0a0a0a)

text_colorstring

Cor do texto da pergunta (hex)

answer_text_colorstring

Cor do texto do campo de resposta (hex)

placeholder_colorstring

Cor do placeholder do campo (hex)

button_colorstring

Cor de fundo do botão (hex)

button_text_colorstring

Cor do texto do botão (hex)

title_colorstring

Cor do texto do título (hex)

description_colorstring

Cor do texto da descrição (hex)

option_text_colorstring

Cor do texto das opções de escolha (hex)

indicator_bg_colorstring

Cor de fundo do indicador de etapa (hex)

indicator_text_colorstring

Cor do texto do indicador de etapa (hex)

font_familystring

Família de fonte da pergunta

font_family_answerstring

Família de fonte do campo de resposta

font_family_buttonstring

Família de fonte do botão

font_family_descriptionstring

Família de fonte da descrição

font_family_optionstring

Família de fonte das opções de escolha

font_family_indicatorstring

Família de fonte do indicador de etapa

question_font_sizestring

Tamanho da fonte da pergunta (por exemplo, "24px")

custom_cssstring

CSS personalizado injetado no renderizador do formulário

show_progress_barboolean

Exibe uma barra de progresso (padrão: true)

branding_logo_urlstring

URL do logotipo da marca

branding_footer_textstring

Texto personalizado do rodapé

hide_brandingboolean

Oculta a marca NueForm (padrão: false)

top_logo_urlstring

URL de um logotipo exibido no topo do formulário

top_logo_sizestring

Tamanho do logotipo do topo (por exemplo, "120px")

top_logo_alignmentstring

Alinhamento do logotipo do topo ("left", "center", "right")

top_logo_cssstring

CSS personalizado para o logotipo do topo

watermark_cssstring

CSS personalizado para a marca d'água

welcome_titlestring

Título da tela de boas-vindas

welcome_descriptionstring

Descrição da tela de boas-vindas

welcome_button_textstring

Texto do botão da tela de boas-vindas (padrão: "Start")

thank_you_titlestring

Título da tela de agradecimento (padrão: "Thank you!")

thank_you_descriptionstring

Descrição da tela de agradecimento

modestring

Modo do formulário: "standard", "knowledge_quiz", "lead_qualification", "match_quiz" (padrão: "standard")

quiz_settingsobject

Configuração do questionário (para modos de questionário)

variablesobject

Variáveis no nível do formulário para lógica

start_logic_jumpsarray

Regras de saltos de lógica aplicadas no início do formulário

webhook_urlstring

URL para receber POST no envio (requer plano Pro)

limit_one_responseboolean

Limita a uma resposta por visitante (padrão: false)

incremental_submissionboolean

Salva as respostas de forma incremental conforme o respondente avança (padrão: false)

questionsarray

Array de objetos de pergunta a criar (veja abaixo)

Exemplo de Requisição

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

Resposta

Retorna o objeto do formulário criado com todas as perguntas:

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": {}
    }
  ]
}

Exemplos de Código

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

Obter Formulário

GET/api/v1/forms/:id

Recupera um único formulário pelo ID, incluindo todas as perguntas ordenadas pela posição.

Parâmetros de Caminho

idstring

O ID do formulário

Resposta

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": {}
    }
  ]
}

Exemplos de Código

bash

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

Atualizar Formulário

PUT/api/v1/forms/:id

Atualiza os campos de um formulário e sincroniza suas perguntas. Quando você inclui um array questions, o NueForm irá:

Atualizar perguntas existentes (correspondidas pelo id)
Criar novas perguntas (sem id ou com id não reconhecido)
Excluir perguntas que existem no formulário mas não estão presentes no array

Se o formulário estiver publicado no momento, a flag has_unpublished_changes é definida automaticamente como true.

Parâmetros de Caminho

idstring

O ID do formulário

Corpo da Requisição

Aceita todos os campos de Criar Formulário, exceto team_id. Inclua apenas os campos que você deseja alterar.

Exemplo de Requisição

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

Resposta

Retorna o objeto do formulário atualizado com todas as perguntas (mesmo esquema de Obter Formulário).

Exemplos de Código

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

Exclui permanentemente um formulário e todos os dados associados, incluindo perguntas, respostas, versões e entradas do registro de alterações. Os uploads de arquivo associados são limpos de forma assíncrona.

Esta ação é irreversível. Todas as respostas coletadas para este formulário serão excluídas permanentemente.

Parâmetros de Caminho

idstring

O ID do formulário

Resposta

json

{
  "success": true
}

Exemplos de Código

bash

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

Publicar Formulário

POST/api/v1/forms/:id/publish

Publica um formulário criando um snapshot versionado do formulário atual e de suas perguntas. Cada publicação incrementa o número da versão. O formulário se torna acessível publicamente em sua URL compartilhável.

Parâmetros de Caminho

idstring

O ID do formulário

Resposta

Retorna o objeto do formulário com um campo published_version indicando o novo número da versão:

json

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

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Despublicar Formulário

DELETE/api/v1/forms/:id/publish

Despublica um formulário, tornando-o inacessível em sua URL pública. O snapshot da versão publicada é mantido para que você possa publicar novamente mais tarde.

Parâmetros de Caminho

idstring

O ID do formulário

Resposta

Retorna o objeto do formulário atualizado com published definido como false.

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "published": false,
  "questions": [ ... ]
}

Exemplos de Código

bash

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

Duplicar Formulário

POST/api/v1/forms/:id/duplicate

Cria uma cópia de um formulário existente, incluindo todas as perguntas. As referências de saltos de lógica são remapeadas automaticamente para os novos IDs de pergunta. O formulário duplicado é sempre criado em estado não publicado.

Parâmetros de Caminho

idstring

O ID do formulário a duplicar

Corpo da Requisição

titlestring

Título do novo formulário (padrão: "Original Title (Copy)")

team_idstring

Atribui a cópia a uma equipe diferente

Exemplo de Requisição

json

{
  "title": "Customer Feedback Survey v2",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f"
}

Resposta

Retorna o objeto do formulário recém-criado (mesmo esquema de Obter Formulário) com published definido como false.

Exemplos de Código

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

Respostas de Erro

Todos os endpoints retornam respostas de erro padrão.

Códigos de Erro

400Bad Request

Erro de validação ou campo obrigatório ausente

401Unauthorized

Chave de API ausente ou inválida

403Forbidden

Permissões insuficientes para formulários de equipe

404Not Found

Formulário não encontrado

500Server Error

Erro interno do servidor

Exemplo de Erro

json

{
  "error": "Title is required"
}

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