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

> Liste paginée des utilisateurs (collaborateurs) de votre périmètre — l'annuaire complet.

Liste paginée des collaborateurs de tout votre groupe d'agences, y compris ceux d'agences que votre clé ne couvre pas. La réponse ne dit pas à quelle agence chacun appartient. Permet de récupérer en une fois l'annuaire des collaborateurs : nom, prénom, téléphone, photo, fonction, statut.

## Endpoint

**URL** : `/external-integration/users`
**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

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

> [!WARNING]
>
> Toute clé de query non listée → `400`.

> [!WARNING]
>
> La liste comprend les collaborateurs **désactivés** qui restent rattachés à
> une agence du groupe, sans indicateur pour les distinguer. Avant de désigner
> un `owner`, vérifiez de votre côté que le collaborateur est toujours en poste.

## Pagination

* Taille de page fixe : **100 utilisateurs**.
* Pas de `total` retourné. Itérez jusqu'à `hasMore: false`.
* `page` max : **100**.
* 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.

> [!TIP]
>
> **Bonne pratique** : récupérez l'annuaire **une seule fois** via cette route
> (et mettez-le en cache de votre côté), plutôt que d'interroger
> `/external-integration/user?id=...` en boucle pour chaque identifiant
> rencontré. Les utilisateurs changent rarement ; un rafraîchissement périodique
> suffit.

## Exemples de requête

```bash theme={null}
GET /external-integration/users
Authorization: Bearer your-linked-api-token
```

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

## Réponse de succès

**Code** : `200`

```json theme={null}
{
  "success": true,
  "users": [
    {
      "id": "618a35a36d932054e195ca0a",
      "firstName": "Thomas",
      "lastName": "Godard",
      "phone": "+33612345678",
      "picture": "https://static.example.com/user/618a35a36d932054e195ca0a.jpg",
      "jobTitle": "Directeur",
      "agentStatus": "independent",
      "agentRegistrationNumber": "CPI 3101 2020 000 012 345"
    },
    {
      "id": "618a35a36d932054e195ca0b",
      "firstName": "Marie",
      "lastName": "Martin",
      "phone": "+33698765432",
      "jobTitle": "Conseillère",
      "agentStatus": "employee"
    }
  ],
  "page": 1,
  "limit": 100,
  "hasMore": false
}
```

### Aucun résultat

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

## Champs retournés

| Champ | Type | Description |
| - | - | - |
| `id` | String | Identifiant de l'utilisateur (à croiser avec `owner`). |
| `firstName` | String | Prénom. |
| `lastName` | String | Nom. |
| `phone` | String | Téléphone. |
| `picture` | String | URL de la photo. Absent si l'utilisateur n'en a pas. |
| `jobTitle` | String | Fonction. Absent si non renseigné. |
| `agentStatus` | String | `employee` ou `independent`. Absent si non renseigné. |
| `agentRegistrationNumber` | String | Numéro de carte professionnelle. Absent si non renseigné. |

> [!NOTE]
>
> Les champs optionnels sont omis lorsqu'ils ne sont pas renseignés.

## Réponses d'erreur

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

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

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

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetUsers : 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. **Croisement avec les transactions/contacts** : l'`id` retourné correspond à l'identifiant `owner` présent sur les ventes, acquisitions, locations et contacts. Utilisez cette route pour résoudre un `owner` en nom/prénom/photo.
2. **Scope** : les utilisateurs sont limités à votre périmètre autorisé.
3. **Tri** : par nom puis prénom.
4. Endpoint en lecture seule.

## Rate limits

Cette route est limitée à **20 req / minute par groupe d'agences** (bucket dédié). Une seule requête (ou quelques pages) suffit pour récupérer tout l'annuaire — pas besoin d'un débit élevé.

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