---
title: "Salvar formulário"
method: POST
path: "/api/management/save-form"
tags: ["forms"]
---

# Salvar formulário

`POST /api/management/save-form`

Cria um formulário ou, quando `id` é enviado, atualiza o título e os campos de um existente. A lista `edges` é sempre a definição completa: campo existente que não vier no payload é removido definitivamente. Tipos de campo e lógica condicional estão em [Criar um formulário](https://docs.olie.ai/guides/forms/creating-forms).

## Request body

- object — Definição completa do formulário.
  - `id` integer, nullable — ID do formulário a atualizar. Omita ou envie nulo para criar um novo.
  - `title` string, required — Título do formulário (3 a 255 caracteres).
  - `edges` object[], required — Lista completa de campos, na ordem desejada. Campos existentes que não forem enviados são removidos definitivamente.
    - `id` union — ID do campo existente (número) para atualizá-lo. Em campo novo, envie um ID temporário em texto (ex.: "CREATE1") para poder referenciá-lo em conditionals.target_id no mesmo payload.
      - integer
      - string
    - `label` string, required — Rótulo do campo (até 255 caracteres, sem HTML).
    - `type` 'short_text' | 'long_text' | 'rich_text' | 'attachment' | 'checkbox' | 'user' | 'date' | 'date_and_time' | 'email' | 'phone' | 'select' | 'radio' | 'currency' | 'number' | 'link' | 'time' | 'contact' | 'customer' | 'project' | 'counter' | 'matrix', required — Tipo do campo.
    - `index` integer — Posição do campo no formulário.
    - `required` boolean — Se o preenchimento é obrigatório.
    - `help_text` string, nullable — Texto de ajuda (até 255 caracteres).
    - `description` string, nullable — Descrição do campo (até 255 caracteres).
    - `custom_validation` string, nullable — Expressão regular que a resposta precisa atender (até 255 caracteres).
    - `options` union — Opções do campo: lista de textos para select, radio e checkbox; objeto com rows/columns para matrix. Opções removidas são apagadas das respostas já dadas.
      - string[]
      - object
        - `rows` object[] — Linhas da matriz (1 a 100).
          - `key` string — Chave única da linha (1 a 64 caracteres).
          - `label` string — Rótulo exibido na linha (1 a 255 caracteres).
        - `columns` object[] — Colunas da matriz (1 a 20).
          - `key` string, required — Chave única da coluna (1 a 64 caracteres). O tipo de uma coluna existente não pode mudar.
          - `label` string, required — Rótulo exibido na coluna (1 a 255 caracteres).
          - `type` 'short_text' | 'long_text' | 'number' | 'currency' | 'date' | 'date_and_time' | 'time' | 'email' | 'phone' | 'link' | 'select' | 'radio' | 'checkbox', required — Tipo da célula. Aceita apenas tipos simples.
          - `options` string[] — Opções da célula (1 a 50). Obrigatório para select, radio e checkbox; proibido nos demais tipos.
          - `required` boolean — Se a célula é obrigatória.
          - `is_multiple` boolean — Permite vários links na célula. Só para colunas do tipo link.
          - `description` string, nullable — Descrição da coluna (até 255 caracteres).
          - `help_text` string, nullable — Texto de ajuda da coluna (até 255 caracteres).
          - `custom_validation` string, nullable — Expressão regular aplicada à célula. Só para short_text, long_text, email, phone, currency e number.
    - `is_multiple` boolean, nullable — Se o campo aceita mais de um valor.
    - `initial_value` union — Valor pré-preenchido, no formato de uma resposta daquele tipo. É validado como uma resposta.
      - string
      - number
      - unknown[]
        - unknown
      - object
    - `conditional_action` 'show' | 'hide' | 'null', nullable — O que fazer com o campo quando as regras são atendidas.
    - `logical_operator` 'and' | 'or' | 'null', nullable — Como combinar as regras do campo: and (todas) ou or (qualquer uma).
    - `conditionals` object[] — Regras que controlam a exibição do campo. Substituem as regras anteriores a cada salvamento.
      - `target_id` union, required — Campo cuja resposta é avaliada: ID existente ou ID temporário de um campo novo do mesmo payload. Campos matrix não podem ser avaliados.
        - integer
        - string
      - `operator` 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'is_empty' | 'is_not_empty' | 'starts_with' | 'ends_with' | 'greater_than_or_equals' | 'less_than_or_equals' — Operador de comparação. Padrão: equals.
      - `value` union — Valor comparado. Lista aceita apenas textos ou números.
        - string
        - number
        - string[]
    - `action` 'archive' | 'restore' — Ação sobre um campo existente: archive arquiva (oculta sem apagar as respostas) e restore reativa um campo arquivado.

## Response `200`

Sucesso

- object — Formulário salvo.
  - `response` boolean — Indicador de sucesso da requisição. Sempre true nas respostas bem-sucedidas.
  - `form` object — Dados do formulário.
    - `id` integer — ID do formulário.
    - `title` string — Título do formulário.
    - `frame_id` string, uuid — ID da conta dona do formulário.
    - `created_at` string, date-time — Data de criação do formulário.
    - `updated_at` string, date-time — Data da última alteração do formulário.
    - `deleted_at` string, date-time, nullable — Data de exclusão do formulário. Nulo quando ativo.
    - `edges` object[] — Campos do formulário, ordenados por index.
      - `id` integer — ID do campo.
      - `type` 'short_text' | 'long_text' | 'rich_text' | 'attachment' | 'checkbox' | 'user' | 'date' | 'date_and_time' | 'email' | 'phone' | 'select' | 'radio' | 'currency' | 'number' | 'link' | 'time' | 'contact' | 'customer' | 'project' | 'counter' | 'matrix' — Tipo do campo.
      - `label` string — Rótulo do campo.
      - `index` integer — Posição do campo no formulário (ordem crescente).
      - `help_text` string, nullable — Texto de ajuda exibido junto ao campo.
      - `description` string, nullable — Descrição do campo.
      - `options` union — Opções do campo: lista de textos para select, radio e checkbox; objeto com rows/columns para matrix; lista vazia nos demais tipos.
        - string[]
        - object
      - `initial_value` union — Valor pré-preenchido do campo, no mesmo formato de uma resposta daquele tipo.
        - string
        - number
        - unknown[]
          - unknown
        - object
      - `required` boolean — Se o preenchimento é obrigatório.
      - `custom_validation` string, nullable — Expressão regular que a resposta precisa atender.
      - `conditional` unknown
      - `form_id` integer — ID do formulário ao qual o campo pertence.
      - `created_at` string, date-time — Data de criação do campo.
      - `updated_at` string, date-time — Data da última alteração do campo.
      - `deleted_at` string, date-time, nullable — Data em que o campo foi arquivado. Nulo quando ativo.
      - `is_multiple` boolean — Se o campo aceita mais de um valor (ex.: vários links ou usuários).
      - `logical_operator` 'and' | 'or' — Como as regras condicionais do campo se combinam.
      - `is_migrated` boolean — Marcador interno de migração de dados. Pode ser ignorado.
      - `conditional_action` 'show' | 'hide' | 'null', nullable — O que acontece com o campo quando as regras são atendidas: show (exibe) ou hide (oculta). Nulo quando não há lógica condicional.
      - `conditionals` object[] — Regras condicionais do campo.
        - `id` integer — ID da regra.
        - `form_edge_id` integer — ID do campo que é mostrado ou ocultado pela regra.
        - `target_id` integer — ID do campo cuja resposta é avaliada.
        - `operator` 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'is_empty' | 'is_not_empty' | 'starts_with' | 'ends_with' | 'greater_than_or_equals' | 'less_than_or_equals' — Operador de comparação.
        - `value` union — Valor comparado com a resposta do campo avaliado.
          - string
          - number
          - string[]
        - `created_at` string, date-time — Data de criação da regra.
        - `updated_at` string, date-time — Data da última alteração da regra.

## Other responses

- `422` — Validação falhou

## Changes

- **2026-09-22** `d71b18b1685d` — 18 breaking, 32 warning, 40 info
  - request property `edges/items/type` was restricted to a list of enum values
  - the request property `edges` became required
  - the request property `edges/items/label` became required
  - the request property `edges/items/type` became required
  - …86 more
- **2026-09-22** `b43a04f35145` — 3 info
  - added optional request body
  - added the media type `application/json` for the response with the status `200`
  - added the non-success response with the status `422`

[Change history](https://skmtc.dev/olie-ai/apis/olie-api/changes/api/management/save-form/post.md)

---

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