---
title: "Criar formulário"
method: POST
path: "/v1/flows"
tags: ["Formulários"]
---

# Criar formulário

`POST /v1/flows`

## Request

- Base URL: `https://api.ararahq.com`
- URL: `https://api.ararahq.com/v1/flows`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ararahq/apis/ararahq-api/docs/v1/flows/post.ts> (a function with typed inputs; its response is checked against the schema)

Cria o formulário e já publica: quando a chamada volta `201` com
`status: PUBLISHED`, ele está no ar e não pode mais ser editado. Se só a
publicação falhar, o formulário fica em `DRAFT` com `publishError`
preenchido; publique de novo em `POST /v1/flows/{id}/publish`.

Não aceita `Idempotency-Key`. O nome é único por número, então repetir
um `POST` que já passou responde `409 FLOW_NAME_TAKEN` em vez de duplicar.

Disponível do plano Voo para cima. Permissão: `TEMPLATES_WRITE`.

## Request body

- CreateFlowRequest
  - `name` string, required: Nome interno, único por número. Só você vê.
  - `category` 'SIGN_UP' | 'LEAD_GENERATION' | 'SURVEY' | 'APPOINTMENT_BOOKING' | 'CONTACT_US' | 'OTHER', required
  - `title` string, required: Aparece no topo do formulário.
  - `intro` string, nullable: Texto de introdução, abaixo do título.
  - `submitLabel` string: Texto do botão de envio.
  - `fields` FlowFieldRequest[], required: De 1 a 10 perguntas, todas na mesma tela.
    - `label` string, required: Texto da pergunta.
    - `type` 'TEXT' | 'EMAIL' | 'PHONE' | 'NUMBER' | 'LONG_TEXT' | 'SELECT' | 'MULTI_SELECT' | 'DATE' | 'OPT_IN', required: Texto, e-mail, telefone, número, texto longo, escolha única, múltipla escolha, data ou aceite.
    - `required` boolean: Pergunta opcional sem resposta chega como string vazia no webhook.
    - `options` string[], nullable: Só em `SELECT` e `MULTI_SELECT`. De 2 a 20 opções, até 30 caracteres cada.
    - `key` string, nullable: Nome do campo no webhook (`fields.email`). Minúsculas, números e `_`, começando por letra. Sem ela, nasce do texto da pergunta. Não muda depois de publicado.

## Response `201`

Formulário criado

- Flow
  - `id` string, uuid, required: Use como `flowId` no envio e no botão `FLOW` do template.
  - `name` string, required
  - `category` 'SIGN_UP' | 'LEAD_GENERATION' | 'SURVEY' | 'APPOINTMENT_BOOKING' | 'CONTACT_US' | 'OTHER', required
  - `status` 'DRAFT' | 'PUBLISHED' | 'DEPRECATED', required: `DRAFT`: criado, mas a publicação falhou (veja `publishError`). `PUBLISHED`: no ar, pode ser enviado. `DEPRECATED`: desativado.
  - `definition` object, required: O formulário como foi criado, já com as chaves finais.
    - `title` string, required
    - `intro` string, nullable
    - `submitLabel` string, required
    - `fields` FlowField[], required
      - `key` string, required: Chave estável da resposta.
      - `label` string, required
      - `type` 'TEXT' | 'EMAIL' | 'PHONE' | 'NUMBER' | 'LONG_TEXT' | 'SELECT' | 'MULTI_SELECT' | 'DATE' | 'OPT_IN', required: Texto, e-mail, telefone, número, texto longo, escolha única, múltipla escolha, data ou aceite.
      - `required` boolean, required
      - `options` object[], required
        - `id` string, required
        - `title` string, required
  - `responseCount` integer, required: Total de respostas recebidas.
  - `publishError` string, nullable: Preenchido só quando o formulário foi criado mas a publicação falhou.
  - `createdAt` string, date-time, nullable
  - `publishedAt` string, date-time, nullable

## Other responses

- `400`: `INVALID_FLOW`: pergunta em branco, opções de menos, chave inválida ou JSON recusado pela Meta. Também `INVALID_JSON`.
- `401`: Chave inexistente, revogada, expirada, com prefixo errado (`ara_` sem `ara_live_`) ou vinda de IP fora da allowlist. O corpo é o JSON padrão do Spring, sem `error.code`.
- `403`: Dois casos, com corpos diferentes: - Autenticação: header `Authorization` ausente, Bearer que não começa com `ara_`, chave sem a permissão da rota ou rota que não aceita chave de API. Corpo no formato padrão do Spring, sem `error.code`. - Regra de negócio, no formato `{ "error": { ... } }`: `PLAN_FEATURE_LOCKED`, `PLAN_LIMIT_REACHED`, `ACCOUNT_NOT_ACTIVATED`, `NO_DEDICATED_NUMBER`, `ORGANIZATION_SUSPENDED`, `NUMBER_BLOCKED`, `FRAUD_SUSPECTED`, `RESOURCE_FORBIDDEN`, `VIEWER_READ_ONLY`.
- `409`: `FLOW_NAME_TAKEN` (nome já usado no número) ou `FLOW_NUMBER_REQUIRED` (nenhum número conectado).
- `429`: `RATE_LIMIT_EXCEEDED`: limite geral da API (1.200 leituras ou 3.000 escritas por minuto, por usuário da chave).

## Changes

- **2026-10-12** `d576cd28afc0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ararahq/apis/ararahq-api/changes/v1/flows/post.md)

---

[API](https://skmtc.dev/ararahq/apis/ararahq-api.md) - [All operations](https://skmtc.dev/ararahq/apis/ararahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ararahq/apis/ararahq-api/revisions/d576cd28afc0?raw)