Pular para o conteúdo

Criar um formulário

POST
/forms
 
curl --request POST \
  --url https://dattacrm.com.br/api/v1/forms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "slug": "example", "experience": "classic", "fields": [ { "additionalProperty": "example" } ], "defaultTags": [], "defaultListId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "funnelEntry": { "enabled": false, "stageId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }, "entryConfig": { "listId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }, "listRules": [ { "questionId": "example", "operator": "equals", "value": { "min": 1, "max": 1 }, "listIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] } ], "isActive": true, "showQuestions": false, "theme": { "background": "#202720", "foreground": "#fbfaf6", "accent": "#1d8f7a", "questionSize": "medium", "answerSize": "medium", "alignment": "left" }, "consent": { "enabled": false, "text": "", "url": "example" }, "emailMarketing": { "enabled": false, "text": "" } }'

Cria um formulário de captação pelo mesmo caminho da tela: mesmas validações, primeira versão no histórico e campos personalizados registrados no catálogo. Devolve o formulário com publicUrl (página pública) e embedUrl (código de incorporação). Responde 400 quando os campos são inválidos (id ausente ou repetido, conversacional sem campo name ou phone, etapa do funil inexistente, defaultListId que não é lista de Site da conta) e 409 quando o slug já está em uso.

Authorizations

Seção intitulada “Authorizations ”

Request Body required

Seção intitulada “Request Body required ”
Media type application/json

Dados do formulário. Obrigatórios: name, slug, experience e fields. O resto tem padrão (publicado, sem tags, tema escuro). Publicado exige defaultListId (ou entryConfig.listId); sem lista, só como rascunho (isActive: false).

object
name
required

Nome do formulário, como aparece no CRM (1 a 100 caracteres).

string
>= 1 characters <= 100 characters
slug
required

Apelido único do formulário em toda a plataforma (2 a 64 caracteres: letras minúsculas, números e hífen).

string
>= 2 characters <= 64 characters /^[a-z0-9-]+$/
experience
required

Formato: classic (todas as perguntas numa página) ou conversational (uma pergunta por vez, estilo typeform).

string
Allowed values: classic conversational
fields
required

Etapas do formulário, na ordem em que aparecem (até 50). Cada item é um objeto com no mínimo id (texto único no formulário), type e title. type aceita welcome, statement, short_text, long_text, email, phone, multiple_choice, opinion_scale, date, number, money, cpf, cnpj, address, url_param e thank_you. crmField liga a resposta a um campo do lead (name, email, phone ou o caminho de um campo personalizado, criado no catálogo se não existir). Outras chaves comuns: description, placeholder, required, options (lista de { label, value }) em multiple_choice, logic (regras de salto) e thankYou ({ mode, url, label }) em thank_you. No formato conversacional ao menos um campo precisa ter crmField igual a name ou phone. Exemplo de item: { “id”: “name”, “type”: “short_text”, “title”: “Seu nome”, “crmField”: “name”, “required”: true }.

Array<object>
<= 50 items

Uma etapa do formulário: objeto com id (texto único no formulário), type e title; as demais chaves dependem do tipo.

object
key
additional properties
defaultTags

Tags aplicadas a todo lead que enviar o formulário (até 20, de até 40 caracteres cada). Padrão: nenhuma.

Array<string>
default: <= 20 items
defaultListId
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
funnelEntry

Legado: aceito e ignorado. O formulário não coloca o lead no funil.

object
enabled

Legado: ignorado. A entrada de leads não coloca ninguém no funil.

boolean
stageId
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
entryConfig

Para onde vão os leads do formulário: a lista de destino, que precisa ser de Site. Omitido, o formulário mantém a configuração atual (ou nasce na lista de defaultListId, ou sem lista).

object
listId
required

Id de uma lista de Site da conta (de GET /lists).

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
listRules

Regras de lista por resposta (até 20), gravadas em settings.listRules: se a resposta de questionId bate (equals, in, contains ou between), o lead entra também nas listIds da regra. Só somam listas. Omitido, mantém as regras atuais; [] remove todas.

Array<object>
<= 20 items

Uma regra: se a resposta bate, o lead entra nas listas.

object
questionId
required

Id da pergunta (campo do formulário) cuja resposta é avaliada.

string
>= 1 characters
operator
required

Equals (igual), in (uma das opções), contains (contém o texto) ou between (número entre min e max, inclusivo).

string
Allowed values: equals in contains between
value
required
Any of:

Texto de comparação (equals e contains).

string
listIds
required

Listas em que o lead entra quando a regra bate (1 a 10).

Array<string>
>= 1 items <= 10 items
isActive

Publicado (true, padrão) ou desativado (false): desativado, a página pública deixa de aceitar envios.

boolean
default: true
showQuestions

Mostra a lista de perguntas na página do formulário conversacional. Padrão false.

boolean
theme

Aparência do formulário. Chaves omitidas ficam com o padrão (fundo escuro, destaque verde).

object
background

Cor de fundo, em hexadecimal de 6 dígitos (ex.: #202720).

string
default: #202720 /^#[0-9a-fA-F]{6}$/
foreground

Cor do texto, em hexadecimal de 6 dígitos.

string
default: #fbfaf6 /^#[0-9a-fA-F]{6}$/
accent

Cor de destaque (botões e seleção), em hexadecimal de 6 dígitos.

string
default: #1d8f7a /^#[0-9a-fA-F]{6}$/
bgType

Tipo do fundo: solid (cor única), linear, radial ou mesh (gradientes que usam bgColor2).

string
Allowed values: solid linear radial mesh
bgColor2

Segunda cor do gradiente de fundo, em hexadecimal de 6 dígitos.

string
/^#[0-9a-fA-F]{6}$/
fontFamily

Nome da fonte do formulário (até 50 caracteres).

string
<= 50 characters
fontSize

Tamanho geral da fonte: sm, md, lg ou xl.

string
Allowed values: sm md lg xl
questionSize

Tamanho do título das perguntas: small, medium (padrão) ou large.

string
default: medium
Allowed values: small medium large
answerSize

Tamanho do texto das respostas: small, medium (padrão) ou large.

string
default: medium
Allowed values: small medium large
alignment

Alinhamento do conteúdo: left (padrão) ou center.

string
default: left
Allowed values: left center
consent

Caixa de consentimento LGPD exibida ao lead antes de enviar. Omitida, não aparece.

object
enabled

Mostra a caixa de consentimento (LGPD) antes do envio.

boolean
text

Texto da caixa de consentimento (até 500 caracteres).

string
"" <= 500 characters
url

Endereço http(s) da política de privacidade; vazio para não mostrar link.

string
<= 500 characters
emailMarketing

Caixa de aceite de e-mail marketing; marcada, registra o consentimento do lead. Omitida, não aparece.

object
enabled

Mostra a caixa “quero receber novidades por e-mail”.

boolean
text

Texto da caixa (até 300 caracteres). Vazio usa o texto padrão.

string
"" <= 300 characters

Responses

Seção intitulada “ Responses ”

201

Seção intitulada “201 ”

Sucesso.

Media type application/json
object
data
required

Formulário de captação da conta, com as etapas, o tema e os endereços de uso.

object
id
required

Identificador do formulário.

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
name
required

Nome do formulário, como aparece no CRM.

string
slug
required

Apelido único do formulário na plataforma.

string
experience
required

Formato: classic (todas as perguntas numa página) ou conversational (uma pergunta por vez).

string
Allowed values: classic conversational
isActive
required

Publicado (true) ou desativado (false).

boolean
fields
required

Etapas do formulário, na ordem em que aparecem.

Array<object>

Uma etapa do formulário (id, type, title, crmField…).

object
key
additional properties
defaultTags
required

Tags aplicadas a todo lead que enviar o formulário.

Array<string>
defaultListId
required
Any of:

Identificador único (UUID).

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
theme
required

Aparência do formulário (cores, fundo, tamanhos e alinhamento).

object
background
required

Cor de fundo, em hexadecimal de 6 dígitos (ex.: #202720).

string
default: #202720 /^#[0-9a-fA-F]{6}$/
foreground
required

Cor do texto, em hexadecimal de 6 dígitos.

string
default: #fbfaf6 /^#[0-9a-fA-F]{6}$/
accent
required

Cor de destaque (botões e seleção), em hexadecimal de 6 dígitos.

string
default: #1d8f7a /^#[0-9a-fA-F]{6}$/
bgType

Tipo do fundo: solid (cor única), linear, radial ou mesh (gradientes que usam bgColor2).

string
Allowed values: solid linear radial mesh
bgColor2

Segunda cor do gradiente de fundo, em hexadecimal de 6 dígitos.

string
/^#[0-9a-fA-F]{6}$/
fontFamily

Nome da fonte do formulário (até 50 caracteres).

string
<= 50 characters
fontSize

Tamanho geral da fonte: sm, md, lg ou xl.

string
Allowed values: sm md lg xl
questionSize
required

Tamanho do título das perguntas: small, medium (padrão) ou large.

string
default: medium
Allowed values: small medium large
answerSize
required

Tamanho do texto das respostas: small, medium (padrão) ou large.

string
default: medium
Allowed values: small medium large
alignment
required

Alinhamento do conteúdo: left (padrão) ou center.

string
default: left
Allowed values: left center
publicUrl
required

Endereço da página pública do formulário.

string
embedUrl
required

Endereço do código de incorporação (HTML) para colocar o formulário em outro site.

string
createdAt
required

Quando o formulário foi criado.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
updatedAt
required

Quando o formulário foi alterado pela última vez.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
Example 
{
  "data": {
    "id": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f",
    "experience": "classic",
    "defaultListId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f",
    "theme": {
      "background": "#202720",
      "foreground": "#fbfaf6",
      "accent": "#1d8f7a",
      "bgType": "solid",
      "fontSize": "sm",
      "questionSize": "small",
      "answerSize": "small",
      "alignment": "left"
    },
    "createdAt": "2026-10-19T12:00:00.000Z",
    "updatedAt": "2026-10-19T12:00:00.000Z"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

400

Seção intitulada “400 ”

Dados inválidos na requisição (validation_error), lead novo sem lista (list_required), campo que mudou de lugar (field_moved) ou chave enviada na URL (api_key_in_url).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

401

Seção intitulada “401 ”

Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

403

Seção intitulada “403 ”

A chave é somente leitura e a operação grava dados (insufficient_scope).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

409

Seção intitulada “409 ”

Conflito com o estado atual (conflict), contato oculto, cujo negócio não muda (lead_hidden), ou limite do plano atingido (plan_limit).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

413

Seção intitulada “413 ”

O corpo da requisição passa de 256 KB (payload_too_large).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

429

Seção intitulada “429 ”

Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

Retry-After
integer

Segundos até poder tentar de novo.

500

Seção intitulada “500 ”

Erro interno (internal_error). Informe o requestId ao suporte.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

503

Seção intitulada “503 ”

O CRM está em modo somente leitura durante uma migração (maintenance). Tente de novo depois de Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

Retry-After
integer

Segundos até poder tentar de novo.