Documentação da API

A API REST do FormGuru permite criar formulários, gerenciar perguntas e respostas, configurar webhooks e muito mais de forma programática.

v1https://formguru.com.br/api/v1

1. Autenticação

Todas as requisições autenticadas devem incluir um cabeçalho Authorization com seu API Key no formato Bearer <chave>.

Suas chaves de API são gerenciadas em Configurações → API no painel do FormGuru. Nunca compartilhe suas chaves secretas em código público.

curl https://formguru.com.br/api/v1/forms \
  -H "Authorization: Bearer sk_live_xxx"

Atenção: Chaves prefixadas com sk_live_ afetam dados reais. Use ambientes de teste durante o desenvolvimento.

2. Formulários

Endpoints para criar, listar, atualizar, excluir e controlar o estado de publicação dos seus formulários.

GEThttps://formguru.com.br/api/v1/formsforms:read

Lista todos os formulários da organização. O resultado é paginado.

Exemplo

curl "https://formguru.com.br/api/v1/forms?page=1&limit=20" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "data": [
    {
      "id": "form_abc123",
      "title": "Pesquisa de Satisfação",
      "status": "published",
      "responses_count": 42,
      "created_at": "2025-01-10T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

POSThttps://formguru.com.br/api/v1/formsforms:write

Cria um novo formulário. O formulário é criado como rascunho.

Exemplo

curl -X POST "https://formguru.com.br/api/v1/forms" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Meu Novo Formulário" }'

Resposta

{
  "id": "form_xyz789",
  "title": "Meu Novo Formulário",
  "status": "draft",
  "created_at": "2025-04-15T10:00:00Z"
}

GEThttps://formguru.com.br/api/v1/forms/:idforms:read

Retorna os detalhes completos de um formulário específico.

Exemplo

curl "https://formguru.com.br/api/v1/forms/form_abc123" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "id": "form_abc123",
  "title": "Pesquisa de Satisfação",
  "status": "published",
  "questions_count": 5,
  "responses_count": 42,
  "created_at": "2025-01-10T14:00:00Z",
  "updated_at": "2025-03-01T09:30:00Z"
}

PATCHhttps://formguru.com.br/api/v1/forms/:idforms:write

Atualiza os campos de um formulário. Apenas os campos enviados serão alterados.

Exemplo

curl -X PATCH "https://formguru.com.br/api/v1/forms/form_abc123" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Pesquisa de Satisfação 2025" }'

Resposta

{
  "id": "form_abc123",
  "title": "Pesquisa de Satisfação 2025",
  "status": "published",
  "updated_at": "2025-04-15T12:00:00Z"
}

DELETEhttps://formguru.com.br/api/v1/forms/:idforms:write

Exclui permanentemente um formulário e todos os seus dados. Esta ação é irreversível.

Exemplo

curl -X DELETE "https://formguru.com.br/api/v1/forms/form_abc123" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{ "deleted": true, "id": "form_abc123" }

POSThttps://formguru.com.br/api/v1/forms/:id/publishforms:write

Publica um formulário, tornando-o acessível ao público para receber respostas.

Exemplo

curl -X POST "https://formguru.com.br/api/v1/forms/form_abc123/publish" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "id": "form_abc123",
  "status": "published",
  "published_at": "2025-04-15T13:00:00Z"
}

POSThttps://formguru.com.br/api/v1/forms/:id/unpublishforms:write

Despublica um formulário, impedindo novas respostas sem excluir os dados existentes.

Exemplo

curl -X POST "https://formguru.com.br/api/v1/forms/form_abc123/unpublish" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "id": "form_abc123",
  "status": "draft",
  "updated_at": "2025-04-15T14:00:00Z"
}

3. Perguntas

Gerencie as perguntas de um formulário. Cada pergunta tem um tipo que define como a resposta será coletada.

GEThttps://formguru.com.br/api/v1/forms/:id/questionsforms:read

Lista todas as perguntas de um formulário, ordenadas por posição.

Exemplo

curl "https://formguru.com.br/api/v1/forms/form_abc123/questions" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "data": [
    {
      "id": "q_001",
      "title": "Qual seu nível de satisfação?",
      "type": "rating",
      "position": 1,
      "required": true
    },
    {
      "id": "q_002",
      "title": "Tem algum comentário?",
      "type": "long_text",
      "position": 2,
      "required": false
    }
  ]
}

POSThttps://formguru.com.br/api/v1/forms/:id/questionsforms:write

Adiciona uma nova pergunta ao formulário. Tipos disponíveis: short_text, long_text, email, number, rating, multiple_choice, checkbox, date.

Exemplo

curl -X POST "https://formguru.com.br/api/v1/forms/form_abc123/questions" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Como você nos conheceu?",
    "type": "multiple_choice"
  }'

Resposta

{
  "id": "q_003",
  "title": "Como você nos conheceu?",
  "type": "multiple_choice",
  "position": 3,
  "required": false,
  "created_at": "2025-04-15T10:00:00Z"
}

Operações em uma pergunta específica

GEThttps://formguru.com.br/api/v1/forms/:id/questions/:qidforms:read

Retorna os detalhes de uma pergunta específica.

Exemplo

curl "https://formguru.com.br/api/v1/forms/form_abc123/questions/q_001" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "id": "q_001",
  "title": "Qual seu nível de satisfação?",
  "type": "rating",
  "position": 1,
  "required": true
}

PATCHhttps://formguru.com.br/api/v1/forms/:id/questions/:qidforms:write

Atualiza os dados de uma pergunta específica.

Exemplo

curl -X PATCH "https://formguru.com.br/api/v1/forms/form_abc123/questions/q_001" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "required": false, "title": "Nível de satisfação (opcional)" }'

Resposta

{
  "id": "q_001",
  "title": "Nível de satisfação (opcional)",
  "type": "rating",
  "required": false,
  "updated_at": "2025-04-15T11:00:00Z"
}

DELETEhttps://formguru.com.br/api/v1/forms/:id/questions/:qidforms:write

Remove permanentemente uma pergunta do formulário.

Exemplo

curl -X DELETE "https://formguru.com.br/api/v1/forms/form_abc123/questions/q_001" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{ "deleted": true, "id": "q_001" }

4. Respostas

Acesse e gerencie as respostas enviadas aos seus formulários. Suporta filtros por status e período.

GEThttps://formguru.com.br/api/v1/forms/:formId/responsesresponses:read

Lista as respostas de um formulário. Parâmetros opcionais: status (complete | partial), since (ISO 8601), until (ISO 8601).

Exemplo

curl "https://formguru.com.br/api/v1/forms/form_abc123/responses?status=complete&since=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "data": [
    {
      "id": "resp_aaa",
      "form_id": "form_abc123",
      "status": "complete",
      "submitted_at": "2025-03-10T08:22:00Z",
      "answers": [
        { "question_id": "q_001", "value": 5 },
        { "question_id": "q_002", "value": "Excelente serviço!" }
      ]
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 }
}

POSThttps://formguru.com.br/api/v1/forms/:formId/responsesresponses:write

Envia uma nova resposta a um formulário. Útil para integrar formulários externos ou importar dados.

Exemplo

curl -X POST "https://formguru.com.br/api/v1/forms/form_abc123/responses" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      { "question_id": "q_001", "value": 4 },
      { "question_id": "q_002", "value": "Muito bom!" }
    ]
  }'

Resposta

{
  "id": "resp_bbb",
  "form_id": "form_abc123",
  "status": "complete",
  "submitted_at": "2025-04-15T10:00:00Z"
}

Operações em uma resposta específica

GEThttps://formguru.com.br/api/v1/forms/:formId/responses/:idresponses:read

Retorna os detalhes completos de uma resposta específica, incluindo todas as respostas às perguntas.

Exemplo

curl "https://formguru.com.br/api/v1/forms/form_abc123/responses/resp_aaa" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "id": "resp_aaa",
  "form_id": "form_abc123",
  "status": "complete",
  "submitted_at": "2025-03-10T08:22:00Z",
  "answers": [
    { "question_id": "q_001", "question_title": "Qual seu nível de satisfação?", "value": 5 },
    { "question_id": "q_002", "question_title": "Tem algum comentário?", "value": "Excelente serviço!" }
  ]
}

DELETEhttps://formguru.com.br/api/v1/forms/:formId/responses/:idresponses:write

Exclui permanentemente uma resposta. Esta ação é irreversível.

Exemplo

curl -X DELETE "https://formguru.com.br/api/v1/forms/form_abc123/responses/resp_aaa" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{ "deleted": true, "id": "resp_aaa" }

5. Insights

Acesse análises geradas por IA para respostas individuais e resumos agregados do formulário.

GEThttps://formguru.com.br/api/v1/forms/:formId/responses/:id/insightinsights:read

Retorna o insight gerado por IA para uma resposta específica.

Exemplo

curl "https://formguru.com.br/api/v1/forms/form_abc123/responses/resp_aaa/insight" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "response_id": "resp_aaa",
  "summary": "Respondente muito satisfeito. Destacou atendimento ágil e produto de qualidade.",
  "sentiment": "positive",
  "score": 0.92,
  "generated_at": "2025-03-10T08:25:00Z"
}

GEThttps://formguru.com.br/api/v1/forms/:formId/insightsinsights:read

Retorna um resumo agregado com insights do formulário inteiro, incluindo tendências e pontos de atenção.

Exemplo

curl "https://formguru.com.br/api/v1/forms/form_abc123/insights" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "form_id": "form_abc123",
  "total_responses": 42,
  "avg_rating": 4.7,
  "sentiment_breakdown": {
    "positive": 35,
    "neutral": 5,
    "negative": 2
  },
  "top_themes": ["atendimento", "qualidade", "prazo de entrega"],
  "generated_at": "2025-04-15T09:00:00Z"
}

6. Webhooks

Configure webhooks para receber notificações em tempo real quando eventos ocorrerem na sua conta (ex.: nova resposta, formulário publicado).

GEThttps://formguru.com.br/api/v1/webhookswebhooks:read

Lista todos os webhooks configurados na organização.

Exemplo

curl "https://formguru.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "data": [
    {
      "id": "wh_001",
      "url": "https://meusite.com.br/webhook/formguru",
      "events": ["response.submitted"],
      "active": true,
      "created_at": "2025-02-01T10:00:00Z"
    }
  ]
}

POSThttps://formguru.com.br/api/v1/webhookswebhooks:write

Cria um novo webhook. Eventos disponíveis: response.submitted, response.deleted, form.published, form.unpublished.

Exemplo

curl -X POST "https://formguru.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhook/formguru",
    "events": ["response.submitted"]
  }'

Resposta

{
  "id": "wh_002",
  "url": "https://meusite.com.br/webhook/formguru",
  "events": ["response.submitted"],
  "secret": "whsec_xxxxxxxxxxxxx",
  "active": true,
  "created_at": "2025-04-15T10:00:00Z"
}

Operações em um webhook específico

GEThttps://formguru.com.br/api/v1/webhooks/:idwebhooks:read

Retorna os detalhes de um webhook específico.

Exemplo

curl "https://formguru.com.br/api/v1/webhooks/wh_001" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "id": "wh_001",
  "url": "https://meusite.com.br/webhook/formguru",
  "events": ["response.submitted"],
  "active": true,
  "created_at": "2025-02-01T10:00:00Z"
}

PATCHhttps://formguru.com.br/api/v1/webhooks/:idwebhooks:write

Atualiza a URL, os eventos ou o status (ativo/inativo) de um webhook.

Exemplo

curl -X PATCH "https://formguru.com.br/api/v1/webhooks/wh_001" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Resposta

{
  "id": "wh_001",
  "active": false,
  "updated_at": "2025-04-15T11:00:00Z"
}

DELETEhttps://formguru.com.br/api/v1/webhooks/:idwebhooks:write

Remove permanentemente um webhook.

Exemplo

curl -X DELETE "https://formguru.com.br/api/v1/webhooks/wh_001" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{ "deleted": true, "id": "wh_001" }

7. Organização

Consulte as informações e configurações da sua organização.

GEThttps://formguru.com.br/api/v1/organizationorganization:read

Retorna os dados da organização associada à API Key utilizada.

Exemplo

curl "https://formguru.com.br/api/v1/organization" \
  -H "Authorization: Bearer sk_live_xxx"

Resposta

{
  "id": "org_123",
  "name": "Minha Empresa",
  "plan": "PRO",
  "forms_count": 12,
  "responses_count": 1340,
  "created_at": "2024-06-01T00:00:00Z"
}

8. Erros

Todas as respostas de erro seguem o mesmo formato JSON. O campo code identifica o tipo de erro de forma programática.

{
  "error": {
    "code": "validation_error",
    "message": "O campo 'title' é obrigatório.",
    "status": 400
  }
}

Status HTTP	Código	Descrição
400	`validation_error`	Os dados enviados são inválidos ou estão incompletos.
401	`unauthorized`	API Key ausente, inválida ou revogada.
403	`forbidden`	A chave não tem permissão para este recurso ou escopo.
404	`not_found`	O recurso solicitado não foi encontrado.
429	`rate_limit_exceeded`	Limite de requisições atingido. Aguarde antes de tentar novamente.
500	`internal_error`	Erro interno no servidor. Nossa equipe foi notificada.

9. Rate Limits

Os limites variam conforme o plano da sua organização. Ao atingir o limite, a API retorna HTTP 429 com o código rate_limit_exceeded.

Plano	Req / minuto	Req / dia
STARTER	60	5.000
PRO	120	20.000
PREMIUM	300	100.000

Cada resposta da API inclui cabeçalhos com informações sobre o seu consumo atual:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1713175200
Retry-After: 15

X-RateLimit-Reset é um timestamp Unix (segundos) indicando quando o contador será zerado. Retry-After aparece apenas quando o limite foi atingido.

Dúvidas? suporte@formguru.com.br