curl --request POST \
--url https://app.metricaas.com.br/v1/leads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phone": "11987654321",
"email": "ana@exemplo.com",
"name": "Ana Lima",
"origem": "form",
"campos": {
"data_de_nascimento": "1988-03-21"
},
"tags": [
"Lead"
],
"stage": "Lead",
"utm": {
"utm_source": "instagram",
"utm_medium": "dm",
"utm_campaign": "mapa-cabalistico-nome_desenho"
},
"visita_codigo": "K7M2PQ"
}
'import requests
url = "https://app.metricaas.com.br/v1/leads"
payload = {
"phone": "11987654321",
"email": "ana@exemplo.com",
"name": "Ana Lima",
"origem": "form",
"campos": { "data_de_nascimento": "1988-03-21" },
"tags": ["Lead"],
"stage": "Lead",
"utm": {
"utm_source": "instagram",
"utm_medium": "dm",
"utm_campaign": "mapa-cabalistico-nome_desenho"
},
"visita_codigo": "K7M2PQ"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phone: '11987654321',
email: 'ana@exemplo.com',
name: 'Ana Lima',
origem: 'form',
campos: {data_de_nascimento: '1988-03-21'},
tags: ['Lead'],
stage: 'Lead',
utm: {
utm_source: 'instagram',
utm_medium: 'dm',
utm_campaign: 'mapa-cabalistico-nome_desenho'
},
visita_codigo: 'K7M2PQ'
})
};
fetch('https://app.metricaas.com.br/v1/leads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.metricaas.com.br/v1/leads",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone' => '11987654321',
'email' => 'ana@exemplo.com',
'name' => 'Ana Lima',
'origem' => 'form',
'campos' => [
'data_de_nascimento' => '1988-03-21'
],
'tags' => [
'Lead'
],
'stage' => 'Lead',
'utm' => [
'utm_source' => 'instagram',
'utm_medium' => 'dm',
'utm_campaign' => 'mapa-cabalistico-nome_desenho'
],
'visita_codigo' => 'K7M2PQ'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.metricaas.com.br/v1/leads"
payload := strings.NewReader("{\n \"phone\": \"11987654321\",\n \"email\": \"ana@exemplo.com\",\n \"name\": \"Ana Lima\",\n \"origem\": \"form\",\n \"campos\": {\n \"data_de_nascimento\": \"1988-03-21\"\n },\n \"tags\": [\n \"Lead\"\n ],\n \"stage\": \"Lead\",\n \"utm\": {\n \"utm_source\": \"instagram\",\n \"utm_medium\": \"dm\",\n \"utm_campaign\": \"mapa-cabalistico-nome_desenho\"\n },\n \"visita_codigo\": \"K7M2PQ\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.metricaas.com.br/v1/leads")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"phone\": \"11987654321\",\n \"email\": \"ana@exemplo.com\",\n \"name\": \"Ana Lima\",\n \"origem\": \"form\",\n \"campos\": {\n \"data_de_nascimento\": \"1988-03-21\"\n },\n \"tags\": [\n \"Lead\"\n ],\n \"stage\": \"Lead\",\n \"utm\": {\n \"utm_source\": \"instagram\",\n \"utm_medium\": \"dm\",\n \"utm_campaign\": \"mapa-cabalistico-nome_desenho\"\n },\n \"visita_codigo\": \"K7M2PQ\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.metricaas.com.br/v1/leads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone\": \"11987654321\",\n \"email\": \"ana@exemplo.com\",\n \"name\": \"Ana Lima\",\n \"origem\": \"form\",\n \"campos\": {\n \"data_de_nascimento\": \"1988-03-21\"\n },\n \"tags\": [\n \"Lead\"\n ],\n \"stage\": \"Lead\",\n \"utm\": {\n \"utm_source\": \"instagram\",\n \"utm_medium\": \"dm\",\n \"utm_campaign\": \"mapa-cabalistico-nome_desenho\"\n },\n \"visita_codigo\": \"K7M2PQ\"\n}"
response = http.request(request)
puts response.read_body{
"id": "0f6c8e1a-1b2c-4d5e-8f90-1234567890ab",
"criado": false,
"mudou": [
"email",
"campos.data_de_nascimento"
],
"campos_ignorados": [
"inventado"
],
"tags_ignoradas": [],
"visita_ligada": false
}{
"id": "0f6c8e1a-1b2c-4d5e-8f90-1234567890ab",
"criado": true,
"mudou": [],
"campos_ignorados": [],
"tags_ignoradas": [],
"visita_ligada": true
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}Cria ou atualiza um lead (upsert)
Acha o lead pelo telefone (DDD + 8 últimos dígitos, como o GET) ou
pelo e-mail (sem caixa) — ou pelo visita_codigo — e cria se não
existir. Precisa de token de escrita com crm:operate.
Nunca piora o que já existe: nome e e-mail só preenchem o vazio;
campos trocam o valor das chaves enviadas; tags só são
acrescentadas; stage só move para uma etapa aberta (ganho é
POST /v1/sales, que cria a venda e manda o Purchase; perdido pede o
motivo, pela ficha ou pelo MCP). O telefone de um lead que já existe
não muda.
Lead novo precisa de telefone. O telefone é a identidade do canal
(é por ele que a conversa de WhatsApp casa com o lead). O e-mail
sozinho acha quem já existe, mas não cria — 422.
campos só aceita chaves que existem (as outras voltam em
campos_ignorados), e o valor é validado pelo tipo, como na ficha
(data aaaa-mm-dd, número, opção da lista): valor inválido é 422 e
nada é gravado. tags só aplica tags que existem
(tags_ignoradas); crie com POST /v1/tags.
visita_codigo mantém a atribuição de anúncio:
- 6 caracteres = o código do envio do formulário do MetricaaS
(
mtc.lead): o lead daquele envio é o lead, e ele já nasceu com o clique e o anúncio; - 9 caracteres = o código da visita da tag
m.js: o lead novo nasce com esse clique (UTMs,fbc/fbp, página). Lead que já existe e não tem clique também o ganha; quem já tem, mantém (a origem é o primeiro toque).
Sem código, um lead novo com utm ganha um clique com essas UTMs.
Webhooks: lead.created na criação; lead.updated quando algo
mudou num lead que já existia; lead.stage_changed quando a etapa mudou.
Telefone que já é de um lead fora do alcance deste token (de outra
pessoa, de outro canal ou excluído): 404, e nada é criado.
curl --request POST \
--url https://app.metricaas.com.br/v1/leads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phone": "11987654321",
"email": "ana@exemplo.com",
"name": "Ana Lima",
"origem": "form",
"campos": {
"data_de_nascimento": "1988-03-21"
},
"tags": [
"Lead"
],
"stage": "Lead",
"utm": {
"utm_source": "instagram",
"utm_medium": "dm",
"utm_campaign": "mapa-cabalistico-nome_desenho"
},
"visita_codigo": "K7M2PQ"
}
'import requests
url = "https://app.metricaas.com.br/v1/leads"
payload = {
"phone": "11987654321",
"email": "ana@exemplo.com",
"name": "Ana Lima",
"origem": "form",
"campos": { "data_de_nascimento": "1988-03-21" },
"tags": ["Lead"],
"stage": "Lead",
"utm": {
"utm_source": "instagram",
"utm_medium": "dm",
"utm_campaign": "mapa-cabalistico-nome_desenho"
},
"visita_codigo": "K7M2PQ"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phone: '11987654321',
email: 'ana@exemplo.com',
name: 'Ana Lima',
origem: 'form',
campos: {data_de_nascimento: '1988-03-21'},
tags: ['Lead'],
stage: 'Lead',
utm: {
utm_source: 'instagram',
utm_medium: 'dm',
utm_campaign: 'mapa-cabalistico-nome_desenho'
},
visita_codigo: 'K7M2PQ'
})
};
fetch('https://app.metricaas.com.br/v1/leads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.metricaas.com.br/v1/leads",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone' => '11987654321',
'email' => 'ana@exemplo.com',
'name' => 'Ana Lima',
'origem' => 'form',
'campos' => [
'data_de_nascimento' => '1988-03-21'
],
'tags' => [
'Lead'
],
'stage' => 'Lead',
'utm' => [
'utm_source' => 'instagram',
'utm_medium' => 'dm',
'utm_campaign' => 'mapa-cabalistico-nome_desenho'
],
'visita_codigo' => 'K7M2PQ'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.metricaas.com.br/v1/leads"
payload := strings.NewReader("{\n \"phone\": \"11987654321\",\n \"email\": \"ana@exemplo.com\",\n \"name\": \"Ana Lima\",\n \"origem\": \"form\",\n \"campos\": {\n \"data_de_nascimento\": \"1988-03-21\"\n },\n \"tags\": [\n \"Lead\"\n ],\n \"stage\": \"Lead\",\n \"utm\": {\n \"utm_source\": \"instagram\",\n \"utm_medium\": \"dm\",\n \"utm_campaign\": \"mapa-cabalistico-nome_desenho\"\n },\n \"visita_codigo\": \"K7M2PQ\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.metricaas.com.br/v1/leads")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"phone\": \"11987654321\",\n \"email\": \"ana@exemplo.com\",\n \"name\": \"Ana Lima\",\n \"origem\": \"form\",\n \"campos\": {\n \"data_de_nascimento\": \"1988-03-21\"\n },\n \"tags\": [\n \"Lead\"\n ],\n \"stage\": \"Lead\",\n \"utm\": {\n \"utm_source\": \"instagram\",\n \"utm_medium\": \"dm\",\n \"utm_campaign\": \"mapa-cabalistico-nome_desenho\"\n },\n \"visita_codigo\": \"K7M2PQ\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.metricaas.com.br/v1/leads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone\": \"11987654321\",\n \"email\": \"ana@exemplo.com\",\n \"name\": \"Ana Lima\",\n \"origem\": \"form\",\n \"campos\": {\n \"data_de_nascimento\": \"1988-03-21\"\n },\n \"tags\": [\n \"Lead\"\n ],\n \"stage\": \"Lead\",\n \"utm\": {\n \"utm_source\": \"instagram\",\n \"utm_medium\": \"dm\",\n \"utm_campaign\": \"mapa-cabalistico-nome_desenho\"\n },\n \"visita_codigo\": \"K7M2PQ\"\n}"
response = http.request(request)
puts response.read_body{
"id": "0f6c8e1a-1b2c-4d5e-8f90-1234567890ab",
"criado": false,
"mudou": [
"email",
"campos.data_de_nascimento"
],
"campos_ignorados": [
"inventado"
],
"tags_ignoradas": [],
"visita_ligada": false
}{
"id": "0f6c8e1a-1b2c-4d5e-8f90-1234567890ab",
"criado": true,
"mudou": [],
"campos_ignorados": [],
"tags_ignoradas": [],
"visita_ligada": true
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}Authorizations
Authorization: Bearer mcp_… — gere em Configurações → Tokens de API.
O token de API tem modo read ou write. Um token read responde 403
a qualquer verbo que não seja GET. As capacidades do token são a
interseção com as da pessoa de quem ele herda o papel: se ela perder
acesso na grade de Equipe, o token perde junto, sem ninguém revogar nada.
Token de agência (gerado no console da agência): vale para as
empresas da agência, e a empresa de cada chamada vai no header
X-Empresa: <slug da empresa>. Sem o header, 401. Num token de
empresa o header é opcional e, se vier, tem de ser a própria empresa. O
modo read vale igual: um token de agência de leitura só faz GET —
é o token para pôr numa função que só consulta.
Body
Response
Já existia (mudou diz o que mudou; vazio = nada)