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

# GET Contacts

> Liste paginée de contacts par téléphone, email ou texte libre, sans les transactions associées.

Liste paginée de contacts par téléphone, email, ou texte libre. Ne retourne pas les transactions associées — uniquement les contacts.

## Endpoint

**URL** : `/external-integration/contacts`
**Méthode** : `GET`
**Authentification** : Requiert un token LinkedAPI avec `agencyGroup` configuré.
**Clé requise** : toutes les clés (lecture seule suffit). Voir [Types de clé](https://developers.avest.fr/guides/authentification.md).

## Headers

```
Authorization: Bearer {token}
```

## Query Parameters

Exactement **un** des trois paramètres suivants doit être fourni :

| Paramètre | Type | Description |
| - | - | - |
| `phone` | String | Numéro de téléphone. Formats acceptés : `+33612345678`, `0612345678`, `06 12 34 56 78`. Match exact. |
| `email` | String | Adresse email. Match exact (normalisé en minuscules). |
| `search` | String | Texte libre — **minimum 3 caractères**. Recherche sur nom, email, téléphone. Tri par pertinence. |

Paramètres supplémentaires :

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `page` | Integer | ❌ | Page 1-indexée. Défaut `1`. Max `100` |

> [!WARNING]
>
> `phone`, `email`, `search` sont **mutuellement exclusifs**. Zéro ou plus d'un
> → `400`. Toute clé de query non listée → `400`.

## Pagination

* Taille de page fixe : **100 contacts**.
* Pas de `total` retourné. Itérez jusqu'à `hasMore: false`.
* `page` max : **100** (= 10 000 contacts cumulés).
* Le champ de taille de page de la réponse s'appelle ici **`limit`** — mais **`pageSize`** sur [GET Activities](https://developers.avest.fr/endpoints/get-activities.md) et [GET Ad Search](https://developers.avest.fr/endpoints/get-ad-search.md). Même sens, deux noms : lisez celui de la route que vous appelez.

## Différences avec `/external-integration/contact`

| Aspect | `/contact` | `/contacts` |
| - | - | - |
| Résultat | Un seul contact (le plus pertinent) | Liste paginée |
| Transactions | Inclut `sales`, `acquisitions`, `rentals` | Non — uniquement les contacts |
| Pagination | Non | Oui (`page`, `hasMore`) |

## Exemples de requête

```bash theme={null}
GET /external-integration/contacts?phone=+33612345678
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/contacts?email=jean.dupont@email.com
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/contacts?search=dupont&page=2
Authorization: Bearer your-linked-api-token
```

## Réponse de succès

**Code** : `200`

```json theme={null}
{
  "success": true,
  "contacts": [
    {
      "id": "618a35a36d932054e195ca0a",
      "firstName": "Jean",
      "lastName": "Dupont",
      "contactDetails": [
        { "type": "phone", "data": "+33612345678" },
        { "type": "email", "data": "jean.dupont@email.com" }
      ]
    },
    {
      "id": "618a35a36d932054e195ca0b",
      "firstName": "Marie",
      "lastName": "Dupont",
      "contactDetails": [{ "type": "email", "data": "marie.dupont@email.com" }]
    }
  ],
  "page": 1,
  "limit": 100,
  "hasMore": false
}
```

### Aucun résultat

```json theme={null}
{
  "success": true,
  "contacts": [],
  "page": 1,
  "limit": 100,
  "hasMore": false
}
```

## Réponses d'erreur

* **Aucun paramètre fourni** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetContacts : One of phone, email, or search is required"
}
```

* **Plusieurs paramètres fournis** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetContacts : Provide exactly one of phone, email, or search"
}
```

* **Paramètre de query inconnu** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetContacts : Unsupported query parameter: foo"
}
```

* **Téléphone invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetContacts : Invalid phone number"
}
```

* **Email invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetContacts : Invalid email"
}
```

* **`search` \< 3 caractères** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetContacts : search must be at least 3 characters"
}
```

* **`page` hors limites** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetContacts : page must be <= 100"
}
```

* **LinkedAPI agencyGroup manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "LinkedAPI agencyGroup is required"
}
```

* **Header `Authorization` absent, ou IP non whitelistée sur une clé sécurisée** : `403 Not authorized to access this resource`

```json theme={null}
{
  "success": false,
  "message": "Not authorized to access this resource"
}
```

* **Token invalide** : `401 Invalid bearer token`

```json theme={null}
{
  "success": false,
  "message": "Invalid bearer token"
}
```

## Notes

1. **Mode `phone` / `email`** : matching exact. Tri par `createdAt` desc.
2. **Mode `search`** : tri par pertinence.
3. **Scope** : les contacts sont limités à votre périmètre autorisé.
4. **Pas de transactions** : utiliser `/external-integration/contact` (singulier) pour obtenir un contact + ses transactions associées.
5. Endpoint en lecture seule.

## Rate limits

Cette route est limitée à **200 req / minute par groupe d'agences** (bucket dédié).

* Headers : `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (secondes avant reset).
* Dépassement → `429 Too Many Requests` avec header `Retry-After` :

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded",
  "retryAfter": 27
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.