> ## Documentation Index
> Fetch the complete documentation index at: https://avest.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST Activity

> Crée une activité (note, tâche, appel, message, email, rendez-vous) sur une fiche existante : acquisition, vente, location ou contact.

Crée une activité sur un document **existant** — typiquement une **note sur une fiche acquéreur**, mais aussi une tâche, un appel, un message, un email ou un rendez-vous, sur une acquisition, une vente, une location ou un contact.

## Endpoint

**URL** : `/external-integration/activity`
**Méthode** : `POST`
**Authentification** : Requiert un token LinkedAPI avec scope `externalIntegration` et une clé rattachée à un groupe d'agences.
**Clé requise** : lecture-écriture. Une clé en lecture seule reçoit `403`. Voir [Types de clé](https://avest.mintlify.site/guides/authentification.md).

## Headers

```
Content-Type: application/json
Authorization: Bearer {token}
```

## Body Parameters

| Champ | Type | Requis | Description |
| - | - | - | - |
| `document` | ObjectId | ✅ | ObjectId du document auquel rattacher l'activité. |
| `documentType` | String | ✅ | Type du document. Valeurs : `acquisition`, `sale`, `rental`, `contact`. |
| `type` | String | ✅ | Type d'activité (voir liste ci-dessous). |
| `data` | Object | ✅ | Données de l'activité. Les champs attendus dépendent du `type`. |
| `deadline` | String | — | Échéance (date ISO 8601). Voir [Programmer un rappel](#programmer-un-rappel). |
| `completionDate` | String | — | Date de réalisation (ISO 8601), pour consigner une action déjà faite. |
| `owner` | ObjectId | — | Collaborateur à qui attribuer l'activité. Voir [Périmètre et attribution](#périmètre-et-attribution). |

### Types d'activité (`type`)

Seuls les types « manuels » sont créables via l'API. Les types système (changement d'étape, offre, séquence, etc.) ne le sont pas.

| `type` | Champ requis dans `data` | Description |
| - | - | - |
| `note` | `content` (String) | Note libre sur la fiche. |
| `task` | `content` (String) | Tâche / rappel. |
| `call` | `title` (String) | Compte-rendu d'appel. |
| `message` | `title` (String) | Message (SMS, WhatsApp, …). |
| `email` | `title` (String) | Email loggé manuellement. |
| `meeting` | `title` (String) | Rendez-vous / réunion. |
| `appointment` | — | Rendez-vous (aucun champ requis). |

> [!NOTE]
>
> `content` est optionnel (en plus de `title`) pour `call`, `message`, `email`
> et `meeting`. Le champ `data` est ouvert : tout champ supplémentaire pertinent
> pour le `type` est accepté.

### Mise en forme de `content`

`content` accepte du **texte brut** ou du **HTML**.

* **Texte brut** : séparez les paragraphes par une ligne vide (`\n\n`) ; un
  saut de ligne simple (`\n`) reste un retour à la ligne dans le paragraphe.
  Avest convertit ce texte en HTML à l'enregistrement (`&`, `<` et `>` sont
  échappés) : [GET Activities](https://avest.mintlify.site/endpoints/get-activities.md) vous renvoie donc la
  version HTML.
* **HTML** : pour la mise en forme (gras, listes…). Un `content` qui contient
  au moins une balise est enregistré tel quel.

```json theme={null}
{
  "data": {
    "content": "Visite du bien avec M. Martin.\n\nRappeler le 12/04 pour l'offre."
  }
}
```

| Vous envoyez | Résultat affiché |
| - | - |
| `"Ligne 1\n\nLigne 2"` | deux paragraphes |
| `"Ligne 1\nLigne 2"` | deux lignes dans un même paragraphe |
| `"<p>Ligne 1</p><p>Ligne 2</p>"` | deux paragraphes |
| `"<p>Texte <strong>en gras</strong></p>"` | mise en forme respectée |

> [!NOTE]
>
> Balises reconnues : `<p>`, `<br>`, `<strong>`, `<em>`, `<u>`, `<s>`, `<code>`,
> `<pre>`, `<ul>` / `<ol>` / `<li>`, `<h1>`–`<h3>`, `<blockquote>`, et `<a href>`
> en `http` / `https`. Le reste est nettoyé à l'affichage.

> [!WARNING]
>
> Une note saisie depuis l'interface Avest est stockée dans un format interne
> (un document d'éditeur sérialisé en JSON). **N'essayez pas de le reproduire** :
> ce format n'est pas un contrat d'API et peut changer sans préavis. Envoyez du
> texte brut ou du HTML.

## Programmer un rappel

Envoyez une **`deadline` future** et **pas** de `completionDate` : l'activité reste « à faire » et remonte dans les relances du négociateur, exactement comme un rappel créé depuis l'interface Avest.

```json theme={null}
{
  "document": "6a04a0aed4948142783f8cdf",
  "documentType": "sale",
  "type": "call",
  "data": {
    "title": "Rappeler M. Dupont",
    "content": "Relance après estimation."
  },
  "deadline": "2026-08-12T09:00:00.000Z"
}
```

À l'inverse, une `completionDate` consigne une action **déjà effectuée** — un compte-rendu d'appel saisi après coup.

> [!WARNING]
>
> Sur une vente jusqu'à l'étape `DLV`, créer un appel, une tâche, un message,
> un email ou un rendez-vous (`meeting`) clôt les autres activités à faire de
> la fiche, rendez-vous d'estimation compris. Les notes, les visites et les
> offres ne sont pas concernées.

> [!WARNING]
>
> Les deux champs s'excluent : si vous fournissez une `completionDate`, la
> `deadline` que vous envoyez est **écartée**. Une activité terminée n'a plus
> d'échéance à venir.

> [!NOTE]
>
> La réponse renvoie quand même une `deadline` : elle vaut alors la
> `completionDate`. C'est cette date que la fiche affiche (« était planifié le
> … »), pour qu'un rendez-vous consigné après coup s'affiche à sa date réelle et
> non à celle de l'appel API.

> [!NOTE]
>
> `deadline` et `completionDate` sont des **chaînes** de date ISO 8601
> (`2026-08-12T09:00:00.000Z`). Un timestamp numérique ou `null` est refusé.

Une fois le rappel honoré, soldez-le avec [PATCH Activity](https://avest.mintlify.site/endpoints/patch-activity.md) : sans cela il reste « à faire » et continue de remonter dans les relances du négociateur.

## Périmètre et attribution

* Le document doit appartenir au périmètre autorisé du token (`agencyGroup` + agences de la clé). Sinon → `403 Not authorized to access this resource`.
* Par défaut, l'activité est attribuée à l'utilisateur Avest **responsable du dossier** (l'`owner` de la fiche).
* `owner` permet de désigner **le collaborateur qui a réellement réalisé l'action** — celui qui a passé l'appel. Récupérez son ObjectId via [GET Users](https://avest.mintlify.site/endpoints/get-users.md).

L'`owner` fourni traverse **deux contrôles** :

| Contrôle | Portée | Refus |
| - | - | - |
| Appartient aux agences de votre clé | Tous les types de document | `400 ExternalIntegrationCreateActivity : owner is not in the authorized scope of this LinkedAPI` |
| Appartient à l'agence **du document visé** | Ventes (`sale`) uniquement | `400 Activity's sale owner not found owner: <userId> agency: <agencyId>` |

> [!WARNING]
>
> Le second contrôle est plus strict que le premier. Une clé qui couvre
> plusieurs agences peut très bien renvoyer, via [GET Users](https://avest.mintlify.site/endpoints/get-users.md),
> un collaborateur valide **pour la clé** mais pas **pour l'agence de la vente**
> — la requête est alors refusée et **rien n'est écrit**.

> [!NOTE]
>
> `GET /users` ne renvoie pas les agences d'un collaborateur : vous ne pouvez pas
> savoir à l'avance lequel est valide pour une vente donnée. En pratique,
> **omettez `owner`** (l'activité revient au responsable du dossier, toujours
> valide) sauf si vous savez de source sûre que le collaborateur est rattaché à
> l'agence de la fiche.

## Exemples de requête

### Note sur une fiche acquéreur

```json theme={null}
{
  "document": "6a04a0aed4948142783f8cdf",
  "documentType": "acquisition",
  "type": "note",
  "data": {
    "content": "Client recontacté, visite à planifier la semaine prochaine."
  }
}
```

### Appel sur un contact

```json theme={null}
{
  "document": "618a35a36d932054e195ca0a",
  "documentType": "contact",
  "type": "call",
  "data": {
    "title": "Appel sortant",
    "content": "Laissé un message vocal."
  }
}
```

## Réponse de succès

**Code** : `201`

```json theme={null}
{
  "success": true,
  "activity": {
    "id": "6a04a0aed4948142783f8ce0",
    "type": "note",
    "startAt": null,
    "endAt": null,
    "deadline": "2026-06-29T10:00:00.000Z",
    "completionDate": "2026-06-29T10:00:00.000Z",
    "pinned": false,
    "owner": "6939530d9200187f19a2707d",
    "linkedDocument": "6a04a0aed4948142783f8cdf",
    "linkedModel": "acquisition",
    "data": {
      "content": "Client recontacté, visite à planifier la semaine prochaine."
    },
    "file": null,
    "driveLinks": [],
    "createdAt": "2026-06-29T10:00:00.000Z",
    "updatedAt": "2026-06-29T10:00:00.000Z"
  }
}
```

L'objet `activity` retourné a la même forme que les éléments listés par `GET /external-integration/activities`.

## Réponses d'erreur

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

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

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

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationCreateActivity : documentType must be one of: acquisition, sale, rental, contact"
}
```

* **`type` non autorisé** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationCreateActivity : type must be one of: note, task, call, message, email, meeting, appointment"
}
```

* **`data` requis manquant** (selon le `type`) : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "Invalid activity data : content is required for type : note"
}
```

* **`deadline` / `completionDate` mal formée** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationCreateActivity : Invalid deadline"
}
```

* **`owner` hors du périmètre de la clé** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationCreateActivity : owner is not in the authorized scope of this LinkedAPI"
}
```

* **Header `Authorization` absent, clé en lecture seule, document lié hors périmètre, 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"
}
```

## Rate limits

Cette route est limitée à **100 req / minute par groupe d'agences** (un compteur par groupe d'agences × route : les autres routes d'écriture ont chacune le leur).

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