NueForm

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

Defina como true para publicar o formulário logo depois de criá-lo. A publicação executa as mesmas verificações de Publicar Formulário. Se alguma verificação falhar, o formulário é criado mesmo assim como rascunho: a resposta é 201 com published: false e um objeto publish_error (reason, message, question_ids, upgrade_required). Não crie o formulário de novo — corrija o problema e depois chame Publicar Formulário. Padrão: false (rascunho)

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)

auto_translateboolean

NueLingo — traduz o formulário publicado sob demanda para qualquer idioma suportado para os respondentes (Pro+; salvo como false em outros planos). Requer um idioma padrão; entra em vigor ao publicar.

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,
  "auto_translate": 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: suas alterações são salvas como rascunho, e os respondentes continuam vendo a versão publicada até você publicar de novo.

published muda o estado do formulário em vez de ser salvo como um campo:

  • Em um formulário em rascunho, published: true o publica depois de salvar suas alterações, com as mesmas verificações de Publicar Formulário. Se alguma verificação falhar, suas alterações são salvas mesmo assim e a API retorna 409 Conflict com form_id e saved_as_draft: true.
  • Em um formulário que já está no ar, published: true não muda nada — chame Publicar Formulário para colocar suas alterações no ar.
  • published: false tira do ar um formulário publicado, assim como Despublicar Formulário.

Em formulários de equipe, só administradores e proprietários da equipe podem alterar published.

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

Excluir Formulário

DELETE/api/v1/forms/:id

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

Parâmetros de Consulta

delete_signed_contractsboolean

Deve ser true para excluir um formulário que tem contratos assinados concluídos. Eles são excluídos permanentemente com o formulário, incluindo os PDFs assinados e as trilhas de auditoria. Sem ele, esse formulário não é excluído: a API responde 409 com reason: form_has_signed_contracts e signed_contracts (quantos são).

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 — o mesmo processo do botão Publicar do editor. Cada publicação incrementa o número da versão, e o formulário se torna acessível publicamente em sua URL compartilhável.

Antes de publicar qualquer coisa, o NueForm verifica se:

  • formulários de equipe são publicados apenas por administradores e proprietários da equipe, e formulários pessoais apenas pelo dono (qualquer outra pessoa recebe 403 Forbidden, ou 404 Not Found se não for membro da equipe do formulário);
  • os recursos Pro (perguntas de agendamento, contratos com assinatura eletrônica, nós de dados, webhooks de formulário e pagamentos na sua própria conta Stripe) estão incluídos no plano do dono do formulário (o plano do proprietário da equipe em formulários de equipe);
  • as perguntas de agendamento, as etapas de e-mail, as perguntas Fuse e os composites estão totalmente configurados.

Se alguma verificação falhar, o formulário não é publicado e a API retorna 409 Conflict com um código reason e os question_ids a corrigir (veja Tratamento de erros). As respostas de sucesso incluem published_version e um array warnings com avisos que não bloqueiam a publicação.

Parâmetros de Caminho

idstring

O ID do formulário

Resposta

Retorna o formulário publicado com published_version (o novo número da versão) e warnings (avisos que não bloqueiam a publicação; geralmente vazio):

json
{
  "data": {
    "id": "665a1b2c3d4e5f6a7b8c9d0e",
    "title": "Customer Feedback Survey",
    "slug": "a1b2c3d4e5f6",
    "published": true,
    "has_unpublished_changes": false,
    "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
    "published_version": 3,
    "warnings": [
      {
        "code": "booking_attendee_ask",
        "question_id": "66a1b2c3d4e5f6a7b8c9d004",
        "question_title": "Book a demo",
        "message": "Booking question \"Book a demo\" has no attendee email mapping, so respondents will be asked for their email when they book."
      }
    ],
    "questions": [ ... ]
  }
}

Publicação bloqueada (409)

Nada é publicado. reason indica qual verificação falhou e question_ids lista as perguntas a corrigir; upgrade_required é true quando o plano do dono do formulário precisa de upgrade:

json
{
  "error": {
    "code": "CONFLICT",
    "message": "E-signature contracts need a Pro plan to go live. Upgrade to publish this form, or remove the contract question.",
    "status": 409,
    "reason": "contract_requires_pro",
    "question_ids": ["66a1b2c3d4e5f6a7b8c9d001"],
    "upgrade_required": true
  }
}

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. Formulários de equipe só podem ser despublicados por administradores e proprietários da equipe, e formulários pessoais pelo dono; qualquer outra pessoa recebe 403 Forbidden, ou 404 Not Found se não for membro da equipe do formulário.

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

409Conflict

Publicação bloqueada: uma verificação de publicação falhou (veja Publicar Formulário)

500Server Error

Erro interno do servidor

Exemplo de Erro

json
{
  "error": "Title is required"
}
Última atualização: 30 de outubro de 2026