Buscar contato por campo personalizado

GET/contacts/find_by_custom_field

Gerada do contrato OpenAPI

Encontra contatos pelo valor de um campo: o telefone, o e-mail ou um campo personalizado. Devolve no máximo 100 contatos, os mais recentes primeiro, pela última mudança do campo. É o jeito de achar o contact_id de quem você conhece pelo telefone ou pelo e-mail: veja Encontrar um contato pelo e-mail ou telefone.

Requisição

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);

Autenticação

Mande a chave de API da conta no cabeçalho X-ACCESS-TOKEN de cada chamada. Veja Autenticação com a chave de API.

Parâmetros de consulta

field_idstringobrigatório

Onde procurar: phone (telefone), email (e-mail) ou o ID de um campo personalizado.

Exemplo: phone

valuestringobrigatório

O valor procurado. O telefone vai completo e só com números, como 5511988776655.

Exemplo: 5511988776655

Respostas

200Sucesso

Os contatos encontrados, em data.

Ver os 24 campos

dataarray de objeto Contato

Os contatos, no máximo 100, os mais recentes primeiro.

data[].idinteger

O ID do contato: o contact_id das outras chamadas.

data[].page_idinteger

O ID da conta.

data[].first_namestring

O nome.

data[].last_namestring

O sobrenome.

data[].channelinteger

O canal atual do contato: 0 Messenger, 5 WhatsApp, 8 Telegram, 9 Webchat, 10 Instagram, 17 TikTok.

data[].profile_picstring

O endereço da foto de perfil.

data[].localestring

O idioma do contato, como pt_BR.

data[].genderinteger

O gênero: 0 feminino, 1 masculino, 2 desconhecido.

data[].timezoneinteger

O fuso horário do contato, em horas em relação ao UTC (-3 em Brasília).

data[].last_sentinteger

Quando a última mensagem foi enviada ao contato, em Unix timestamp em milissegundos.

data[].last_deliveredinteger

Quando a última mensagem foi entregue ao contato, em Unix timestamp em milissegundos.

data[].last_seeninteger

Quando o contato foi visto pela última vez (Visto pela última vez, no app), em Unix timestamp em milissegundos.

data[].last_interactioninteger

Quando o contato interagiu com a conta pela última vez, em Unix timestamp em milissegundos.

data[].subscribed_datestring

Quando o contato entrou na conta, em UTC, no formato 2026-10-12 14:40:00.

data[].subscribedinteger

1 inscrito; 2 inscrição cancelada (o contato saiu das transmissões e não recebe Broadcasts). Veja Contatos que pediram para sair das transmissões.

data[].tagsarray de objeto Etiqueta

As etiquetas do contato.

data[].tags[].idinteger

O ID da etiqueta.

data[].tags[].namestring

O nome da etiqueta.

data[].custom_fieldsarray de objeto Campo personalizado

Os campos personalizados do contato, com o valor de cada um.

data[].custom_fields[].idinteger

O ID do campo.

data[].custom_fields[].namestring

O nome do campo.

data[].custom_fields[].typeinteger

O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla.

Valores: 0 1 2 3 4 5 6 7

data[].custom_fields[].valuestring ou number

O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0).

400Requisição inválida

Faltou field_id ou value, ou um deles não vale.

401Chave inválida

A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja Autenticação.

Relacionados

Este conteúdo ajudou?

Obrigado! Sua resposta ajuda a melhorar a central.

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);

{ "data": [ { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792936930000, "last_delivered": 1792936932000, "last_seen": 1792937020000, "last_interaction": 1792936680000, "subscribed_date": "2026-10-12 14:40:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } ] }

Autenticação

Parâmetros de consulta

Respostas

Relacionados

Contatos, fluxos e outros identificadores

Limites, erros e boas práticas

Criar ou atualizar um contato

Encontrar um contato pelo e-mail ou telefone

Criar contato

Consultar contato