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

> Recherche paginée d'annonces, filtrable par transaction source et par statut.

Recherche paginée d'annonces (publications de biens) de votre périmètre, filtrable par transaction source et par statut.

## Endpoint

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

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `transaction` | ObjectId | ❌ | ObjectId de la transaction source (vente / location). |
| `status` | String | ❌ | Filtre sur le statut de publication : `online`, `offline`, `archived`. |
| `page` | Integer | ❌ | Page 1-indexée. Défaut `1`. |

## Pagination

* Taille de page fixe : **50 annonces**.
* Itérez jusqu'à `hasMore: false`.
* Le champ de taille de page de la réponse s'appelle ici **`pageSize`** — mais **`limit`** sur [GET Contacts](https://developers.avest.fr/endpoints/get-contacts.md), [GET Users](https://developers.avest.fr/endpoints/get-users.md) et [GET Transaction Search](https://developers.avest.fr/endpoints/get-transaction-search.md). Même sens, deux noms : lisez celui de la route que vous appelez.

## Exemples de requête

```bash theme={null}
GET /external-integration/ad/search?status=online
Authorization: Bearer your-linked-api-token
```

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

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

## Réponse de succès

**Code** : `200`

```json theme={null}
{
  "success": true,
  "ads": [
    {
      "id": "6a044cba8db14b3fbd015208",
      "reference": "REF-2025-001",
      "status": "online",
      "adType": "sale",
      "title": "Bel appartement 3 pièces - Paris 14e",
      "propertyHousingType": "apartment",
      "surface": 65,
      "isPriceDisplayed": true,
      "salePrice": 252000,
      "location": {
        "postalCode": "75014",
        "city": "Paris",
        "country": "France",
        "isLocationDisplayed": true,
        "number": "3",
        "route": "Avenue Reille"
      },
      "pictures": [
        "https://d1234.cloudfront.net/ad/6a044cba8db14b3fbd015208/photo-1.jpg"
      ],
      "transactionType": "sale",
      "transactionModel": "Sale",
      "transactionStep": "MND",
      "owner": "6939530d9200187f19a2707d",
      "firstPublicationDate": "2026-05-13T10:04:42.139Z",
      "lastPublicationDate": "2026-05-20T08:00:00.000Z",
      "createdAt": "2026-05-13T10:04:42.139Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "hasMore": true
}
```

### Aucun résultat

```json theme={null}
{
  "success": true,
  "ads": [],
  "page": 1,
  "pageSize": 50,
  "hasMore": false
}
```

## Champs de la réponse

Chaque élément de `ads` reprend les mêmes champs que [GET Ad](https://developers.avest.fr/endpoints/get-ad.md) (`id`, `reference`, `status`, `title`, `surface`, `salePrice`, `location`, `pictures`, `transactionType`, `owner`, etc.). Les champs non renseignés sont absents de la réponse.

## Réponses d'erreur

* **`status` invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationSearchAd : Invalid status"
}
```

* **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** : seules les annonces de votre périmètre autorisé sont retournées.
2. **Pagination** : 50 annonces par page. Itérez jusqu'à `hasMore: false`.
3. **Filtres** : `transaction` et `status` sont combinables. Sans filtre, toutes les annonces du périmètre sont retournées.
4. **Médias** : les `pictures` sont des URLs CloudFront publiques.
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.