Encontrar um contato pelo e-mail ou telefone

Ache o contato pelo telefone, pelo e-mail ou pelo valor de um campo personalizado, e saiba o que fazer quando a busca traz mais de um resultado.

Guia6 min

Atualizado em 26/10/2026

A API não tem uma lista de contatos: para achar alguém, você busca pelo valor de um campo. A mesma chamada, Buscar contato por campo personalizado, procura pelo telefone, pelo e-mail ou por qualquer campo personalizado, e devolve até 100 contatos, os de mudança mais recente no campo primeiro.

Antes de começar

A chave de API na variável de ambiente NEXTAGS_API_KEY. Veja Autenticação com a chave de API.
O valor do jeito que ele está salvo na NexTags. O telefone vai completo e só com números, como 5511988776655. Veja O formato certo do telefone.
Para buscar por um campo personalizado: o ID do campo. Veja Contatos, fluxos e outros identificadores.

Passo a passo

Passo 1: Busque pelo telefone

Mande field_id=phone e o telefone em value:

Buscar pelo telefone

curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({
  field_id: 'phone',
  value: '5511988776655',
})}`, {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/find_by_custom_field",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    params={
        "field_id": "phone",
        "value": "5511988776655",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/find_by_custom_field?' . http_build_query([
    'field_id' => 'phone',
    'value' => '5511988776655',
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Os contatos vêm na lista data, com o id, o nome, o canal, as etiquetas e os campos de cada um (aqui, resumido):

{
  "data": [
    {
      "id": 123456789,
      "first_name": "Ana",
      "last_name": "Souza",
      "channel": 5,
      "subscribed_date": "2026-10-20 14:40:00",
      "tags": [{"id": 2001, "name": "cliente-vip"}],
      "custom_fields": [
        {"id": 3001, "name": "cidade", "type": 0, "value": "São Paulo"}
      ]
    }
  ]
}

Se data vier vazia ou não vier, a busca não achou ninguém com esse telefone.

Passo 2: Busque pelo e-mail

Mande field_id=email e o e-mail em value:

Buscar pelo e-mail

curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=email&value=ana%40exemplo.com.br" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({
  field_id: 'email',
  value: 'ana@exemplo.com.br',
})}`, {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/find_by_custom_field",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    params={
        "field_id": "email",
        "value": "ana@exemplo.com.br",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/find_by_custom_field?' . http_build_query([
    'field_id' => 'email',
    'value' => 'ana@exemplo.com.br',
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Passo 3: Busque por um campo personalizado

Mande o ID do campo em field_id. Um campo que identifica a pessoa, como o código do cliente no seu sistema, traz um contato só; um campo como a cidade traz vários:

Buscar pela cidade

curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=3001&value=S%C3%A3o%20Paulo" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({
  field_id: '3001',
  value: 'São Paulo',
})}`, {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/find_by_custom_field",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    params={
        "field_id": "3001",
        "value": "São Paulo",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/find_by_custom_field?' . http_build_query([
    'field_id' => '3001',
    'value' => 'São Paulo',
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Os exemplos codificam o valor na URL: o espaço vira %20 ou +, e o ã vira %C3%A3. Faça o mesmo no seu código. Um + de verdade, como o de um telefone salvo com +55, precisa ir como %2B; sem codificar, ele vira espaço.

Passo 4: Escolha o contato certo quando vierem vários

A busca traz até 100 contatos, os de mudança mais recente no campo primeiro. Isso acontece com campos que se repetem (cidade, plano) e pode acontecer também quando a mesma pessoa tem um contato em cada canal. Escolha pelo que o seu sistema sabe: o canal, o nome ou outro campo. Nunca atualize todos os resultados de uma vez.

Escolher o contato

const consulta = new URLSearchParams({ field_id: 'phone', value: '5511988776655' });
const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${consulta}`, {
  headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY },
});
const { data = [] } = await resposta.json();
// prefere o contato do WhatsApp (channel 5); senão, o primeiro, que é o de mudança mais recente
const contato = data.find((c) => c.channel === 5) || data[0] || null;
console.log(data.length, contato && contato.id);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/find_by_custom_field",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    params={"field_id": "phone", "value": "5511988776655"},
    timeout=30,
)
lista = resposta.json().get("data") or []
# prefere o contato do WhatsApp (channel 5); senão, o primeiro, que é o de mudança mais recente
contato = next((c for c in lista if c.get("channel") == 5), lista[0] if lista else None)
print(len(lista), contato and contato["id"])

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/find_by_custom_field?' . http_build_query([
    'field_id' => 'phone',
    'value' => '5511988776655',
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$lista = json_decode(curl_exec($ch), true)['data'] ?? [];
// prefere o contato do WhatsApp (channel 5); senão, o primeiro, que é o de mudança mais recente
$contato = $lista[0] ?? null;
foreach ($lista as $item) {
    if (($item['channel'] ?? null) === 5) {
        $contato = $item;
        break;
    }
}
echo count($lista), ' ', $contato['id'] ?? '-', PHP_EOL;

O channel de cada contato: 5 WhatsApp, 10 Instagram, 0 Messenger, 8 Telegram, 9 webchat e 17 TikTok.

Pronto: como conferir

A busca devolve o contato esperado em data, com o id que você vai usar nas próximas chamadas.
Confira o contato pelo ID com Consultar contato (GET /contacts/123456789).

Se não funcionou

401 com "No valid API key provided."

A chave não chegou ou não vale. Veja Autenticação com a chave de API.

400 com "Invalid parameters"

Falta o field_id ou o value. Os dois são obrigatórios.

Não acha um contato que existe

O telefone pode estar salvo noutro formato, sem o 55, com + ou sem o 9, e não foi conferido se a busca acha esses casos. Tente o e-mail, confira como o telefone aparece no painel do contato e padronize os telefones do seu sistema.

Vieram contatos de mais

O campo se repete entre contatos. Busque por um campo que identifique a pessoa (telefone, e-mail ou um código seu) ou escolha entre os resultados, como no passo 4.

Falta alguém numa busca com muitos resultados

A busca traz no máximo 100 contatos e não tem paginação. Para listas grandes, use um campo mais específico ou exporte os contatos na tela. Veja Exportar contatos.

Faça com a IA

Copie o pedido e cole no ChatGPT ou no Claude.

Leia https://docs.nextags.com.br/guias/buscar-contato-por-campo.md.

Escreva, em [linguagem], uma função que acha o contato da NexTags de um cliente do [seu sistema]: procura pelo telefone (formato 55 + DDD + número, só números), depois pelo e-mail se não achar, e, quando vierem vários, escolhe [o critério, por exemplo: o do WhatsApp]. A chave vem da variável de ambiente NEXTAGS_API_KEY. Devolva o ID do contato ou nada.

Obrigado! Sua resposta ajuda a melhorar a central.