Formulários (forms)

O recurso forms expõe os formulários criados na sua conta: pesquisas, inscrições, captação de leads e afins. Cada formulário traz título, slug público, tipo, situação, visibilidade, janela de respostas e as metas definidas por quem o criou. A API descreve os formulários; as respostas enviadas a eles ainda não estão expostas.

Acesso


Módulo	`formularios`
Escopos	`forms:read` (ou `:read`, ou `:write`)
Operações	somente leitura

Sem o módulo no contrato, a resposta é 403 module_not_enabled. Sem o escopo na chave, é 403 insufficient_scope.

Endpoints

Método	Endpoint	Descrição
`GET`	`/v1/forms`	Lista formulários, com paginação por cursor
`GET`	`/v1/forms/{id}`	Retorna um formulário pelo `id`

A listagem usa o envelope padrão com data, pagination e meta, e aceita limit (1 a 100, padrão 20), cursor, sort e fields. Veja Paginação, filtros e ordenação.

Campos

Campo	Tipo	Descrição
`id`	`uuid`	Identificador do formulário
`title`	`string`	Título do formulário
`description`	`string \| null`	Descrição exibida a quem responde
`slug`	`string`	Identificador amigável usado na URL pública
`form_type`	`string`	Tipo do formulário, por exemplo `survey`, `registration`, `lead`
`status`	`string`	Situação atual, por exemplo `draft`, `published`, `closed`
`visibility`	`string`	Visibilidade, por exemplo `public`, `private`
`opens_at`	`timestamp (ISO 8601) \| null`	Início da janela de respostas
`closes_at`	`timestamp (ISO 8601) \| null`	Fim da janela de respostas
`max_responses`	`integer \| null`	Teto de respostas aceitas
`response_goal`	`integer \| null`	Meta de respostas definida na criação
`one_response_per_person`	`boolean \| null`	Se cada pessoa pode responder uma única vez
`is_active`	`boolean \| null`	`false` quando o formulário foi desativado
`created_at`	`timestamp (ISO 8601) \| null`	Criação do registro
`updated_at`	`timestamp (ISO 8601) \| null`	Última atualização

Filtros e ordenação

Campo	Operadores	Exemplo
`status`	`eq`, `in`	`filter[status][eq]=published`
`form_type`	`eq`, `in`	`filter[form_type][eq]=survey`
`is_active`	`eq`	`filter[is_active][eq]=true`
`title`	`ilike`	`filter[title][ilike]=pesquisa%25`

Filtros combinam com AND. Em ilike, o curinga % precisa ser codificado como %25 na URL. A ordenação padrão é -created_at; sort também aceita created_at, updated_at e title, com - na frente para ordem decrescente.

Exemplos

Listar

curl "$LIGGA_BASE/v1/forms?limit=2&sort=-created_at&filter[status][eq]=published" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": [
    {
      "id": "7f3b2c1a-9d4e-4f6b-8a2c-5e1d0b9a8c7f",
      "title": "Pesquisa de satisfação — Julho",
      "description": "Conte para a gente como foi a sua experiência este mês.",
      "slug": "pesquisa-satisfacao-julho",
      "form_type": "survey",
      "status": "published",
      "visibility": "public",
      "opens_at": "2026-07-01T12:00:00+00:00",
      "closes_at": "2026-07-31T23:59:59+00:00",
      "max_responses": 500,
      "response_goal": 200,
      "one_response_per_person": true,
      "is_active": true,
      "created_at": "2026-06-28T14:22:10.481+00:00",
      "updated_at": "2026-07-02T09:05:33.127+00:00"
    },
    {
      "id": "2a8d5e4f-1b3c-4a7d-9e6f-0c2b4a8d5e4f",
      "title": "Inscrição — Workshop de fotografia",
      "description": null,
      "slug": "workshop-fotografia",
      "form_type": "registration",
      "status": "published",
      "visibility": "private",
      "opens_at": "2026-06-01T12:00:00+00:00",
      "closes_at": "2026-06-15T23:59:59+00:00",
      "max_responses": 30,
      "response_goal": null,
      "one_response_per_person": true,
      "is_active": true,
      "created_at": "2026-05-20T10:11:45.902+00:00",
      "updated_at": "2026-06-16T08:30:02.615+00:00"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjJhOGQ1ZTRmLTFiM2MtNGE3ZC05ZTZmLTBjMmI0YThkNWU0ZiIsInYiOiIyMDI2LTA1LTIwVDEwOjExOjQ1LjkwMiswMDowMCJ9",
    "has_more": true,
    "limit": 2
  },
  "meta": { "request_id": "req_01JYQ8V2K5M7N9P0R1S2T3U4VX" }
}

Para a próxima página, repita a chamada com cursor=<pagination.next_cursor> enquanto has_more for true.

Buscar por id

curl "$LIGGA_BASE/v1/forms/7f3b2c1a-9d4e-4f6b-8a2c-5e1d0b9a8c7f?fields=id,title,slug,status,closes_at" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

{
  "data": {
    "id": "7f3b2c1a-9d4e-4f6b-8a2c-5e1d0b9a8c7f",
    "title": "Pesquisa de satisfação — Julho",
    "slug": "pesquisa-satisfacao-julho",
    "status": "published",
    "closes_at": "2026-07-31T23:59:59+00:00"
  },
  "meta": { "request_id": "req_01JYQ8V2K5M7N9P0R1S2T3U4VX" }
}

Erros comuns

HTTP	`type`	Quando acontece
401	`invalid_token`	Cabeçalho `Authorization` ausente ou chave inexistente
403	`insufficient_scope`	Chave sem `forms:read`
403	`module_not_enabled`	Módulo `formularios` fora do contrato
404	`not_found`	`id` inexistente ou de outra conta
422	`validation`	Campo de filtro, operador, `sort` ou `cursor` não aceito
429	`rate-limit-exceeded`	Limite de requisições do plano excedido

Veja também

Paginação, filtros e ordenação — limit, cursor, sort e fields
Módulos e escopos — o que o módulo formularios libera
Formatos de identificador — o formato de id e slug
Erros — o corpo de erro completo