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

# Obtener contacto externo

> Consulta un contacto de tu compañía por número de teléfono

## Descripción

Este endpoint busca un contacto no de prueba de la compañía asociada a tu Company API Key. El número admite variantes habituales, como E.164 con o sin `+` y formatos internacionales de Meta. Para Argentina también admite variantes con `9` y `15`.

<Note>
  El endpoint devuelve `200` si el contacto no existe. Revisá el campo `found` antes de continuar.
</Note>

## Header de autenticación

<ParamField header="X-API-Key" type="string" required>
  Una Company API Key activa. No se admiten API keys legacy, JWT ni keys globales.
</ParamField>

## Query parameters

<ParamField query="phone" type="string" required>
  Número de teléfono que querés buscar. Recomendamos enviarlo en formato E.164, por ejemplo `+5491112345678`.
</ParamField>

## Respuesta (200 OK)

<ResponseField name="found" type="boolean">
  `true` si se encontró un contacto. `false` si no hay coincidencias.
</ResponseField>

<ResponseField name="contact" type="object | null">
  Datos del contacto. Es `null` cuando `found` es `false`.

  <Expandable title="Propiedades de contact">
    <ResponseField name="id" type="integer">
      ID interno del contacto. Usalo para actualizarlo.
    </ResponseField>

    <ResponseField name="full_name" type="string | null">
      Nombre completo del contacto.
    </ResponseField>

    <ResponseField name="email" type="string | null">
      Email del contacto.
    </ResponseField>

    <ResponseField name="phone" type="string">
      Número de teléfono del contacto.
    </ResponseField>

    <ResponseField name="source" type="string">
      Origen del contacto.
    </ResponseField>

    <ResponseField name="source_detail" type="string | null">
      Detalle del origen.
    </ResponseField>

    <ResponseField name="profile_picture" type="string | null">
      URL de la foto de perfil.
    </ResponseField>

    <ResponseField name="custom_fields" type="array">
      Todos los campos personalizados configurados para la lista del contacto.

      <Expandable title="Propiedades de cada custom field">
        <ResponseField name="id" type="integer">
          ID del campo personalizado. Usalo como `custom_field_id` al actualizar el contacto.
        </ResponseField>

        <ResponseField name="key" type="string">
          Clave interna del campo.
        </ResponseField>

        <ResponseField name="name" type="string">
          Nombre visible del campo.
        </ResponseField>

        <ResponseField name="field_type" type="string">
          Tipo del campo.
        </ResponseField>

        <ResponseField name="options" type="array | null">
          Opciones configuradas para campos de selección.
        </ResponseField>

        <ResponseField name="required" type="boolean">
          Indica si el campo es obligatorio.
        </ResponseField>

        <ResponseField name="value" type="array | null">
          Valor activo. Es `null` si aún no tiene valor o si venció.
        </ResponseField>

        <ResponseField name="version" type="integer | null">
          Versión del valor activo.
        </ResponseField>

        <ResponseField name="expires_at" type="string (ISO 8601) | null">
          Fecha y hora de vencimiento del valor activo.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --get 'https://api.mindosoftware.com/api/v1/external/contacts/' \
    --data-urlencode 'phone=+5491112345678' \
    -H 'X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Contacto encontrado theme={null}
  {
    "found": true,
    "contact": {
      "id": 123,
      "full_name": "Ana Pérez",
      "email": "ana@example.com",
      "phone": "+5491112345678",
      "source": "api",
      "source_detail": null,
      "profile_picture": "https://cdn.example.com/ana.jpg",
      "custom_fields": [
        {
          "id": 45,
          "key": "estado",
          "name": "Estado",
          "field_type": "selector",
          "options": ["nuevo", "calificado"],
          "required": false,
          "value": ["calificado"],
          "version": 2,
          "expires_at": null
        }
      ]
    }
  }
  ```

  ```json 200 - Contacto no encontrado theme={null}
  {
    "found": false,
    "contact": null
  }
  ```
</ResponseExample>

## Errores

| Estado | Situación                                                       |
| ------ | --------------------------------------------------------------- |
| `400`  | Falta el parámetro `phone`.                                     |
| `401`  | Falta una Company API Key válida, activa y no vencida.          |
| `409`  | Hay más de un contacto de tu compañía con el número consultado. |

<Warning>
  Ante un `409`, resolvé la duplicidad de contactos antes de continuar. La API no selecciona un contacto de forma arbitraria.
</Warning>