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

# Look up contact

> Look up contact information by phone number

## Description

This endpoint allows you to look up contact information by phone number. It returns contact data, whether they have replied to messages, and the WhatsApp session window status.

It's useful for **conditional sending and automated follow-up** workflows: before sending a follow-up, you can check if the contact has already replied and if the session window is active.

<Note>
  The endpoint returns `200` even if the contact doesn't exist. Use the `found` field to verify existence.
</Note>

## Authentication header

<ParamField header="X-API-Key" type="string" required>
  Your Mindo API Key. Format: `mindo_xxxxxxxxxxxxxxxxxxxxxxxx`
</ParamField>

## Query parameters

<ParamField query="phone" type="string" required>
  Phone number to look up. The system automatically normalizes the number, so it accepts multiple formats (E.164 with or without `+`, with `15` for Argentina, with spaces or dashes).
</ParamField>

## Response (200 OK)

<ResponseField name="found" type="boolean">
  `true` if the contact exists in any company list.
</ResponseField>

<ResponseField name="contact" type="object">
  Contact information. `null` if not found.

  <Expandable title="contact properties">
    <ResponseField name="id" type="integer">
      Internal contact ID.
    </ResponseField>

    <ResponseField name="fullName" type="string">
      Contact's full name. Can be `null`.
    </ResponseField>

    <ResponseField name="phone" type="string">
      Phone number in E.164 format.
    </ResponseField>

    <ResponseField name="email" type="string">
      Contact's email. Can be `null`.
    </ResponseField>

    <ResponseField name="contactListId" type="integer">
      ID of the contact list they belong to.
    </ResponseField>

    <ResponseField name="contactListName" type="string">
      Name of the contact list.
    </ResponseField>

    <ResponseField name="source" type="string">
      Contact origin: `manual`, `csv_import`, `organic`, `whatsapp_sync`, `instagram_sync`, `group`, `api`, `other`. Can be `null`.
    </ResponseField>

    <ResponseField name="createdAt" type="string (ISO 8601)">
      Contact creation date.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasReplied" type="boolean">
  `true` if the contact has sent at least one message in any chat. Useful for follow-up logic: if `false`, the contact is a candidate for re-sending.
</ResponseField>

<ResponseField name="lastReplyAt" type="string (ISO 8601)">
  Date/time of the last message sent by the contact. `null` if they never replied.
</ResponseField>

<ResponseField name="sessionWindowActive" type="boolean">
  `true` if there's an active WhatsApp session window (24h since the user's last message). If active, free-text messages can be sent; if not, only approved templates.
</ResponseField>

<ResponseField name="sessionExpiresAt" type="string (ISO 8601)">
  Expiration date/time of the active session window. `null` if there's no active window.
</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"Contact: {data['contact']['fullName']}")
      print(f"Replied: {data['hasReplied']}")
      print(f"Window active: {data['sessionWindowActive']}")
  else:
      print("Contact not found")
  ```

  ```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("Contact:", data.contact.fullName);
    console.log("Replied:", data.hasReplied);
    console.log("Window active:", data.sessionWindowActive);
  } else {
    console.log("Contact not found");
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Contact found 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 - Contact not found theme={null}
  {
    "found": false,
    "contact": null,
    "hasReplied": false,
    "lastReplyAt": null,
    "sessionWindowActive": false,
    "sessionExpiresAt": null
  }
  ```

  ```json 400 - Missing parameter theme={null}
  {
    "error": "El parametro 'phone' es requerido"
  }
  ```

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

## Accepted phone formats

The system automatically normalizes the number. All these formats are equivalent:

| Format                | Example               |
| --------------------- | --------------------- |
| E.164 with `+`        | `+5492235961983`      |
| E.164 without `+`     | `5492235961983`       |
| With `15` (Argentina) | `+54223155961983`     |
| With `15` without `+` | `54223155961983`      |
| With spaces/dashes    | `+54 223 15-596-1983` |

<Note>
  For numbers outside Argentina, use E.164 format with country code.
</Note>

## Use case: Conditional follow-up

<AccordionGroup>
  <Accordion title="Automated follow-up workflow">
    Typical workflow for follow-up campaigns:

    1. **Send initial template** via [`/api/v1/meta-templates/send/`](/en/api-reference/mensajes/enviar-mensaje)
    2. **Wait a period** (e.g.: 24-48 hours)
    3. **Check status** via `/api/v1/contact-lookup/?phone=...`
    4. **Decide action** based on the response:
       * `found: false` — Contact doesn't exist, check the number
       * `hasReplied: true` — Already replied, don't send follow-up
       * `hasReplied: false` + `sessionWindowActive: true` — Send free-text follow-up message
       * `hasReplied: false` + `sessionWindowActive: false` — Send follow-up template

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

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

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

    # Step 2: decide action
    if not lookup["found"]:
        print("Contact doesn't exist in the platform")
    elif lookup["hasReplied"]:
        print(f"Already replied on {lookup['lastReplyAt']}, skip follow-up")
    else:
        print("Didn't reply, send follow-up")
        if lookup["sessionWindowActive"]:
            print("Window active: can send free-text message")
        else:
            print("Window expired: use template")
    ```

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

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

    // Step 2: decide action
    if (!lookup.found) {
      console.log("Contact doesn't exist in the platform");
    } else if (lookup.hasReplied) {
      console.log(`Already replied on ${lookup.lastReplyAt}, skip follow-up`);
    } else {
      console.log("Didn't reply, send follow-up");
      if (lookup.sessionWindowActive) {
        console.log("Window active: can send free-text message");
      } else {
        console.log("Window expired: use template");
      }
    }
    ```
  </Accordion>
</AccordionGroup>