Skip to main content
POST
/
api
/
v1
/
leads
curl -X POST https://crm.vistum.com.br/api/v1/leads \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "11999887766",
    "name": "João Ferreira",
    "email": "joao@empresa.com",
    "pipeline": "Vendas",
    "stage": "Qualificação",
    "value": 2500,
    "origin": "landing-page",
    "tags": ["lead-quente", "formulario-site"],
    "assignedTo": "Carlos Atendente",
    "customFields": {
      "Cidade": "São Paulo",
      "Interesse": "Plano PRO"
    }
  }'

{
  "ok": true,
  "action": "created",
  "contact": {
    "id": "cnt_cmnl5abc123",
    "name": "João Ferreira",
    "phone": "5511999887766",
    "email": "joao@empresa.com"
  },
  "card": {
    "id": "card_def456ghi",
    "stageId": "stage_xyz789",
    "origin": "landing-page"
  }
}

​
Autenticação

​
Authorization
string
required
Bearer vg_live_<sua_chave> — API Key com escopo leads:write

​
Body

​
phone
string
required
Número de telefone do contato. Aceita formato E.164 (5511999887766) ou brasileiro (11999887766 ou (11) 99988-7766). O número é normalizado automaticamente com DDI 55 se ausente.
​
name
string
Nome completo do contato.
​
email
string
E-mail do contato.
​
notes
string
Observações internas. Aparece no campo de notas do contato no CRM.
​
tags
string[]
Lista de tags para aplicar ao contato. Tags inexistentes são criadas automaticamente. Máximo de 20 tags por requisição.
"tags": ["lead-quente", "instagram", "produto-x"]
​
pipeline
string
Nome ou ID do pipeline onde o card deve ser criado. Se o pipeline não for encontrado, nenhum card é criado (o contato ainda é salvo).
​
stage
string
Nome ou ID da etapa do pipeline. Se omitido, o card vai para a primeira etapa do pipeline.
​
value
number
Valor do negócio em BRL. Aparece no card do pipeline.
​
origin
string
Origem do lead. Valor livre, usado para rastrear a fonte da integração (ex: "n8n", "typeform", "google-ads"). Máximo 64 caracteres. Padrão: "api".
​
product
string
Nome do produto de interesse. Se não existir no workspace, é criado automaticamente.
​
assignedTo
string
Nome completo do atendente responsável. Deve corresponder exatamente ao nome de um membro do workspace (case-insensitive).
​
customFields
object
Campos personalizados adicionais. São convertidos em texto e adicionados às notas do contato.
"customFields": {
  "Campanha": "Black Friday 2025",
  "Interesse": "Plano Growth",
  "Score": "8.5"
}
Máximo de 50 campos por requisição. Chaves com até 64 caracteres, valores com até 512 caracteres.

​
Comportamento de upsert

O endpoint não cria duplicatas. Se um contato com o mesmo phone já existir no workspace:
  • Os campos name, email e notes são atualizados se fornecidos
  • As tags são adicionadas (não substituídas)
  • O card do pipeline é atualizado se já houver um card aberto para o contato naquele pipeline
  • A resposta retorna "action": "updated" em vez de "action": "created"

​
Resposta de sucesso

​
ok
boolean
Sempre true em caso de sucesso.
​
action
string
"created" se um novo contato foi criado, "updated" se o contato já existia.
​
contact
object
Dados do contato criado ou atualizado.
​
card
object | null
Card criado ou atualizado no pipeline. null se nenhum pipeline foi especificado ou encontrado.
curl -X POST https://crm.vistum.com.br/api/v1/leads \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "11999887766",
    "name": "João Ferreira",
    "email": "joao@empresa.com",
    "pipeline": "Vendas",
    "stage": "Qualificação",
    "value": 2500,
    "origin": "landing-page",
    "tags": ["lead-quente", "formulario-site"],
    "assignedTo": "Carlos Atendente",
    "customFields": {
      "Cidade": "São Paulo",
      "Interesse": "Plano PRO"
    }
  }'

{
  "ok": true,
  "action": "created",
  "contact": {
    "id": "cnt_cmnl5abc123",
    "name": "João Ferreira",
    "phone": "5511999887766",
    "email": "joao@empresa.com"
  },
  "card": {
    "id": "card_def456ghi",
    "stageId": "stage_xyz789",
    "origin": "landing-page"
  }
}