Pipeline

5 endpoints

get/v1/pipeline/deals

Lister les opportunités du pipeline

Retourne la liste paginée des deals (opportunités) du client (cursor v2). Tri stable created_at DESC, id DESC.

Un deal n'est PAS une entité distincte en base : c'est un client_contacts ayant pipeline_stage_id IS NOT NULL. Le sous-ensemble de champs exposé est volontairement réduit aux infos pertinentes pour la vue pipeline (coordonnées + stage + valeur + score). Pour le contact complet (custom_fields, tags, notes), utiliser GET /v1/contacts/{id}.

Filtres

?stage_id (uuid) — filtre exact sur la stage du pipeline.

Pas de GET single

Aucun endpoint GET /v1/pipeline/deals/{id} n'est exposé — pour récupérer un deal individuel, utiliser GET /v1/contacts/{id} ou filtrer cette liste par ?stage_id.

Scopes requis: pipeline:read

Paramètres de requête

Nom	Type	obligatoire	Description
`stage_id`	`string`	optionnel	Filtre exact sur la stage du pipeline.

Responses

Status	Description
`200`	Liste paginée des deals.
`400`	La requête est mal formée (header manquant, JSON invalide, paramètre invalide).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/v1/pipeline/deals' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

post/v1/pipeline/deals

Placer un contact dans le pipeline

Place un contact existant dans une stage du pipeline (set pipeline_stage_id). Ne crée pas de contact — contact_id doit déjà exister et appartenir au client appelant (sinon 404 not_found). De même pour stage_id (404 not_found si la stage n'appartient pas au client).

Si le contact est déjà dans une stage, son pipeline_stage_id est écrasé par la nouvelle valeur — pas d'historique de mouvement enregistré (la table pipeline_history référence l'autre table interne contacts, pas client_contacts).

Scopes requis: pipeline:write

Corps de requête

#/components/schemas/DealCreate

Responses

Status	Description
`201`	Deal placé dans le pipeline.
`400`	Validation des paramètres ou du body a échoué.
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`415`	Le header `Content-Type` est manquant ou non supporté pour cet endpoint.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X POST 'https://app.capturia.io/api/v1/pipeline/deals' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "contact_id": "8f3b1a2c-9d4e-4f5a-b6c7-d8e9f0a1b2c3",
  "stage_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}'

patch/v1/pipeline/deals/{id}

Déplacer un deal vers une autre stage

Déplace un deal (pipeline_stage_id) vers une nouvelle stage. Seul le déplacement de stage est exposé via cet endpoint — pour modifier les autres champs du deal (email, deal_value, etc.) utiliser PATCH /v1/contacts/{id}.

Préconditions

Le deal cible doit exister, appartenir au client appelant, et avoir pipeline_stage_id IS NOT NULL — sinon 404 not_found.
La stage cible doit appartenir au client appelant — sinon 404 not_found.

Scopes requis: pipeline:write

Corps de requête

#/components/schemas/DealUpdate

Responses

Status	Description
`200`	Deal déplacé vers la nouvelle stage.
`400`	Validation des paramètres ou du body a échoué.
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`415`	Le header `Content-Type` est manquant ou non supporté pour cet endpoint.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X PATCH 'https://app.capturia.io/api/v1/pipeline/deals/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "stage_id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
}'

delete/v1/pipeline/deals/{id}

Retirer un deal du pipeline

Retire le deal du pipeline en mettant pipeline_stage_id = NULL. Le contact n'est PAS supprimé — il reste accessible via GET /v1/contacts/{id}. Pour supprimer définitivement le contact, utiliser DELETE /v1/contacts/{id}.

Le deal cible doit exister, appartenir au client appelant, et avoir pipeline_stage_id IS NOT NULL — sinon 404 not_found.

Scopes requis: pipeline:write

Responses

Status	Description
`200`	Deal retiré du pipeline (le contact n'est pas supprimé).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X DELETE 'https://app.capturia.io/api/v1/pipeline/deals/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

get/v1/pipeline/stages

Lister les stages du pipeline

Retourne la liste complète des stages du pipeline du client, triées par stage_order ASC. Chaque stage est enrichie d'un compteur contact_count calculé en temps réel (nombre de contacts du client actuellement positionnés sur cette stage — utile pour les KPI de pipeline).

Réponse non-paginée

L'endpoint retourne toutes les stages du client en un seul appel (généralement < 20 par client, max 50). Le format de réponse reste compatible list V2 pour la cohérence des intégrations (pagination.next_cursor=null, pagination.has_more=false, pagination.limit et pagination.total_count égalent le nombre de stages retournées).

Lecture seule

Création / édition / réordonnancement des stages passe par le dashboard — aucun endpoint POST/PATCH/DELETE /v1/pipeline/stages n'est exposé.

Scopes requis: pipeline:read

Responses

Status	Description
`200`	Liste complète des stages du pipeline (non-paginée).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/v1/pipeline/stages' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'