# 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.

Endereço: https://docs.nextags.com.br/guias/buscar-contato-por-campo/
Tipo: Guia

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](https://docs.nextags.com.br/referencia/contatos/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](https://docs.nextags.com.br/comecar/autenticacao/).
- 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](https://help.nextags.com.br/tutoriais/contatos/formato-do-telefone/).
- Para buscar por um campo personalizado: o ID do campo. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/).

## Passo a passo

### Passo 1: Busque pelo telefone

Mande `field_id=phone` e o telefone em `value`:

**Buscar pelo telefone**

```bash
curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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):

```json
{
  "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**

```bash
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"
```
```javascript
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);
```
```python
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
<?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**

```bash
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"
```
```javascript
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);
```
```python
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
<?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**

```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/referencia/contatos/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](https://docs.nextags.com.br/comecar/autenticacao/).

### 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](https://help.nextags.com.br/tutoriais/contatos/exportar-contatos/).

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
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.
```