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

# Modifier des prospects

> Changer l'étape, le setter, le closer ou le rappel d'un prospect, et lui ajouter des notes et des tags, avec une clé API.

## Clé API

Ces routes n'acceptent **pas** le jeton du webhook de leads : elles demandent une **clé API**, créée dans **Réglages → Tags & Webhook → Clés API** par un administrateur de l'espace.

* Une clé par intégration (« Zapier Telegram », « Make Calendly »…), révocable à tout moment.
* La clé n'est affichée **qu'une fois**, à sa création. Perdue, elle se révoque et se recrée.
* Elle s'envoie **uniquement** dans l'en-tête `Authorization: Bearer VOTRE_CLE`. Une clé passée dans l'URL est refusée.
* L'espace est déduit de la clé : un identifiant de prospect d'un autre espace répond `404`.

```bash theme={null}
curl https://api.scaleflow.fr/pipelines \
  -H "Authorization: Bearer VOTRE_CLE"
```

## Lister pipelines, étapes et tags

```text theme={null}
GET https://api.scaleflow.fr/pipelines
```

Renvoie les pipelines actifs avec leurs étapes, et les tags de l'espace, avec leurs identifiants.

```json 200 theme={null}
{
  "pipelines": [
    {
      "id": "190abe0c-0000-4000-8000-000000000000",
      "name": "Pipeline Complet",
      "is_default": true,
      "stages": [
        { "id": "232a96b4-0000-4000-8000-000000000000", "name": "Optin", "type": "Appointment Setting", "order": 0 },
        { "id": "9f9e6b56-0000-4000-8000-000000000000", "name": "Relance", "type": "Follow up", "order": 5 }
      ]
    }
  ],
  "tags": [{ "id": "09e923ed-0000-4000-8000-000000000000", "name": "Chaud" }]
}
```

## Modifier un prospect

```text theme={null}
PATCH https://api.scaleflow.fr/prospects/{prospect_id}
```

L'identifiant du prospect est le `prospect_id` renvoyé par le [webhook leads](/webhooks/leads). Envoyez seulement les champs à changer.

<ParamField body="stage" type="string">
  Étape : identifiant (n'importe quel pipeline de l'espace, le prospect change alors de pipeline) ou nom exact d'une étape de son pipeline actuel, sans tenir compte des majuscules.
</ParamField>

<ParamField body="setter_id" type="string | null">
  Identifiant d'un membre de l'espace, ou `null` pour retirer le setter.
</ParamField>

<ParamField body="closer_id" type="string | null">
  Identifiant d'un membre de l'espace, ou `null` pour retirer le closer.
</ParamField>

<ParamField body="follow_up_at" type="string | null">
  Date du prochain rappel, ISO 8601 avec fuseau (`2026-11-02T09:30:00+01:00`). Replanifie le prochain rappel prévu, ou en crée un s'il n'y en a pas. `null` annule le prochain rappel.
</ParamField>

```bash theme={null}
curl -X PATCH https://api.scaleflow.fr/prospects/PROSPECT_ID \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "Relance", "follow_up_at": "2026-11-02T09:30:00+01:00" }'
```

```json 200 theme={null}
{
  "id": "7f2fc974-0000-4000-8000-000000000000",
  "pipeline_id": "190abe0c-0000-4000-8000-000000000000",
  "stage_id": "9f9e6b56-0000-4000-8000-000000000000",
  "setter_id": null,
  "closer_id": null,
  "next_follow_up_at": "2026-11-02T08:30:00+00:00",
  "changed": ["stage", "follow_up"]
}
```

<Warning>
  Un prospect en **Closé** ou **Acompte** ne peut pas être déplacé par l'API, et l'API ne peut pas y faire entrer un prospect : ce passage se fait dans ScaleFlow, où la vente est saisie. Réponse `409`.
</Warning>

## Ajouter une note

```text theme={null}
POST https://api.scaleflow.fr/prospects/{prospect_id}/notes
```

<ParamField body="content" type="string" required>
  Texte brut, 10 000 caractères maximum. Une ligne vide crée un paragraphe, le HTML est affiché tel quel.
</ParamField>

<ParamField body="date" type="string">
  Date de la note (ISO 8601), pour rattraper un historique. Invalide ou future : la note prend la date de réception et un avertissement remonte dans `warnings`.
</ParamField>

Réponse `201` : `{ "id", "created_at", "warnings" }`.

## Ajouter ou retirer un tag

```text theme={null}
POST   https://api.scaleflow.fr/prospects/{prospect_id}/tags        { "tag": "Chaud" }
DELETE https://api.scaleflow.fr/prospects/{prospect_id}/tags/{tag}
```

`tag` est l'identifiant ou le nom exact d'un tag **existant** (sans tenir compte des majuscules) : l'API n'en crée pas. Réponses : `201 added`, `200 already_present`, `200 removed`, `200 absent`.

## Journal et annulation

Chaque modification faite par l'API est inscrite sur la fiche du prospect (onglet **Infos**, « Modifications par l'API »), avec la clé utilisée, la valeur avant et après. Un membre de l'équipe peut l'**annuler** d'un clic, tant que la fiche n'a pas été modifiée depuis. Le journal de chaque clé est aussi visible dans **Réglages → Tags & Webhook → Clés API**.

## Erreurs et limites

| Code | Cause |
| - | - |
| 400 | corps invalide, champ inconnu, aucun champ à modifier |
| 401 | clé absente, invalide ou révoquée |
| 403 | la clé n'a pas la portée nécessaire |
| 404 | prospect inexistant ou d'un autre espace |
| 409 | prospect en Closé ou Acompte, ou passage vers ces étapes |
| 422 | étape, tag ou membre introuvable dans l'espace |
| 429 | plus de 120 requêtes, ou plus de 30 changements d'étape, par minute et par clé |

L'API ne supprime jamais un prospect ni une note.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.