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

> Recherche un contact par téléphone, email ou texte libre et retourne ses transactions associées.

Recherche un contact par téléphone, email, ou texte libre, et retourne ses transactions associées (ventes, acquisitions, locations).

## Endpoint

**URL** : `/external-integration/contact`
**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. Retourne le meilleur résultat. |

> [!WARNING]
>
> Les trois paramètres sont **mutuellement exclusifs**. Zéro ou plus d'un →
> `400`. Toute clé de query non listée → `400`.

## Exemples de requête

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

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

```bash theme={null}
GET /external-integration/contact?search=jean+dupont
Authorization: Bearer your-linked-api-token
```

## Réponse de succès

**Code** : `200`

### Contact trouvé

```json theme={null}
{
  "success": true,
  "contact": {
    "id": "618a35a36d932054e195ca0a",
    "firstName": "Jean",
    "lastName": "Dupont",
    "contactDetails": [
      { "type": "phone", "data": "+33612345678" },
      { "type": "email", "data": "jean.dupont@email.com" }
    ]
  },
  "sales": [
    {
      "id": "619b46b47e043165f206db1b",
      "customId": "V-2025-001",
      "step": "QUL",
      "project": "B"
    }
  ],
  "acquisitions": [
    {
      "id": "619b46b47e043165f206db1c",
      "customId": "A-2025-001",
      "step": "AQUL",
      "project": "B"
    }
  ],
  "rentals": []
}
```

### Contact non trouvé

```json theme={null}
{
  "success": true,
  "contact": null,
  "sales": [],
  "acquisitions": [],
  "rentals": []
}
```

## Réponses d'erreur

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

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

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

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

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

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

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

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

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

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

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

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

* **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`** : match exact. Retourne `null` si aucun contact ne correspond.
2. **Mode `search`** : retourne le meilleur résultat selon la pertinence. Si plusieurs contacts matchent, seul le plus pertinent est retourné — utiliser `phone` ou `email` pour un match déterministe.
3. **Scope** : les résultats sont limités à votre périmètre autorisé. Un contact hors périmètre ne sera jamais retourné.
4. **Transactions** : seules les transactions où le contact est rattaché sont retournées. Les fiches de `sales`, `acquisitions` et `rentals` sont un résumé dont la forme peut évoluer : lisez-y `id`, `customId`, `step` et `project`, et récupérez le détail au format public avec [GET Sale](https://developers.avest.fr/endpoints/get-sale.md), [GET Acquisition](https://developers.avest.fr/endpoints/get-acquisition.md) ou [GET Rental](https://developers.avest.fr/endpoints/get-rental.md).
5. Endpoint en lecture seule.

## Rate limits

Cette route est limitée à **500 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.