> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindosoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar contato

> Consultar informações de contato por número de telefone

## Descrição

Este endpoint permite consultar informações de contato por número de telefone. Retorna dados do contato, se ele respondeu às mensagens e o status da janela de sessão do WhatsApp.

É útil para fluxos de **envio condicional e follow-up automatizado**: antes de enviar um follow-up, você pode verificar se o contato já respondeu e se a janela de sessão está ativa.

<Note>
  O endpoint retorna `200` mesmo que o contato não exista. Use o campo `found` para verificar a existência.
</Note>

## Header de autenticação

<ParamField header="X-API-Key" type="string" required>
  Sua API Key da Mindo. Formato: `mindo_xxxxxxxxxxxxxxxxxxxxxxxx`
</ParamField>

## Parâmetros de query

<ParamField query="phone" type="string" required>
  Número de telefone a consultar. O sistema normaliza o número automaticamente, então aceita múltiplos formatos (E.164 com ou sem `+`, com `15` para Argentina, com espaços ou hífens).
</ParamField>

## Resposta (200 OK)

<ResponseField name="found" type="boolean">
  `true` se o contato existe em alguma lista da empresa.
</ResponseField>

<ResponseField name="contact" type="object">
  Informações do contato. `null` se não encontrado.

  <Expandable title="Propriedades de contact">
    <ResponseField name="id" type="integer">
      ID interno do contato.
    </ResponseField>

    <ResponseField name="fullName" type="string">
      Nome completo do contato. Pode ser `null`.
    </ResponseField>

    <ResponseField name="phone" type="string">
      Número de telefone em formato E.164.
    </ResponseField>

    <ResponseField name="email" type="string">
      E-mail do contato. Pode ser `null`.
    </ResponseField>

    <ResponseField name="contactListId" type="integer">
      ID da lista de contatos à qual pertence.
    </ResponseField>

    <ResponseField name="contactListName" type="string">
      Nome da lista de contatos.
    </ResponseField>

    <ResponseField name="source" type="string">
      Origem do contato: `manual`, `csv_import`, `organic`, `whatsapp_sync`, `instagram_sync`, `group`, `api`, `other`. Pode ser `null`.
    </ResponseField>

    <ResponseField name="createdAt" type="string (ISO 8601)">
      Data de criação do contato.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasReplied" type="boolean">
  `true` se o contato enviou pelo menos uma mensagem em algum chat. Útil para lógica de follow-up: se `false`, o contato é candidato para reenvio.
</ResponseField>

<ResponseField name="lastReplyAt" type="string (ISO 8601)">
  Data/hora da última mensagem enviada pelo contato. `null` se nunca respondeu.
</ResponseField>

<ResponseField name="sessionWindowActive" type="boolean">
  `true` se há uma janela de sessão do WhatsApp ativa (24h desde a última mensagem do usuário). Se ativa, mensagens de texto livre podem ser enviadas; caso contrário, apenas templates aprovados.
</ResponseField>

<ResponseField name="sessionExpiresAt" type="string (ISO 8601)">
  Data/hora de expiração da janela de sessão ativa. `null` se não há janela ativa.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.mindosoftware.com/api/v1/contact-lookup/?phone=5492235961983" \
    -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.mindosoftware.com/api/v1/contact-lookup/",
      params={"phone": "5492235961983"},
      headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"}
  )

  data = response.json()

  if data["found"]:
      print(f"Contato: {data['contact']['fullName']}")
      print(f"Respondeu: {data['hasReplied']}")
      print(f"Janela ativa: {data['sessionWindowActive']}")
  else:
      print("Contato não encontrado")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.mindosoftware.com/api/v1/contact-lookup/?phone=5492235961983",
    {
      headers: {
        "X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  );

  const data = await response.json();

  if (data.found) {
    console.log("Contato:", data.contact.fullName);
    console.log("Respondeu:", data.hasReplied);
    console.log("Janela ativa:", data.sessionWindowActive);
  } else {
    console.log("Contato não encontrado");
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Contato encontrado theme={null}
  {
    "found": true,
    "contact": {
      "id": 123,
      "fullName": "Juan Perez",
      "phone": "+5492235961983",
      "email": "juan@ejemplo.com",
      "contactListId": 5,
      "contactListName": "Lista Principal",
      "source": "organic",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    "hasReplied": true,
    "lastReplyAt": "2025-03-28T14:22:00Z",
    "sessionWindowActive": true,
    "sessionExpiresAt": "2025-03-29T14:22:00Z"
  }
  ```

  ```json 200 - Contato não encontrado theme={null}
  {
    "found": false,
    "contact": null,
    "hasReplied": false,
    "lastReplyAt": null,
    "sessionWindowActive": false,
    "sessionExpiresAt": null
  }
  ```

  ```json 400 - Parâmetro ausente theme={null}
  {
    "error": "El parametro 'phone' es requerido"
  }
  ```

  ```json 401 - Não autenticado theme={null}
  {
    "error": "Este endpoint requiere autenticacion con API Key (header X-API-Key)"
  }
  ```
</ResponseExample>

## Formatos de telefone aceitos

O sistema normaliza o número automaticamente. Todos estes formatos são equivalentes:

| Formato              | Exemplo               |
| -------------------- | --------------------- |
| E.164 com `+`        | `+5492235961983`      |
| E.164 sem `+`        | `5492235961983`       |
| Com `15` (Argentina) | `+54223155961983`     |
| Com `15` sem `+`     | `54223155961983`      |
| Com espaços/hífens   | `+54 223 15-596-1983` |

<Note>
  Para números fora da Argentina, use o formato E.164 com código do país.
</Note>

## Caso de uso: Follow-up condicional

<AccordionGroup>
  <Accordion title="Fluxo de follow-up automatizado">
    Fluxo típico para campanhas de follow-up:

    1. **Enviar template inicial** via [`/api/v1/meta-templates/send/`](/pt/api-reference/mensajes/enviar-mensaje)
    2. **Aguardar um período** (ex.: 24-48 horas)
    3. **Verificar status** via `/api/v1/contact-lookup/?phone=...`
    4. **Decidir ação** com base na resposta:
       * `found: false` — Contato não existe, verifique o número
       * `hasReplied: true` — Já respondeu, não enviar follow-up
       * `hasReplied: false` + `sessionWindowActive: true` — Enviar mensagem de follow-up em texto livre
       * `hasReplied: false` + `sessionWindowActive: false` — Enviar template de follow-up

    ```python Python theme={null}
    import requests

    API_KEY = "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"
    BASE_URL = "https://api.mindosoftware.com"

    # Passo 1: verificar status do contato
    lookup = requests.get(
        f"{BASE_URL}/api/v1/contact-lookup/",
        params={"phone": "5492235961983"},
        headers={"X-API-Key": API_KEY}
    ).json()

    # Passo 2: decidir ação
    if not lookup["found"]:
        print("Contato não existe na plataforma")
    elif lookup["hasReplied"]:
        print(f"Já respondeu em {lookup['lastReplyAt']}, pular follow-up")
    else:
        print("Não respondeu, enviar follow-up")
        if lookup["sessionWindowActive"]:
            print("Janela ativa: pode enviar mensagem de texto livre")
        else:
            print("Janela expirada: usar template")
    ```

    ```javascript JavaScript theme={null}
    const API_KEY = "mindo_xxxxxxxxxxxxxxxxxxxxxxxx";
    const BASE_URL = "https://api.mindosoftware.com";

    // Passo 1: verificar status do contato
    const response = await fetch(
      `${BASE_URL}/api/v1/contact-lookup/?phone=5492235961983`,
      { headers: { "X-API-Key": API_KEY } }
    );
    const lookup = await response.json();

    // Passo 2: decidir ação
    if (!lookup.found) {
      console.log("Contato não existe na plataforma");
    } else if (lookup.hasReplied) {
      console.log(`Já respondeu em ${lookup.lastReplyAt}, pular follow-up`);
    } else {
      console.log("Não respondeu, enviar follow-up");
      if (lookup.sessionWindowActive) {
        console.log("Janela ativa: pode enviar mensagem de texto livre");
      } else {
        console.log("Janela expirada: usar template");
      }
    }
    ```
  </Accordion>
</AccordionGroup>