---
title: "Cria uma nova versão (schema) do formulário"
method: POST
path: "/api/v1/forms/{form_key}/versions"
tags: ["Versions"]
---

# Cria uma nova versão (schema) do formulário

`POST /api/v1/forms/{form_key}/versions`

## Request

- Base URL: `https://clickform-sandbox.clicksign.com`
- URL: `https://clickform-sandbox.clicksign.com/api/v1/forms/{form_key}/versions`
- Auth: API key in header `Authorization`

## Path parameters

- `form_key` string, uuid, required

## Request body

- object: Corpo para criar ou substituir o schema de uma versão.
  - `is_active` boolean
  - `settings` object: Textos de UI e, opcionalmente, rótulos das etapas do formulário.
    - `title` string
    - `subtitle` string
    - `finish_title` string
    - `finish_subtitle` string
    - `finish_info` string
    - `steps` object: Mapa índice da etapa (string) → rótulo exibido.
  - `fields` object[]
    - `key` string: Identificador estável após persistência; pode ser omitido no corpo de criação.
    - `label` string, required
    - `type` string, required: Exemplos text, textarea, number, number_range, email, phone_number, date, cpf, cnpj, currency, cep, image, file, header, paragraph, select, radio-group, checkbox-group, repeater.
    - `required` boolean
    - `order` integer
    - `step` integer
    - `placeholder` string
    - `help_balloon` string: Texto de ajuda exibido em balão junto ao rótulo do campo. Opcional; aplicável aos tipos de entrada e sub-campos aninhados em CEP e repeater (não se aplica a `header` e `paragraph`).
    - `external_key` string: Chave opcional usada no payload do webhook (`responses` e `attachments`) no lugar da `key` interna auto-gerada. O front-end e o `context` do run continuam usando a `key` interna. A API normaliza o valor para snake_case (ex.: "Nome Completo" → `nome_completo`); valores sem nenhum caractere válido (ex.: `!!!`) retornam 400. Deve ser única por nível do payload após a normalização: raiz + subcampos de CEP formam um nível, e cada repeater tem o seu. Também não pode coincidir com a `key` interna de outro campo do mesmo nível. Não se aplica a `header`, `paragraph` nem à raiz de `cep` (apenas aos subcampos em `options.fields`).
    - `conditions` object[]
      - `value` union: Valor comparado com o preenchimento do campo pai.
        - string
        - number
        - integer
        - boolean
      - `operator` string
      - `action` 'show' | 'hide': Ação aplicada aos campos alvo quando a condição é satisfeita.
      - `fields` string[]: Labels dos campos afetados pela regra.
    - `options` object: Opções por tipo (ex. maxlength, values, other, fields para CEP/repeater, min_value/max_value/decimal_places/min_error_message/max_error_message para number_range). Em number_range, min_error_message e max_error_message podem usar os placeholders {min_value}, {max_value} e {decimal_places}. Estrutura variável conforme o `type`.

## Response `201`

Versão criada.

- object: Versão persistida com campos estáveis (`key`) e metadados de auditoria.
  - `key` string, uuid
  - `version` string, uuid
  - `is_active` boolean
  - `fields` object[]
    - `key` string: Identificador estável após persistência; pode ser omitido no corpo de criação.
    - `label` string, required
    - `type` string, required: Exemplos text, textarea, number, number_range, email, phone_number, date, cpf, cnpj, currency, cep, image, file, header, paragraph, select, radio-group, checkbox-group, repeater.
    - `required` boolean
    - `order` integer
    - `step` integer
    - `placeholder` string
    - `help_balloon` string: Texto de ajuda exibido em balão junto ao rótulo do campo. Opcional; aplicável aos tipos de entrada e sub-campos aninhados em CEP e repeater (não se aplica a `header` e `paragraph`).
    - `external_key` string: Chave opcional usada no payload do webhook (`responses` e `attachments`) no lugar da `key` interna auto-gerada. O front-end e o `context` do run continuam usando a `key` interna. A API normaliza o valor para snake_case (ex.: "Nome Completo" → `nome_completo`); valores sem nenhum caractere válido (ex.: `!!!`) retornam 400. Deve ser única por nível do payload após a normalização: raiz + subcampos de CEP formam um nível, e cada repeater tem o seu. Também não pode coincidir com a `key` interna de outro campo do mesmo nível. Não se aplica a `header`, `paragraph` nem à raiz de `cep` (apenas aos subcampos em `options.fields`).
    - `conditions` object[]
      - `value` union: Valor comparado com o preenchimento do campo pai.
        - string
        - number
        - integer
        - boolean
      - `operator` string
      - `action` 'show' | 'hide': Ação aplicada aos campos alvo quando a condição é satisfeita.
      - `fields` string[]: Labels dos campos afetados pela regra.
    - `options` object: Opções por tipo (ex. maxlength, values, other, fields para CEP/repeater, min_value/max_value/decimal_places/min_error_message/max_error_message para number_range). Em number_range, min_error_message e max_error_message podem usar os placeholders {min_value}, {max_value} e {decimal_places}. Estrutura variável conforme o `type`.
  - `settings` object: Textos de UI e, opcionalmente, rótulos das etapas do formulário.
    - `title` string
    - `subtitle` string
    - `finish_title` string
    - `finish_subtitle` string
    - `finish_info` string
    - `steps` object: Mapa índice da etapa (string) → rótulo exibido.
  - `form_url` string, uri: URL pública para preenchimento do formulário.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Requisição inválida.
- `401`: Autenticação ausente ou inválida.
- `404`: Recurso não encontrado.

---

[API](https://skmtc.dev/clicksign/apis/m-dulo-de-coleta-de-dados-clickform.md) - [All operations](https://skmtc.dev/clicksign/apis/m-dulo-de-coleta-de-dados-clickform/llms.txt) - [OpenAPI document](https://skmtc.dev/clicksign/apis/m-dulo-de-coleta-de-dados-clickform/revisions/05dba4170672?raw)