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"
}
}'
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": "21988776655",
"name": "Ana Costa",
"origin": "whatsapp-link"
}'
{
"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"
}
}
{
"ok": true,
"action": "updated",
"contact": {
"id": "cnt_cmnl5abc123",
"name": "João Ferreira",
"phone": "5511999887766",
"email": "joao@empresa.com"
},
"card": null
}
Leads
Criar lead
Cria um contato (deduplicado por telefone) e opcionalmente abre um novo negócio no pipeline. Ideal para integrações com n8n, Zapier, Google Sheets, formulários e anúncios.
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"
}
}'
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": "21988776655",
"name": "Ana Costa",
"origin": "whatsapp-link"
}'
{
"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"
}
}
{
"ok": true,
"action": "updated",
"contact": {
"id": "cnt_cmnl5abc123",
"name": "João Ferreira",
"phone": "5511999887766",
"email": "joao@empresa.com"
},
"card": null
}
Autenticação
string
required
Bearer vg_live_<sua_chave> — API Key com escopo leads:writeBody
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.string
Nome completo do contato.
string
E-mail do contato.
string
Observações internas. Aparece no campo de notas do contato no CRM.
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"]
string
Nome ou ID do pipeline onde o negócio (card) deve ser criado. Se o pipeline não for encontrado, nenhum card é criado (o contato ainda é salvo). Use o endpoint Listar Pipelines para descobrir nomes e IDs.
string
Nome ou ID da etapa do pipeline. Se omitido, o card vai para a primeira etapa do pipeline.
number
Valor do negócio em BRL. Aparece no card do pipeline.
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".string
Nome do produto de interesse. Se não existir no workspace, é criado automaticamente.
string
Nome completo do atendente responsável. Deve corresponder exatamente ao nome de um membro do workspace (case-insensitive). Use o endpoint Listar Membros para descobrir os nomes válidos.
object
Campos personalizados adicionais. São convertidos em texto e adicionados às notas do contato.Máximo de 50 campos por requisição. Chaves com até 64 caracteres, valores com até 512 caracteres.
"customFields": {
"Campanha": "Black Friday 2025",
"Interesse": "Plano Growth",
"Score": "8.5"
}
Comportamento: contato único, negócio sempre novo
A regra mais importante para entender antes de integrar:- O contato é deduplicado por telefone dentro do workspace — nunca são criados dois contatos para o mesmo número.
- O negócio (card) NÃO é deduplicado — cada chamada com
pipelinecria um card novo.
Cada chamada que inclui
pipeline cria um novo negócio (card). Mesmo que o contato já tenha um card aberto naquele pipeline, um card novo é criado — o card existente nunca é reaproveitado nem atualizado. Só o contato é único (por telefone).Se você chamar este endpoint repetidamente para o mesmo telefone com pipeline preenchido, vai acumular vários cards para o mesmo contato. Envie o pipeline apenas quando quiser de fato abrir um novo negócio; para só atualizar o contato, omita pipeline e stage.phone já existir no workspace:
- O
nameé preenchido apenas se o contato ainda não tiver nome — um nome já existente não é sobrescrito - O
emailé atualizado se fornecido - As
notessão atualizadas se fornecidas - As
tagssão adicionadas (nunca substituídas) - A resposta retorna
"action": "updated"e status200(em vez de"action": "created"com status201)
Resposta de sucesso
boolean
Sempre
true em caso de sucesso.string
"created" (status 201) se um novo contato foi criado; "updated" (status 200) se o contato já existia. Refere-se ao contato, não ao card — um card novo pode ter sido criado mesmo quando action é "updated".object
object | null
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"
}
}'
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": "21988776655",
"name": "Ana Costa",
"origin": "whatsapp-link"
}'
{
"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"
}
}
{
"ok": true,
"action": "updated",
"contact": {
"id": "cnt_cmnl5abc123",
"name": "João Ferreira",
"phone": "5511999887766",
"email": "joao@empresa.com"
},
"card": null
}