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

> Liste paginée des activités rattachées à un document (annonce, transaction, match ou contact).

Liste paginée des activités (notes, rendez-vous, emails, tâches, ...) rattachées à un document : annonce, vente, acquisition, location, match ou contact.

## Endpoint

**URL** : `/external-integration/activities`
**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 |
| - | - | - | - |
| `document` | ObjectId | ✅ | ObjectId du document auquel les activités sont rattachées. |
| `documentType` | String | ✅ | Type de document. Valeurs : `ad`, `acquisition`, `sale`, `rental`, `match`, `contact`. |
| `page` | Integer | ❌ | Page 1-indexée. Défaut `1`. |

> [!WARNING]
>
> `document` et `documentType` sont obligatoires.

## Pagination et tri

* Taille de page fixe : **20 activités**.
* Itérez jusqu'à `hasMore: false`.
* Tri : **`createdAt` décroissant** (activité saisie le plus récemment en premier).
* 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.

> [!WARNING]
>
> Le tri porte sur `createdAt`, **pas** sur la date métier de l'activité (par
> exemple `data.visitStartAt` pour une visite). Une visite saisie aujourd'hui
> pour une date passée remontera avant une visite saisie hier pour demain.
> Pour obtenir « la dernière visite », **triez côté client** sur le champ de
> date métier — ne prenez pas le premier élément de la liste.

## Exemples de requête

```bash theme={null}
GET /external-integration/activities?document=6a044cba8db14b3fbd015208&documentType=sale
Authorization: Bearer your-linked-api-token
```

```bash theme={null}
GET /external-integration/activities?document=618a35a36d932054e195ca0a&documentType=contact&page=2
Authorization: Bearer your-linked-api-token
```

## Réponse de succès

**Code** : `200`

```json theme={null}
{
  "success": true,
  "activities": [
    {
      "id": "6a04a0aed4948142783f8cdf",
      "type": "meeting",
      "startAt": "2026-05-20T10:00:00.000Z",
      "endAt": "2026-05-20T11:00:00.000Z",
      "deadline": "2026-05-20T11:00:00.000Z",
      "completionDate": "2026-05-20T11:05:00.000Z",
      "pinned": false,
      "owner": "6939530d9200187f19a2707d",
      "linkedDocument": "6a044cba8db14b3fbd015208",
      "linkedModel": "sale",
      "data": {
        "title": "Rendez-vous estimation",
        "content": "Visite du bien avec le vendeur"
      },
      "file": {
        "name": "compte-rendu.pdf",
        "mimetype": "application/pdf",
        "size": 102400,
        "url": "https://s3.eu-west-3.amazonaws.com/avest/activity/6a04a0aed4948142783f8cdf/compte-rendu.pdf?X-Amz-Signature=..."
      },
      "driveLinks": ["66cc8a8e75c9fac35c6ecd80"],
      "createdAt": "2026-05-13T16:02:54.888Z",
      "updatedAt": "2026-05-20T11:05:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "hasMore": false
}
```

### Aucun résultat

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

## Champs de la réponse

Chaque élément de `activities` :

| Champ | Type | Description |
| - | - | - |
| `id` | String | ObjectId Mongo de l'activité. |
| `type` | String | Type d'activité, en minuscules. Voir « Types d'activité » ci-dessous. |
| `startAt` | ISO 8601 | Date/heure de début. |
| `endAt` | ISO 8601 | Date/heure de fin. |
| `deadline` | ISO 8601 | Échéance. |
| `completionDate` | ISO 8601 | Date de complétion. |
| `pinned` | Boolean | Activité épinglée. |
| `owner` | String | ObjectId de l'utilisateur responsable. |
| `linkedDocument` | String | ObjectId du document rattaché. |
| `linkedModel` | String | Modèle du document rattaché, en minuscules : `sale`, `acquisition`, `rental`, `match`, `contact`, `ad`. |
| `data` | Object | Données de l'activité. Le contenu dépend du `type` — voir « Types d'activité » ci-dessous. |
| `file` | Object \| null | Pièce jointe : `{ name, mimetype, size, url }`. `url` est un lien S3 signé temporaire (privé), `null` si le lien n'a pas pu être généré. `file` vaut `null` quand l'activité ne porte pas de fichier stocké par Avest. |
| `driveLinks` | Array | Liste d'ObjectIds de liens drive rattachés. |
| `createdAt` | ISO 8601 | Date de création. |
| `updatedAt` | ISO 8601 | Date de dernière mise à jour. |

> [!NOTE]
>
> Aucun thumbnail n'est exposé. La pièce jointe `file.url` est un lien S3 signé
> temporaire vers un objet privé — à télécharger côté serveur, ne pas mettre en
> cache durablement.

## Types d'activité

Le champ `type` est **toujours en minuscules**. Les types ci-dessous sont ceux que
vous rencontrerez le plus souvent en lecture ; la liste n'est pas fermée et de
nouveaux types peuvent apparaître.

| `type` | Sens |
| - | - |
| `note` | Note libre. |
| `task` | Tâche. |
| `call` | Appel téléphonique. |
| `message` | Message (SMS, messagerie). |
| `email` | Email. |
| `meeting` | Rendez-vous. |
| `appointment` | Rendez-vous planifié. |
| `visit` | **Visite d'un bien** — voir [Visites & offres](https://developers.avest.fr/endpoints/visits-offers.md). |
| `offer` | **Offre d'achat** — voir [Visites & offres](https://developers.avest.fr/endpoints/visits-offers.md). |
| `visitChangeLog` | Journal des modifications d'une visite. |
| `offerChangeLog` | Journal des modifications d'une offre. |
| `changeStep` | Changement d'étape de la fiche : `data.from`, `data.to`. Sur une vente, `data.isAutomatic: true` quand Avest a changé l'étape seul (séquence de relance, par exemple). |

> [!WARNING]
>
> Traitez `type` comme un **ensemble ouvert** : ignorez silencieusement les
> valeurs que vous ne connaissez pas plutôt que de rejeter la réponse.

> [!NOTE]
>
> Les visites et les offres sont des activités rattachées au **match**. Leur
> lecture, le schéma de leur `data` et leurs limites font l'objet d'une page
> dédiée : [Visites & offres](https://developers.avest.fr/endpoints/visits-offers.md).

## Écriture : ce qui n'est pas possible

`POST /external-integration/activity` est **plus restreint que la lecture** :

* types acceptés : `note`, `task`, `call`, `message`, `email`, `meeting`,
  `appointment` uniquement ;
* `documentType` accepté : `acquisition`, `sale`, `rental`, `contact` uniquement.

> [!WARNING]
>
> Il n'est donc **pas possible de créer ni de modifier une visite ou une offre
> via l'API externe**, ni de rattacher une activité à un `match`. Ces objets sont
> aujourd'hui accessibles **en lecture seule**.

## Réponses d'erreur

* **`document` manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetActivities : document is required"
}
```

* **`documentType` manquant ou invalide** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationGetActivities : Invalid documentType"
}
```

* **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 activités rattachées à un document de votre périmètre autorisé sont retournées.
2. **Pagination** : 20 activités par page. Itérez jusqu'à `hasMore: false`.
3. **Pièces jointes** : `file.url` est un lien S3 signé temporaire vers un fichier privé. Pas de thumbnail. Testez `file` et `file.url` avant de télécharger : un document signé électroniquement, par exemple, peut remonter sans lien de téléchargement.
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.