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

> Récupère un utilisateur (collaborateur) par son identifiant pour résoudre un owner.

Récupère un utilisateur (collaborateur) par son identifiant. Pratique pour résoudre un `owner` (présent sur les ventes, acquisitions, locations et contacts) en nom, prénom et photo.

## Endpoint

**URL** : `/external-integration/user`
**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 |
| - | - | - | - |
| `id` | String | ✅ | Identifiant de l'utilisateur. |

> [!WARNING]
>
> `id` est obligatoire et doit être un identifiant valide → sinon `400`. Toute
> clé de query non listée → `400`.

> [!NOTE]
>
> Un collaborateur désactivé, encore rattaché à une agence du groupe, est
> renvoyé comme les autres : la réponse ne dit pas s'il est actif.

> [!TIP]
>
> **Bonne pratique** : n'appelez **pas** cette route en boucle pour résoudre
> chaque `owner` rencontré. Récupérez plutôt l'annuaire complet **une seule
> fois** via `/external-integration/users`, mettez-le en cache de votre côté, et
> faites la correspondance `id → utilisateur` localement. Réservez cette route
> aux cas ponctuels (un identifiant isolé, ou un rafraîchissement ciblé).

## Exemples de requête

```bash theme={null}
GET /external-integration/user?id=618a35a36d932054e195ca0a
Authorization: Bearer your-linked-api-token
```

## Réponse de succès

**Code** : `200`

### Utilisateur trouvé

```json theme={null}
{
  "success": true,
  "user": {
    "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"
  }
}
```

### Utilisateur non trouvé

```json theme={null}
{
  "success": true,
  "user": null
}
```

## Champs retournés

| Champ | Type | Description |
| - | - | - |
| `id` | String | Identifiant de l'utilisateur. |
| `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

* **`id` manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetUser : id is required"
}
```

* **`id` invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetUser : Invalid id"
}
```

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

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

* **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"
}
```

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

| Aspect | `/user` | `/users` |
| - | - | - |
| Résultat | Un utilisateur (par `id`) | Liste paginée de tous les users |
| Usage | Résolution ponctuelle d'un `id` | Récupération de l'annuaire complet |
| Pagination | Non | Oui (`page`, `hasMore`) |

## Notes

1. **Scope** : un utilisateur hors de votre périmètre autorisé ne sera jamais retourné (`user: null`).
2. **Croisement** : l'`id` correspond à l'identifiant `owner` des ventes, acquisitions, locations et contacts.
3. Endpoint en lecture seule.

## Rate limits

Cette route est limitée à **200 req / minute par groupe d'agences** (bucket dédié, indépendant des autres routes).

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