> ## 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 Match Search

> Recherche les matchs rattachés à une vente et/ou une acquisition.

Recherche les matchs (rapprochements acquisition / vente) rattachés à une vente et/ou une acquisition.

## Endpoint

**URL** : `/external-integration/match/search`
**Méthode** : `GET`
**Authentification** : Requiert un token LinkedAPI avec scope `externalIntegration` et une clé rattachée à un groupe d'agences.
**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

Au moins **un** des deux paramètres suivants doit être fourni :

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `sale` | ObjectId | ✅\* | ObjectId de la vente à matcher. |
| `acquisition` | ObjectId | ✅\* | ObjectId de l'acquisition à matcher. |

> [!WARNING]
>
> Au moins un des deux paramètres (`sale` ou `acquisition`) doit être fourni.
> Les deux peuvent être fournis simultanément.

## Exemples de requête

```bash theme={null}
GET /external-integration/match/search?sale=6a044cba8db14b3fbd015208
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/match/search?acquisition=6a04a0aed4948142783f8ce0
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/match/search?sale=6a044cba8db14b3fbd015208&acquisition=6a04a0aed4948142783f8ce0
Authorization: Bearer your-linked-api-token
```

## Réponse de succès

**Code** : `200`

Les matchs sont retournés triés par `createdAt` décroissant (les plus récents en premier), dans la limite de **200 résultats**.

```json theme={null}
{
  "success": true,
  "matches": [
    {
      "id": "6a04a0aed4948142783f8cdf",
      "customId": "M-2025-001",
      "step": "MRQT",
      "origin": "manual",
      "sale": "6a044cba8db14b3fbd015208",
      "acquisition": "6a04a0aed4948142783f8ce0",
      "tags": ["66cc8a8e75c9fac35c6ecd80"],
      "createdAt": "2026-05-13T16:02:54.888Z"
    }
  ]
}
```

### Aucun résultat

```json theme={null}
{
  "success": true,
  "matches": []
}
```

## Champs de la réponse

Chaque élément de `matches` :

| Champ | Type | Description |
| - | - | - |
| `id` | String | ObjectId Mongo du match. |
| `customId` | String | Identifiant métier du match. |
| `step` | String | Étape courante du match. Voir [Étapes du match](https://developers.avest.fr/endpoints/get-match.md). |
| `origin` | String | Origine du match. Voir [Origines](https://developers.avest.fr/endpoints/get-match.md). |
| `sale` | String | ObjectId de la vente rapprochée. |
| `acquisition` | String | ObjectId de l'acquisition rapprochée. |
| `tags` | Array | Liste d'ObjectIds des tags rattachés au match. |
| `createdAt` | ISO 8601 | Date de création du match. |

## Réponses d'erreur

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

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchMatch : Either sale or acquisition is required"
}
```

* **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. **Scope** : seuls les matchs de votre périmètre autorisé sont retournés.
2. **Limite** : au maximum 200 matchs sont retournés, triés par `createdAt` décroissant.
3. **Croisement** : `sale` et `acquisition` sont les ObjectIds à utiliser avec `GET /external-integration/sale` et `GET /external-integration/acquisition`.
4. 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.