L’API FantomHunt, appel par appel.

Lisez tout votre suivi, écrivez des notes, des tâches et des affaires, envoyez et utilisez l’IA depuis vos outils. Chaque appel est décrit tel que le serveur le traite aujourd’hui, avec ses droits, ses limites et ses erreurs.

120 requêtes par minute et par clé
39 appels de lecture
Erreurs à code stable

Ouvrir l’API avec Essentiel

29 € par mois, sans engagement · lecture seule par défaut · Déjà client : Paramètres › API

Mis à jour le 3 octobre 2026 · API v1

Votre clé API, vérifiée en un appel.

Pour obtenir une clé API FantomHunt, ouvrez Paramètres, onglet API, puis « Créer une clé » : elle commence par fh_live_ et ne s’affiche qu’une fois. Donnez-lui le nom de l’outil qui l’utilisera et cochez seulement les droits utiles. Vérifiez-la avec GET /v1/moi, qui répond votre offre, les droits de la clé et vos crédits restants.

Créer la clé, puis la vérifier

Ouvrez Paramètres › API dans votre espace FantomHunt, puis « Créer une clé ». L’écran existe sur toutes les offres ; la création demande Essentiel ou Croissance.
Nommez la clé d’après l’outil qui l’utilisera (« HubSpot par Zapier », « Claude Code »). Laissez-la en lecture, ou cochez seulement les droits utiles (tableau ci-dessous). Copiez-la : elle ne s’affichera plus.
Vérifiez-la avec l’appel ci-dessous : il répond votre offre, les droits de la clé, vos crédits et vos invitations du mois.

L’offre est revérifiée à chaque appel : un compte repassé en Découverte perd l’accès, même avec une clé active.

Vérifier la clé

curl "https://api.fantomhunt.com/v1/moi" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (200)

{
  "compte": {
    "email": "vous@entreprise.fr",
    "plan": "essentiel",
    "cree_le": "2026-09-12T08:30:00.000Z"
  },
  "cle": {
    "nom": "HubSpot par Zapier",
    "prefixe": "fh_live_a1b2",
    "portee": "lecture",
    "droits": ["lecture"]
  },
  "credits": {
    "ia": { "restants": 362, "par_mois": 400 },
    "contact": { "restants": 41.5, "par_mois": 50 }
  },
  "prospects": { "utilises": 1240, "limite": null },
  "invitations_linkedin": { "envoyees": 312, "par_mois": 800 }
}

Ce qu’il faut pour brancher l’API

Une offre payanteEssentiel ou Croissance.
- Essentiel : 29 € par mois sans engagement
- ou 19 € par mois avec engagement d’un an
- API, webhooks et MCP compris
API, webhooks et MCP dès Essentiel
Une clé par outilCréée dans Paramètres › API, nommée selon l’outil, avec ses droits.
- Lecture seule par défaut
- 10 clés actives au plus
- Révocable sans toucher aux autres
Créer votre clé et choisir ses droits
L’extension, pour LinkedInMessages, invitations et recherches LinkedIn partent par l’extension, navigateur ouvert.
- Votre session, sans mot de passe à confier
- Mêmes plafonds que l’application
- Réponse 202 : l’envoi est en file
Les envois LinkedIn partent par l’extension
Vos canaux connectésWhatsApp et votre boîte email, pour envoyer sur ces canaux.
- Sinon : 409 canal_deconnecte
- Rien n’est parti dans ce cas
- Réponse 201 : le message est parti
Ce que l’API, les webhooks et le MCP permettent

Une adresse, une clé, des réponses prévisibles.

L’API FantomHunt est une API REST : une adresse, https://api.fantomhunt.com/v1, une clé dans l’en-tête Authorization: Bearer fh_live_…, des réponses en JSON. Chaque clé accepte 120 requêtes par minute ; les listes de prospects et de contacts se paginent par curseur ; chaque erreur porte un code stable et un message en français.

Adresse: https://api.fantomhunt.com/v1
Clé: fh_live_ suivi de 40 caractères, montrée une seule fois à la création, gardée en empreinte SHA-256, jamais en clair. 10 clés actives par compte. Révoquée, elle cesse à la requête suivante, et ce qu’elle avait lancé sans être encore parti (inscriptions, envois en file, recherches) est mis en pause. L’offre est revérifiée à chaque appel : un compte repassé en Découverte perd l’accès. Voir créer votre clé et choisir ses droits.
Droits: lecture toujours ; messages, crm, envoyer et credits décochés par défaut.
Débit: 120 requêtes par minute et par clé, 600 par minute et par adresse ; en-têtes RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset sur chaque réponse.
Pagination: { donnees, curseur_suivant } pour les prospects et les contacts : limite 50 par défaut, 200 au plus ; curseur_suivant vaut null à la dernière page. Les tâches et les prospects d’une campagne acceptent limite (200 par défaut, 500 au plus) ; les conversations se remontent avec avant ; les autres listes renvoient { donnees } en une fois, 500 éléments au plus (200 pour les rendez-vous, les recherches programmées, les changements de poste et les audiences).
Formats: Dates ISO 8601 en UTC ; montants des affaires en centimes (montant_centimes).
Rejeu sans doublon: Ajoutez l’en-tête Idempotency-Key (une valeur unique par action, 200 caractères au plus) à vos requêtes POST : créations, envois, actions de l’IA. Si Zapier ou votre script renvoie la même requête, la première réponse est rendue telle quelle (en-tête Idempotent-Replayed: true) : pas de seconde tâche, pas de second message. La valeur vaut 24 heures, pour une seule requête.
Champ inconnu: Refusé en 400, jamais ignoré : une faute de frappe ne passe pas en silence.
Cache: Cache-Control: no-store sur chaque réponse.

Ce que l’API, les webhooks et le MCP permettent, sans code : la page des intégrations. Comment vos clés sont gardées : clés gardées en empreinte, jamais en clair.

Cinq droits, cochés un à un.

Une clé FantomHunt lit toujours vos fiches, vos tâches, vos affaires, vos campagnes et vos statistiques. Quatre droits se cochent en plus, un à un, à la création : lire le texte des messages, modifier le suivi, envoyer, dépenser des crédits. Ce dernier exige deux plafonds mensuels, proposés à 100 crédits IA et 20 crédits contact.

Les droits d’une clé API
Case dans Paramètres	Code et pastille	Ce qu’elle ouvre aujourd’hui
« Lire le CRM » (toujours inclus)	`lecture`Lecture	Les fiches, les dates des échanges, les tâches, les affaires, les campagnes, les offres, les statistiques, l’état du compte. Jamais le texte des messages.
« Lire le texte des messages et des notes »	`messages`Messages	Le contenu des conversations LinkedIn, WhatsApp et email, les notes et le journal.
« Modifier le CRM »	`crm`Modifier le CRM	La note d’une fiche, le journal, les tâches, les affaires, la création d’étiquettes. Rien ne part vers un prospect. Ajouter une personne, changer son statut, son rendez-vous, son offre ou ses étiquettes : dans l’application pour l’instant.
« Envoyer des messages et lancer des actions »	`envoyer`Envoyer	Messages LinkedIn, WhatsApp et email, invitations, inscriptions en campagne, pause d’une campagne, recherches LinkedIn. Sans relecture dans l’application : l’email et le message WhatsApp partent aussitôt, LinkedIn passe par la file de l’extension. Toujours dans vos plafonds d’envoi.
« Dépenser des crédits »	`credits`Crédits	Rédaction par l’IA, modèles d’offre, séquences de campagne, lecture, sans débit, d’un email ou d’un téléphone déjà obtenu, sous deux plafonds mensuels obligatoires. Score IA et nouvelles recherches de coordonnées : dans l’application pour l’instant.

Les plafonds de dépense et leur fonctionnement : les plafonds de dépense d’une clé.

Une clé qui fuit ? Révoquez-la

Une clé FantomHunt n’est jamais gardée en clair : le serveur n’en conserve que l’empreinte. Révoquée dans Paramètres, elle cesse de fonctionner à la requête suivante, sans toucher aux autres clés du compte, dix au plus. Pour changer ses droits, créez une nouvelle clé ; ses plafonds, eux, se modifient sans changer de clé. Pour aller plus loin : comment vos clés et vos données sont protégées.

Ce que l’API ne fait pas encore

Pour l’instant, l’API et le serveur MCP de FantomHunt n’ajoutent pas de prospects, ne changent ni le statut, ni le rendez-vous, ni l’offre, ni les étiquettes d’une fiche, et ne lancent ni Score IA ni nouvelle recherche d’email ou de téléphone : l’application le fait, l’API répond 409 action_compte_requise. Notes, journal, tâches, affaires, envois et rédaction par l’IA passent par l’API.

Réponse (409)

{
  "error": "action_compte_requise",
  "message": "Cette modification est temporairement réservée à l’application, car son éventuelle reprise par une automatisation ne peut pas encore être attribuée à la clé API. Les notes et les tâches restent disponibles par API, même lorsque les automatisations sont en pause."
}

Des erreurs qui disent quoi faire, rien ne passe en silence.

Chaque erreur a la même forme : un code stable dans error, une explication en français dans message. Le code se teste dans votre programme, le message se lit. Un refus droit_manquant rend aussi le champ droit.

Réponse (403) d’une clé sans le droit Envoyer

{
  "error": "droit_manquant",
  "droit": "envoyer",
  "message": "Cette clé n'a pas le droit « Envoyer des messages et lancer des actions ». Créez une clé avec ce droit dans Réglages › API & Intégrations."
}

Les erreurs de l’API
HTTP	Code	Quand
400	`parametre_invalide`	Un filtre, une date, un curseur ou un champ illisible ; en écriture, aussi un champ inconnu.
401	`cle_manquante`	Aucune clé dans Authorization.
401	`cle_invalide`	Clé inconnue ou révoquée.
402	`plafond_atteint`	Le plafond du mois de la clé ne couvre pas cette action : rien n’est lancé (plafond et estimation sont joints ; la dépense du mois est dans GET /v1/moi).
402	`credits_insuffisants`	Le compte n’a plus assez de crédits.
403	`plan_requis`	Le compte n’est plus sur une offre payante.
403	`compte_desactive`	Le compte a été désactivé.
403	`compte_en_suppression`	La suppression du compte est demandée : l’API est fermée.
403	`droit_manquant`	La clé n’a pas le droit demandé (le champ droit dit lequel) : créez une clé qui l’a.
403	`delegation_suspendue`	Cas rare : la clé a été révoquée, ou le compte a perdu son offre payante, pendant le traitement de la requête. Rien n’est lancé.
404	`introuvable`	Identifiant inconnu sur ce compte.
409	`action_compte_requise`	Action réservée pour l’instant à l’application : ajout de personnes, statut, rendez-vous, offre ou étiquettes d’une fiche, Score IA, nouvelle recherche d’email ou de téléphone. Rien n’est écrit ni débité.
409	`reprise_compte_requise`	Relancer cette campagne se fait dans l’application : l’API ne relance qu’une campagne LinkedIn à liste manuelle remplie par cette clé.
409	`conflit`	L’action contredit l’état de la fiche (personne déjà rattachée à l’affaire, invitation à un prospect déjà connecté, recherche déjà en cours).
409	`canal_deconnecte`	WhatsApp ou la boîte email n’est pas connecté : rien n’est parti.
409	`requete_en_cours`	Une requête avec la même Idempotency-Key n’est pas encore terminée.
409	`requete_incertaine`	La requête précédente avec cette Idempotency-Key a échoué après avoir commencé à enregistrer : vérifiez le résultat avant de réessayer avec une nouvelle clé.
422	`hors_cadre`	L’IA a jugé la demande hors du cadre de la prospection.
422	`cle_reutilisee`	Cette Idempotency-Key a déjà servi pour une autre requête (autre adresse ou autre contenu).
429	`limite_atteinte`	Le quota d’invitations du mois, 100 invitations demandées aujourd’hui ou 300 cette semaine, le plafond WhatsApp ou email du jour ou de la semaine, ou la limite de profils trouvés est atteint : rien n’est parti. Un message LinkedIn, lui, n’est jamais refusé : il attend dans la file (voir attentes).
429	`quota_atteint`	Recherche lancée avec un persona au-delà de la limite de profils trouvés (1 000 par jour, 3 000 par semaine au plus).
429	`trop_de_requetes`	Plus de 120 requêtes en une minute avec cette clé, ou plus de 600 depuis la même adresse : réessayez dans une minute (en-têtes RateLimit-*).
503	`indisponible`	Le service d’IA ne répond pas. Si l’appel avait déjà réservé ses crédits, ils restent débités (le bloc credits le dit) ; réessayez plus tard.

Les statuts

Les statuts d’un prospect LinkedIn
Statut d’un prospect LinkedIn	Ce qu’il veut dire
`nouveau`	Pas encore démarché.
`pending_connection`	Invitation envoyée, en attente.
`contacted`	Message envoyé.
`connected`	Invitation acceptée.
`replied`	A répondu.
`rdv`	Rendez-vous pris.
`snoozed`	Relance programmée (mis en veille jusqu’à une date).
`client`	Devenu client.
`not_interested`	Pas intéressé.
`off_topic`	Hors cible.
`ecarte`	Écarté.
`archived`	Archivé.

Un contact WhatsApp ou email a son propre statut dans son canal : actif tant qu’il n’en est pas sorti, puis rdv, client, not_interested, off_topic, ecarte, archived, et pour l’email bounced (adresse qui rejette les messages).

Lire et filtrer, sans laisser filer un prospect.

GET`/v1/moi`

Lecture

Le compte derrière la clé : ses droits, les crédits IA et contact restants, les invitations LinkedIn du mois. L’appel de vérification de toute intégration.

Vérifier la clé

curl "https://api.fantomhunt.com/v1/moi" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (200)

{
  "compte": {
    "email": "vous@entreprise.fr",
    "plan": "essentiel",
    "cree_le": "2026-09-12T08:30:00.000Z"
  },
  "cle": {
    "nom": "HubSpot par Zapier",
    "prefixe": "fh_live_a1b2",
    "portee": "lecture",
    "droits": ["lecture"]
  },
  "credits": {
    "ia": { "restants": 362, "par_mois": 400 },
    "contact": { "restants": 41.5, "par_mois": 50 }
  },
  "prospects": { "utilises": 1240, "limite": null },
  "invitations_linkedin": { "envoyees": 312, "par_mois": 800 }
}

GET`/v1/etat`

Lecture

Ce que FantomHunt fait pour vous : prospection en pause ou non, frein LinkedIn, prochaine action prévue, canaux connectés, usage du jour et de la semaine face aux limites.

Requête

curl "https://api.fantomhunt.com/v1/etat" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/prospects`

Lecture

Vos prospects LinkedIn : liste filtrable et paginée, ou une seule fiche retrouvée par son email, son lien LinkedIn ou son téléphone.

Filtres de GET /v1/prospects : statut (plusieurs à la fois : statut=replied,rdv), etiquette, recherche, campagne, offre (identifiants), score_min, q (nom, entreprise ou poste), les dates cree_depuis, contacte_depuis, repondu_depuis et modifie_depuis. Pour retrouver la fiche d’une personne que votre outil de suivi connaît (HubSpot, Pipedrive, un tableur) : email, url_linkedin (avec ou sans https://) ou telephone (06…, +33 6… : même numéro). Contacts WhatsApp et email : statut (une valeur), q, telephone ou email, cree_depuis, repondu_depuis.

Ne tirer que ce qui a bougé. Passez modifie_depuis avec la date de votre dernier passage : seules les fiches modifiées depuis reviennent. C’est le moyen le plus simple de tenir un autre outil à jour à intervalles réguliers. Gardez l’id FantomHunt dans votre outil : il est dans chaque fiche, et la même fiche arrive dans chaque webhook qui concerne la personne.

Lister qui a répondu

curl "https://api.fantomhunt.com/v1/prospects?statut=replied&limite=1" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (200)

{
  "donnees": [
    {
      "id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
      "nom": "Camille Roussel",
      "entreprise": "Skova",
      "poste": "Directrice commerciale",
      "url_linkedin": "https://www.linkedin.com/in/…",
      "localisation": "Lyon, France",
      "email": "camille.roussel@skova.fr",
      "email_score": null,
      "telephone": null,
      "statut": "replied",
      "score": 92,
      "source": "extension",
      "recherche_id": "4a7e…",
      "offre_id": "9c1d…",
      "offre": { "id": "9c1d…", "nom": "Pilotage de la performance B2B" },
      "cree_le": "2026-09-22T08:10:00.000Z",
      "modifie_le": "2026-09-30T09:13:58.000Z",
      "contacte_le": "2026-09-23T09:00:00.000Z",
      "connecte_le": "2026-09-24T16:20:00.000Z",
      "repondu_le": "2026-09-30T09:13:58.000Z",
      "rdv_le": null,
      "etiquettes": [{ "id": "7b21…", "nom": "Chaud", "couleur": "#e8935a" }],
      "campagnes": [{ "id": "b3f0…", "nom": "Directeurs commerciaux" }]
    }
  ],
  "curseur_suivant": "eyJ0Ijoi…"
}

GET`/v1/prospects/:id`

Lecture

Une fiche complète : coordonnées, statut, Score IA, offre, étiquettes, campagnes en cours, dates clés.

Requête

curl "https://api.fantomhunt.com/v1/prospects/3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (200)

{
  "id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
  "nom": "Camille Roussel",
  "entreprise": "Skova",
  "poste": "Directrice commerciale",
  "url_linkedin": "https://www.linkedin.com/in/…",
  "localisation": "Lyon, France",
  "email": "camille.roussel@skova.fr",
  "email_score": null,
  "telephone": null,
  "statut": "replied",
  "score": 92,
  "source": "extension",
  "recherche_id": "4a7e…",
  "offre_id": "9c1d…",
  "offre": { "id": "9c1d…", "nom": "Pilotage de la performance B2B" },
  "cree_le": "2026-09-22T08:10:00.000Z",
  "modifie_le": "2026-09-30T09:13:58.000Z",
  "contacte_le": "2026-09-23T09:00:00.000Z",
  "connecte_le": "2026-09-24T16:20:00.000Z",
  "repondu_le": "2026-09-30T09:13:58.000Z",
  "rdv_le": null,
  "etiquettes": [{ "id": "7b21…", "nom": "Chaud", "couleur": "#e8935a" }],
  "campagnes": [{ "id": "b3f0…", "nom": "Directeurs commerciaux" }]
}

Avec le droit messages, la fiche porte aussi sa note.

GET`/v1/prospects/:id/journal`

Lecture

Le journal : le type d’événement et sa date ; avec le droit messages, le contenu (note, compte rendu, texte du message).

Requête

curl "https://api.fantomhunt.com/v1/prospects/3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22/journal" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/prospects/:id/conversation`

Messages

Le fil de la personne, LinkedIn, WhatsApp et email réunis, du plus récent au plus ancien ({ donnees, avant_suivant }).

Avec une clé qui a le droit messages. Chaque message dit son canal, son sens (envoye ou recu), son texte et sa date ; un email porte aussi son objet, et deux marques : réponse automatique, expéditeur non authentifié. limite : 100 par défaut, 200 au plus ; pour remonter plus loin, repassez avant_suivant dans avant. Sans ce droit, le journal donne le type de chaque événement et sa date, jamais son contenu.

Lire la conversation

curl "https://api.fantomhunt.com/v1/prospects/3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22/conversation" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (200)

{
  "donnees": [
    {
      "canal": "linkedin",
      "id": "…",
      "sens": "recu",
      "objet": null,
      "texte": "Volontiers. Jeudi après-midi ?",
      "date": "2026-09-30T09:13:58.000Z",
      "media": null,
      "reponse_automatique": false,
      "non_verifie": false
    },
    {
      "canal": "linkedin",
      "id": "…",
      "sens": "envoye",
      "objet": null,
      "texte": "Bonjour Camille, je vois que vous pilotez les ventes chez Skova…",
      "date": "2026-09-29T08:30:00.000Z",
      "media": null,
      "reponse_automatique": false,
      "non_verifie": false
    }
  ],
  "avant_suivant": null
}

GET`/v1/contacts-whatsapp`

Lecture

Le répertoire WhatsApp (filtres : statut, q, telephone, cree_depuis, repondu_depuis).

Requête

curl "https://api.fantomhunt.com/v1/contacts-whatsapp" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/contacts-whatsapp/:id`

Lecture

La fiche d’un contact WhatsApp : offre, étiquettes, campagnes (celles de sa fiche LinkedIn liée), dates.

Requête

curl "https://api.fantomhunt.com/v1/contacts-whatsapp/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/contacts-whatsapp/:id/conversation`

Messages

La conversation WhatsApp du contact.

Requête

curl "https://api.fantomhunt.com/v1/contacts-whatsapp/:id/conversation" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/contacts-email`

Lecture

Le répertoire email (filtres : statut, q, email, cree_depuis, repondu_depuis).

Requête

curl "https://api.fantomhunt.com/v1/contacts-email" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/contacts-email/:id`

Lecture

La fiche d’un contact email.

Requête

curl "https://api.fantomhunt.com/v1/contacts-email/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/contacts-email/:id/conversation`

Messages

Les emails échangés avec le contact, objet compris.

Requête

curl "https://api.fantomhunt.com/v1/contacts-email/:id/conversation" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/taches`

Lecture

Vos tâches et la personne concernée (statut : a_faire, faites ou toutes ; en_retard=1 ; prospect ; echeance_avant, echeance_apres).

Requête

curl "https://api.fantomhunt.com/v1/taches?statut=a_faire" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (200)

{
  "donnees": [
    {
      "id": "c84e…",
      "titre": "Rappeler Camille Roussel",
      "echeance_le": "2026-10-05T09:00:00.000Z",
      "faite_le": null,
      "cree_le": "2026-10-01T10:02:11.000Z",
      "en_retard": false,
      "canal": "linkedin",
      "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
      "contact_whatsapp_id": null,
      "contact_email_id": null,
      "personne": "Camille Roussel"
    }
  ]
}

GET`/v1/affaires`

Lecture

Vos affaires (vue Opérations) : montant, colonne, échéance ; statut : en_cours, gagnee ou perdue avec le motif.

Requête

curl "https://api.fantomhunt.com/v1/affaires?statut=en_cours" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/affaires/:id`

Lecture

Une affaire et ses personnes, avec leur importance.

Requête

curl "https://api.fantomhunt.com/v1/affaires/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/affaires-colonnes`

Lecture

Les colonnes de votre tableau d’affaires, dans l’ordre.

Requête

curl "https://api.fantomhunt.com/v1/affaires-colonnes" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/campagnes`

Lecture

Vos campagnes et leurs compteurs (inscrits, traités, actifs, stoppés, réponses).

Requête

curl "https://api.fantomhunt.com/v1/campagnes" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/campagnes/:id`

Lecture

Le détail d’une campagne : canal, horaires d’envoi, étapes (types, délais, textes prévus) et compteurs.

Requête

curl "https://api.fantomhunt.com/v1/campagnes/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/campagnes/:id/prospects`

Lecture

Où en sont ses prospects : étape en cours, raison de sortie, prochaine action.

Requête

curl "https://api.fantomhunt.com/v1/campagnes/:id/prospects" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/offres`

Lecture

Vos offres.

Requête

curl "https://api.fantomhunt.com/v1/offres" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/offres/:id`

Lecture

Le contenu d’une offre, celui que lit l’IA : promesse, prix, objectif, ton, personas, angles, preuves, objections, consignes, et ce qui reste à confirmer.

Requête

curl "https://api.fantomhunt.com/v1/offres/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/offres/:id/messages-types`

Lecture

Les modèles de messages de l’offre.

Requête

curl "https://api.fantomhunt.com/v1/offres/:id/messages-types" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats`

Lecture

Les totaux par canal, filtrables par date avec depuis.

Requête

curl "https://api.fantomhunt.com/v1/stats?depuis=2026-09-01" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats/canaux`

Lecture

Par canal : envois, personnes contactées, réponses, taux et délai médian de réponse, et la période précédente pour comparer (jours, 30 par défaut).

Requête

curl "https://api.fantomhunt.com/v1/stats/canaux?jours=30" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats/quotidien`

Lecture

Envois et réponses jour par jour (jours : 7 à 90).

Requête

curl "https://api.fantomhunt.com/v1/stats/quotidien?jours=30" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats/etapes`

Lecture

Envois, réponses et taux par étape de campagne.

Requête

curl "https://api.fantomhunt.com/v1/stats/etapes" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats/ab`

Lecture

Les tests comparatifs en cours : versions, taux, probabilité d’être la meilleure et verdict (trop_tot, tendance, gagnante, egalite).

Requête

curl "https://api.fantomhunt.com/v1/stats/ab" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats/horaires`

Lecture

Les réponses par jour de la semaine (lundi en premier) et par heure, heure de Paris.

Requête

curl "https://api.fantomhunt.com/v1/stats/horaires" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats/segments`

Lecture

Les taux de réponse par offre, par étiquette et par recherche.

Requête

curl "https://api.fantomhunt.com/v1/stats/segments" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats/pipeline`

Lecture

Le stock de prospects par étape et l’état des parcours de campagne.

Requête

curl "https://api.fantomhunt.com/v1/stats/pipeline" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/stats/resultats-commerciaux`

Lecture

Affaires gagnées et perdues, montants, taux de réussite, durée d’une affaire, motifs de perte, et la période précédente (jours, 0 = depuis toujours).

Requête

curl "https://api.fantomhunt.com/v1/stats/resultats-commerciaux" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/rdv`

Lecture

Les rendez-vous des trois canaux (periode : a_venir ou passes).

Requête

curl "https://api.fantomhunt.com/v1/rdv?periode=a_venir" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/recherches`

Lecture

Vos recherches et leur récolte.

Requête

curl "https://api.fantomhunt.com/v1/recherches" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/recherches/:id`

Lecture

Le détail d’une recherche : paramètres, progression, erreur éventuelle.

Requête

curl "https://api.fantomhunt.com/v1/recherches/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/recherches-automatiques`

Lecture

Vos recherches programmées.

Requête

curl "https://api.fantomhunt.com/v1/recherches-automatiques" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/changements-poste`

Lecture

Les prospects suivis qui ont changé de poste ou ont été promus (non_vus=1).

Requête

curl "https://api.fantomhunt.com/v1/changements-poste?non_vus=1" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/audiences`

Lecture

Vos audiences.

Requête

curl "https://api.fantomhunt.com/v1/audiences" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/equipe`

Lecture

Votre équipe et les performances de ses membres, avec les mêmes règles de visibilité que l’application.

Requête

curl "https://api.fantomhunt.com/v1/equipe" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

GET`/v1/etiquettes`

Lecture

Vos étiquettes (pour donner leur sens aux filtres).

Requête

curl "https://api.fantomhunt.com/v1/etiquettes" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Écrire dans votre suivi, sans rien envoyer.

Avec une clé qui a le droit crm (case « Modifier le CRM », décochée par défaut). Ouvert aujourd’hui : la note d’une fiche, le journal, les tâches, les affaires et la création d’étiquettes. L’ajout de personnes et le changement de statut, de rendez-vous, d’offre ou d’étiquettes d’une fiche se font pour l’instant dans l’application : par l’API, la requête répond 409 action_compte_requise, avant toute écriture.

Ce qui passe suit le même chemin que l’application : la note suit sur les autres canaux de la personne, et les tâches et les affaires préviennent vos webhooks (tache.creee, affaire.gagnee…). Rien ne part vers un prospect et aucun crédit n’est dépensé. Une fiche est vérifiée en entier avant d’écrire : une requête refusée n’y laisse rien à moitié fait.

POST`/v1/prospects`

Modifier le CRMDans l’application pour l’instant

Ajouter un prospect par url_linkedin (avec offre_id, etiquettes_ajouter, note). Pour l’instant dans l’application : 409 action_compte_requise.

Requête

curl -X POST "https://api.fantomhunt.com/v1/prospects" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "url_linkedin": "https://www.linkedin.com/in/…", "offre_id": "9c1d…" }'

Réponse (409)

{
  "error": "action_compte_requise",
  "message": "Cette modification est temporairement réservée à l’application, car son éventuelle reprise par une automatisation ne peut pas encore être attribuée à la clé API. Les notes et les tâches restent disponibles par API, même lorsque les automatisations sont en pause."
}

PATCH`/v1/prospects/:id`

Modifier le CRMNote seule pour l’instant

Ouvert : note (rend la fiche à jour). Pour l’instant dans l’application : statut, rdv_le, rdv_duree_min, rdv_debriefe, offre_id, etiquettes_ajouter, etiquettes_retirer ; un seul de ces champs et toute la requête répond 409 action_compte_requise.

Requête

curl -X PATCH "https://api.fantomhunt.com/v1/prospects/3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Préfère un appel le matin." }'

Réponse (200)

{
  "id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
  "nom": "Camille Roussel",
  "entreprise": "Skova",
  "poste": "Directrice commerciale",
  "url_linkedin": "https://www.linkedin.com/in/…",
  "localisation": "Lyon, France",
  "email": "camille.roussel@skova.fr",
  "email_score": null,
  "telephone": null,
  "statut": "replied",
  "score": 92,
  "source": "extension",
  "recherche_id": "4a7e…",
  "offre_id": "9c1d…",
  "offre": { "id": "9c1d…", "nom": "Pilotage de la performance B2B" },
  "cree_le": "2026-09-22T08:10:00.000Z",
  "modifie_le": "2026-09-30T09:13:58.000Z",
  "contacte_le": "2026-09-23T09:00:00.000Z",
  "connecte_le": "2026-09-24T16:20:00.000Z",
  "repondu_le": "2026-09-30T09:13:58.000Z",
  "rdv_le": null,
  "etiquettes": [{ "id": "7b21…", "nom": "Chaud", "couleur": "#e8935a" }],
  "campagnes": [{ "id": "b3f0…", "nom": "Directeurs commerciaux" }]
}

POST`/v1/prospects/:id/journal`

Modifier le CRM

Ajouter une note datée au journal (texte) : un appel, un échange hors FantomHunt.

Requête

curl -X POST "https://api.fantomhunt.com/v1/prospects/3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22/journal" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "texte": "Appel de 15 minutes, budget validé pour janvier." }'

Réponse (201)

{
  "id": "e5a2…",
  "texte": "Appel de 15 minutes, budget validé pour janvier.",
  "cree_le": "2026-10-01T10:04:00.000Z"
}

POST`/v1/contacts-whatsapp`

Modifier le CRMDans l’application pour l’instant

Ajouter un contact WhatsApp (telephone, nom). Pour l’instant dans l’application : 409 action_compte_requise.

Requête

curl -X POST "https://api.fantomhunt.com/v1/contacts-whatsapp" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "telephone": "+33612345678", "nom": "Camille Roussel" }'

Réponse (409)

{
  "error": "action_compte_requise",
  "message": "Cette modification est temporairement réservée à l’application, car son éventuelle reprise par une automatisation ne peut pas encore être attribuée à la clé API. Les notes et les tâches restent disponibles par API, même lorsque les automatisations sont en pause."
}

PATCH`/v1/contacts-whatsapp/:id`

Modifier le CRMNote seule pour l’instant

Ouvert : note. Le reste (statut : actif, rdv, client, not_interested, off_topic, archived, ecarte ; offre, étiquettes) se fait pour l’instant dans l’application.

Requête

curl -X PATCH "https://api.fantomhunt.com/v1/contacts-whatsapp/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Préfère un message le matin." }'

POST`/v1/contacts-whatsapp/:id/journal`

Modifier le CRM

Une note datée au journal du contact.

Requête

curl -X POST "https://api.fantomhunt.com/v1/contacts-whatsapp/:id/journal" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "texte": "Appel de 15 minutes, budget validé pour janvier." }'

Réponse (201)

{
  "id": "e5a2…",
  "texte": "Appel de 15 minutes, budget validé pour janvier.",
  "cree_le": "2026-10-01T10:04:00.000Z"
}

POST`/v1/contacts-email`

Modifier le CRMDans l’application pour l’instant

Ajouter un contact email (email, nom). Pour l’instant dans l’application : 409 action_compte_requise.

Requête

curl -X POST "https://api.fantomhunt.com/v1/contacts-email" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "email": "camille.roussel@skova.fr", "nom": "Camille Roussel" }'

Réponse (409)

{
  "error": "action_compte_requise",
  "message": "Cette modification est temporairement réservée à l’application, car son éventuelle reprise par une automatisation ne peut pas encore être attribuée à la clé API. Les notes et les tâches restent disponibles par API, même lorsque les automatisations sont en pause."
}

PATCH`/v1/contacts-email/:id`

Modifier le CRMNote seule pour l’instant

Ouvert : note. Le reste (statut, offre, étiquettes) se fait pour l’instant dans l’application.

Requête

curl -X PATCH "https://api.fantomhunt.com/v1/contacts-email/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Écrire en fin de journée." }'

POST`/v1/contacts-email/:id/journal`

Modifier le CRM

Une note datée au journal du contact.

Requête

curl -X POST "https://api.fantomhunt.com/v1/contacts-email/:id/journal" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "texte": "Appel de 15 minutes, budget validé pour janvier." }'

Réponse (201)

{
  "id": "e5a2…",
  "texte": "Appel de 15 minutes, budget validé pour janvier.",
  "cree_le": "2026-10-01T10:04:00.000Z"
}

POST`/v1/taches`

Modifier le CRM

Créer une tâche : titre, echeance_le, une personne au plus (prospect_id, contact_whatsapp_id ou contact_email_id), canal (linkedin, whatsapp ou email). 201.

Créer une tâche

curl -X POST "https://api.fantomhunt.com/v1/taches" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Idempotency-Key: rappel-camille-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{ "titre": "Rappeler Camille Roussel", "echeance_le": "2026-10-05T09:00:00Z", "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22", "canal": "linkedin" }'

Réponse (201)

{
  "id": "c84e…",
  "titre": "Rappeler Camille Roussel",
  "echeance_le": "2026-10-05T09:00:00.000Z",
  "faite_le": null,
  "cree_le": "2026-10-01T10:02:11.000Z",
  "en_retard": false,
  "canal": "linkedin",
  "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
  "contact_whatsapp_id": null,
  "contact_email_id": null,
  "personne": "Camille Roussel"
}

PATCH`/v1/taches/:id`

Modifier le CRM

titre, echeance_le, faite (true ou false), canal.

Requête

curl -X PATCH "https://api.fantomhunt.com/v1/taches/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "faite": true }'

Réponse (200)

{
  "id": "c84e…",
  "titre": "Rappeler Camille Roussel",
  "echeance_le": "2026-10-05T09:00:00.000Z",
  "faite_le": "2026-10-05T08:40:00.000Z",
  "cree_le": "2026-10-01T10:02:11.000Z",
  "en_retard": false,
  "canal": "linkedin",
  "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
  "contact_whatsapp_id": null,
  "contact_email_id": null,
  "personne": "Camille Roussel"
}

DELETE`/v1/taches/:id`

Modifier le CRM

Supprimer une tâche.

Requête

curl -X DELETE "https://api.fantomhunt.com/v1/taches/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (200)

{
  "supprime": true,
  "id": "c84e…"
}

POST`/v1/affaires`

Modifier le CRM

Créer une affaire : nom, montant_centimes, debut_le et echeance_le (AAAA-MM-JJ), colonne_id, personnes ([{ "prospect_id": "…" }]). 201.

Requête

curl -X POST "https://api.fantomhunt.com/v1/affaires" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Idempotency-Key: affaire-skova-2026-10" \
  -H "Content-Type: application/json" \
  -d '{ "nom": "Skova, pilotage commercial", "montant_centimes": 480000, "debut_le": "2026-10-01", "echeance_le": "2026-11-30", "personnes": [{ "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22" }] }'

PATCH`/v1/affaires/:id`

Modifier le CRM

nom, montant_centimes, debut_le et echeance_le (AAAA-MM-JJ), colonne_id, et statut : gagnee, perdue (avec motif_de_perte) ou en_cours (rouvre une affaire close).

Une affaire gagnée dans votre outil se reporte avec { "statut": "gagnee" } ; une affaire perdue demande aussi motif_de_perte. Un champ inconnu est refusé (400) plutôt qu’ignoré : une faute de frappe ne passe pas en silence.

Reporter une affaire gagnée

curl -X PATCH "https://api.fantomhunt.com/v1/affaires/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "statut": "gagnee" }'

POST`/v1/affaires/:id/personnes`

Modifier le CRM

Rattacher une personne à une affaire.

Requête

curl -X POST "https://api.fantomhunt.com/v1/affaires/:id/personnes" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22" }'

POST`/v1/etiquettes`

Modifier le CRM

Créer une étiquette (nom, couleur). 201.

Requête

curl -X POST "https://api.fantomhunt.com/v1/etiquettes" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "nom": "Chaud", "couleur": "#e8935a" }'

Réponse (201)

{
  "id": "7b21…",
  "nom": "Chaud",
  "couleur": "#e8935a"
}

Envoyer depuis vos outils, avec vos plafonds.

Avec une clé qui a le droit envoyer (décoché par défaut). L’envoi part sans relecture dans l’application, exactement comme un envoi fait à la main, avec les mêmes plafonds : invitations LinkedIn 100 par jour et 300 par semaine (au-delà, la requête est refusée), dans le quota de votre offre (800 par mois en Essentiel et en Croissance) ; WhatsApp 30 messages par jour et 150 par semaine ; email 40 par jour et 200 par semaine pour chaque boîte connectée. Ces plafonds se baissent dans Paramètres › Limites, jamais au-dessus. Donnez ce droit seulement à un outil de confiance.

Un message ou une invitation LinkedIn part par l’extension, depuis votre navigateur ouvert : la réponse est 202, l’envoi est en file. WhatsApp et email partent du serveur : la réponse est 201, le message est parti. Même frein LinkedIn, même conversation que dans l’application.

La réponse d’un envoi LinkedIn dit, dans attentes, ce qui le ferait patienter : prospection en pause, LinkedIn freiné après des refus, hors de vos horaires d’envoi, plafond du jour atteint. Le webhook message.envoye (ou invitation.envoyee) vous prévient quand il est réellement parti. Une campagne dont les étapes rédigent avec l’IA consomme ses crédits comme dans l’application. Pourquoi LinkedIn passe par le navigateur : les envois LinkedIn partent par l’extension.

POST`/v1/prospects/:id/message`

Envoyer

Un message LinkedIn (texte), ou programmé (programme_le, date à venir). Il entre dans la file de l’extension : 202, avec envoi_id, statut_envoi (en_file ou programme) et attentes.

Envoyer un message LinkedIn

curl -X POST "https://api.fantomhunt.com/v1/prospects/3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22/message" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "texte": "Avec plaisir, Camille. Jeudi 14 h vous convient-il ?" }'

Réponse (202)

{
  "canal": "linkedin",
  "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
  "envoi_id": "a41c…",
  "statut_envoi": "en_file",
  "attentes": ["Hors de vos horaires d’envoi : l’envoi partira à la prochaine plage."]
}

202 : le message est dans la file de l’extension, il part depuis votre navigateur ouvert.

POST`/v1/prospects/:id/invitation`

Envoyer

Une invitation LinkedIn, avec une note facultative (300 caractères). 202 en file ; refusée (409) si le prospect est déjà connecté ou plus loin dans le parcours.

Requête

curl -X POST "https://api.fantomhunt.com/v1/prospects/5d0b…/invitation" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Ravi d’échanger avec vous sur le pilotage commercial." }'

Réponse (202)

{
  "canal": "linkedin",
  "prospect_id": "5d0b…",
  "envoi_id": "b52d…",
  "statut_envoi": "en_file",
  "attentes": []
}

POST`/v1/contacts-whatsapp/:id/message`

Envoyer

Un message WhatsApp (texte), envoyé immédiatement par votre session : 201.

Requête

curl -X POST "https://api.fantomhunt.com/v1/contacts-whatsapp/:id/message" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "texte": "Bonjour Camille, voici le compte rendu de jeudi." }'

Réponse (201)

{
  "canal": "whatsapp",
  "contact_id": "d17a…",
  "statut_envoi": "envoye",
  "message": {
    "id": "f2c9…",
    "texte": "Bonjour Camille, voici le compte rendu de jeudi.",
    "envoye_le": "2026-10-02T15:10:00.000Z"
  }
}

POST`/v1/contacts-email/:id/message`

Envoyer

Un email (objet, texte), envoyé immédiatement par la boîte du fil ou celle de boite_id, avec votre signature (signature: false pour l’enlever) : 201.

Requête

curl -X POST "https://api.fantomhunt.com/v1/contacts-email/:id/message" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "objet": "Compte rendu de jeudi", "texte": "Bonjour Camille, voici le compte rendu de notre échange." }'

Réponse (201)

{
  "canal": "email",
  "contact_id": "e93b…",
  "statut_envoi": "envoye",
  "message": {
    "id": "0a6e…",
    "objet": "Compte rendu de jeudi",
    "envoye_le": "2026-10-02T15:12:00.000Z"
  }
}

POST`/v1/campagnes/:id/prospects`

Envoyer

Inscrire des prospects (prospect_ids, 500 au plus) dans une campagne à liste manuelle. La réponse compte inscrits, ecartes_equipe et ignores (introuvables, déjà dans une campagne en cours ou déjà passés par celle-ci). Si les étapes rédigent avec l’IA ou cherchent un email ou un téléphone, la clé doit aussi avoir le droit credits.

Requête

curl -X POST "https://api.fantomhunt.com/v1/campagnes/:id/prospects" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "prospect_ids": ["5d0b…", "8e3a…"] }'

Réponse (200)

{
  "campagne_id": "b3f0…",
  "inscrits": 2,
  "ecartes_equipe": 0,
  "ignores": 0
}

PATCH`/v1/campagnes/:id`

EnvoyerRelance sous conditions

statut : paused (mettre en pause) ou active (lancer ou relancer). Par l’API, le lancement et la relance ne valent que pour une campagne LinkedIn à liste manuelle dont toutes les inscriptions en cours viennent de cette clé ; sinon 409 reprise_compte_requise.

Requête

curl -X PATCH "https://api.fantomhunt.com/v1/campagnes/:id" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "statut": "paused" }'

Réponse (200)

{
  "id": "b3f0…",
  "nom": "Directeurs commerciaux",
  "statut": "paused"
}

POST`/v1/recherches`

Envoyer

Lancer une recherche de profils LinkedIn, exécutée par l’extension (détail des sources et des volumes plus bas). Une à la fois ; 201 et la fiche de la recherche.

source : mots_cles (par défaut, avec cible et pays, France par défaut), sales_navigator, groupe, evenement, engagement_post (avec url), reseau, visiteurs_profil. volume : 50 par défaut, 200 au plus pour les mots-clés, un post ou vos visiteurs, 500 pour Sales Navigator, votre réseau, un groupe ou un événement, ramené à ce qu’il reste de votre limite de profils trouvés (1 000 par jour et 3 000 par semaine au plus, réglable à la baisse), 15 au moins ; s’il reste moins de 15 profils, 429 limite_atteinte. Filtres : offre_id, secteurs, premier_degre, en_recherche_emploi (vrai ou faux), persona_id (avec son offre_id, en recherche par mots-clés : le persona apporte alors ses mots-clés, ses pays et ses secteurs, seuls offre_id et volume comptent).

Requête

curl -X POST "https://api.fantomhunt.com/v1/recherches" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "source": "mots_cles", "cible": "Directeur commercial", "volume": 50 }'

POST`/v1/recherches/:id/annuler`

Envoyer

Annuler une recherche en attente ou en cours.

Requête

curl -X POST "https://api.fantomhunt.com/v1/recherches/:id/annuler" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Dépenser des crédits, jamais au-delà du plafond.

Avec une clé qui a le droit credits. Cette clé porte deux plafonds mensuels obligatoires, en crédits IA et en crédits contact (100 et 20 proposés à la création, modifiables dans Paramètres › API sans changer de clé). Chaque action est d’abord estimée par le même calcul que l’application (gratuitement avec POST /v1/ia/estimer), puis comptée sur la clé à son coût réellement débité.

Au-delà du plafond, rien n’est lancé (402 plafond_atteint). Le solde du compte reste la seconde barrière. Chaque réponse porte un bloc credits : ce qui était estimé, ce qui a été débité, et où en est la clé ce mois-ci ; GET /v1/moi donne aussi les plafonds de la clé et sa dépense du mois. Le prix des coordonnées dans l’application : 1 crédit l’email, 10 le numéro.

POST`/v1/ia/estimer`

Toute clé

Gratuit, pour toute clé : le coût d’une action avant de la lancer (action : rediger_message, scorer, modeles_offre, sequence_campagne, trouver_email, trouver_telephone, avec ses paramètres).

Estimer un coût, gratuitement

curl -X POST "https://api.fantomhunt.com/v1/ia/estimer" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "action": "rediger_message", "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22" }'

Réponse (200)

{
  "action": "rediger_message",
  "credits_ia": 4
}

Valeur d’exemple : le coût est calculé à chaque demande, avant toute dépense.

POST`/v1/ia/message`

Crédits

Rédiger avec l’IA un message pour un prospect (prospect_id ; mode : premier_message ou reponse ; offre_id, par défaut celle de la fiche ; contexte). Rend message, conseils et stade : le texte n’est pas envoyé. En mode reponse, la clé doit aussi avoir le droit messages.

Requête

curl -X POST "https://api.fantomhunt.com/v1/ia/message" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22", "mode": "premier_message" }'

Réponse (200)

{
  "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
  "mode": "premier_message",
  "message": "Bonjour Camille, je vois que vous pilotez les ventes chez Skova…",
  "conseils": "Si réponse positive, proposer un créneau de 20 minutes.",
  "stade": "…",
  "texte": "…",
  "credits": {
    "type": "ia",
    "estimes": 4,
    "debites": 4,
    "cle_ce_mois": { "depenses": 12, "plafond": 100 }
  }
}

Valeurs d’exemple : le coût réel s’affiche dans estimes avant l’action et dans debites après.

POST`/v1/ia/scorer`

CréditsDans l’application pour l’instant

Calculer le Score IA de prospects face à une offre (offre_id, prospect_ids, 200 au plus). Pour l’instant dans l’application : 409 action_compte_requise.

Requête

curl -X POST "https://api.fantomhunt.com/v1/ia/scorer" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "offre_id": "9c1d…", "prospect_ids": ["3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22"] }'

Réponse (409)

{
  "error": "action_compte_requise",
  "message": "Cette modification est temporairement réservée à l’application, car son éventuelle reprise par une automatisation ne peut pas encore être attribuée à la clé API. Les notes et les tâches restent disponibles par API, même lorsque les automatisations sont en pause."
}

POST`/v1/ia/modeles-offre`

Crédits

Générer les modèles de messages d’une offre, enregistrés dans l’offre.

Requête

curl -X POST "https://api.fantomhunt.com/v1/ia/modeles-offre" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "offre_id": "9c1d…" }'

POST`/v1/ia/sequence-campagne`

Crédits

Rédiger les textes des étapes d’une campagne (campagne_id). Proposés, pas appliqués.

Requête

curl -X POST "https://api.fantomhunt.com/v1/ia/sequence-campagne" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "campagne_id": "b3f0…" }'

POST`/v1/prospects/:id/trouver-email`

CréditsCoordonnée déjà obtenue seulement

Rend gratuitement l’email professionnel déjà obtenu pour ce prospect (trouve, valeur, score). Une nouvelle recherche (1 crédit contact, rendu si introuvable) se lance pour l’instant dans l’application : 409 action_compte_requise, rien n’est débité.

Requête

curl -X POST "https://api.fantomhunt.com/v1/prospects/3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22/trouver-email" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (200)

{
  "prospect_id": "3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22",
  "type": "email",
  "trouve": true,
  "valeur": "camille.roussel@skova.fr",
  "score": null,
  "credits": {
    "type": "contact",
    "estimes": 0,
    "debites": 0,
    "cle_ce_mois": { "depenses": 3, "plafond": 20 }
  }
}

POST`/v1/prospects/:id/trouver-telephone`

CréditsCoordonnée déjà obtenue seulement

Rend gratuitement le numéro déjà obtenu pour ce prospect. Une nouvelle recherche (10 crédits contact, rendus si introuvable) se lance pour l’instant dans l’application : 409 action_compte_requise.

Requête

curl -X POST "https://api.fantomhunt.com/v1/prospects/3f6c2a10-8b4e-4d2a-9c1f-5e7a9b0d1c22/trouver-telephone" \
  -H "Authorization: Bearer fh_live_VOTRE_CLE"

Réponse (409)

{
  "error": "action_compte_requise",
  "message": "Cette modification est temporairement réservée à l’application, car son éventuelle reprise par une automatisation ne peut pas encore être attribuée à la clé API. Les notes et les tâches restent disponibles par API, même lorsque les automatisations sont en pause."
}

Avant votre première requête, vos questions.

Faut-il une offre payante pour utiliser l’API ?

Oui : Essentiel ou Croissance. Essentiel coûte 29 € par mois sans engagement, ou 19 € par mois avec engagement d’un an. L’offre est revérifiée à chaque appel : un compte repassé en Découverte reçoit 403 plan_requis, même avec une clé active.

Existe-t-il une clé de test ou un bac à sable ?

Non : toute clé lit et agit sur votre vrai compte. Pour vos essais, créez une clé en lecture seule, le droit par défaut. Les exemples de cette page montrent les réponses sur un compte d’exemple, sans rien envoyer.

Mon compte LinkedIn risque-t-il plus avec l’API ?

Non : les envois par l’API suivent les mêmes plafonds que l’application, le même frein après des refus, et partent par l’extension, depuis votre navigateur. Au plus 100 invitations par jour et 300 par semaine.

Mon navigateur doit-il rester ouvert ?

Pour LinkedIn, oui : un message ou une invitation répond 202 et attend dans la file de l’extension, la réponse dit pourquoi dans attentes. WhatsApp et email partent du serveur : la réponse est 201, le message est parti.

Pourquoi certaines écritures répondent-elles 409 ?

L’ajout de personnes, les changements de statut, de rendez-vous, d’offre ou d’étiquettes, le Score IA et les nouvelles recherches d’email ou de téléphone se font pour l’instant dans l’application : une automatisation qu’ils déclencheraient ne peut pas encore être rattachée à la clé qui l’a lancée. La requête est refusée avant toute écriture, rien n’est débité.

Comment éviter les doublons ?

Ajoutez l’en-tête Idempotency-Key à vos requêtes POST : une requête rejouée rend la première réponse au lieu d’agir deux fois. Retrouvez une fiche par email, lien LinkedIn ou téléphone, et gardez l’identifiant FantomHunt de chaque fiche dans votre outil.

Quels langages puis-je utiliser ?

Tout langage qui envoie une requête HTTPS. Chaque exemple de cette page est donné en curl, JavaScript et Python. Pour Claude Code ou Cursor, la même clé sert au serveur MCP.

Pour Claude Code ou Cursor : brancher Claude Code ou Cursor avec la même clé.

Votre clé, vos droits, vos plafonds.

Ouvrir l’API avec Essentiel

Lecture seule par défaut
Plafond de dépense obligatoire
29 € par mois, sans engagement

Votre clé API, vérifiée en un appel.

Créer la clé, puis la vérifier

Ce qu’il faut pour brancher l’API

Une adresse, une clé, des réponses prévisibles.

Cinq droits, cochés un à un.

Une clé qui fuit ? Révoquez-la

Ce que l’API ne fait pas encore

Des erreurs qui disent quoi faire, rien ne passe en silence.

Les statuts

Lire et filtrer, sans laisser filer un prospect.

GET/v1/moi

GET/v1/etat

GET/v1/prospects

GET/v1/prospects/:id

GET/v1/prospects/:id/journal

GET/v1/prospects/:id/conversation

GET/v1/contacts-whatsapp

GET/v1/contacts-whatsapp/:id

GET/v1/contacts-whatsapp/:id/conversation

GET/v1/contacts-email

GET/v1/contacts-email/:id

GET/v1/contacts-email/:id/conversation

GET/v1/taches

GET/v1/affaires

GET/v1/affaires/:id

GET/v1/affaires-colonnes

GET/v1/campagnes

GET/v1/campagnes/:id

GET/v1/campagnes/:id/prospects

GET/v1/offres

GET/v1/offres/:id

GET/v1/offres/:id/messages-types

GET/v1/stats

GET/v1/stats/canaux

GET/v1/stats/quotidien

GET/v1/stats/etapes

GET/v1/stats/ab

GET/v1/stats/horaires

GET/v1/stats/segments

GET/v1/stats/pipeline

GET/v1/stats/resultats-commerciaux

GET/v1/rdv

GET/v1/recherches

GET/v1/recherches/:id

GET/v1/recherches-automatiques

GET/v1/changements-poste

GET/v1/audiences

GET/v1/equipe

GET/v1/etiquettes

Écrire dans votre suivi, sans rien envoyer.

POST/v1/prospects

PATCH/v1/prospects/:id

POST/v1/prospects/:id/journal

POST/v1/contacts-whatsapp

PATCH/v1/contacts-whatsapp/:id

POST/v1/contacts-whatsapp/:id/journal

POST/v1/contacts-email

PATCH/v1/contacts-email/:id

POST/v1/contacts-email/:id/journal

POST/v1/taches

PATCH/v1/taches/:id

DELETE/v1/taches/:id

POST/v1/affaires

PATCH/v1/affaires/:id

POST/v1/affaires/:id/personnes

POST/v1/etiquettes

Envoyer depuis vos outils, avec vos plafonds.

POST/v1/prospects/:id/message

POST/v1/prospects/:id/invitation

POST/v1/contacts-whatsapp/:id/message

POST/v1/contacts-email/:id/message

POST/v1/campagnes/:id/prospects

PATCH/v1/campagnes/:id

POST/v1/recherches

POST/v1/recherches/:id/annuler

Dépenser des crédits, jamais au-delà du plafond.

POST/v1/ia/estimer

POST/v1/ia/message

POST/v1/ia/scorer

POST/v1/ia/modeles-offre

GET`/v1/moi`

GET`/v1/etat`

GET`/v1/prospects`

GET`/v1/prospects/:id`

GET`/v1/prospects/:id/journal`

GET`/v1/prospects/:id/conversation`

GET`/v1/contacts-whatsapp`

GET`/v1/contacts-whatsapp/:id`

GET`/v1/contacts-whatsapp/:id/conversation`

GET`/v1/contacts-email`

GET`/v1/contacts-email/:id`

GET`/v1/contacts-email/:id/conversation`

GET`/v1/taches`

GET`/v1/affaires`

GET`/v1/affaires/:id`

GET`/v1/affaires-colonnes`

GET`/v1/campagnes`

GET`/v1/campagnes/:id`

GET`/v1/campagnes/:id/prospects`

GET`/v1/offres`

GET`/v1/offres/:id`

GET`/v1/offres/:id/messages-types`

GET`/v1/stats`

GET`/v1/stats/canaux`

GET`/v1/stats/quotidien`

GET`/v1/stats/etapes`

GET`/v1/stats/ab`

GET`/v1/stats/horaires`

GET`/v1/stats/segments`

GET`/v1/stats/pipeline`

GET`/v1/stats/resultats-commerciaux`

GET`/v1/rdv`

GET`/v1/recherches`

GET`/v1/recherches/:id`

GET`/v1/recherches-automatiques`

GET`/v1/changements-poste`

GET`/v1/audiences`

GET`/v1/equipe`

GET`/v1/etiquettes`

POST`/v1/prospects`

PATCH`/v1/prospects/:id`

POST`/v1/prospects/:id/journal`

POST`/v1/contacts-whatsapp`

PATCH`/v1/contacts-whatsapp/:id`

POST`/v1/contacts-whatsapp/:id/journal`

POST`/v1/contacts-email`

PATCH`/v1/contacts-email/:id`

POST`/v1/contacts-email/:id/journal`

POST`/v1/taches`

PATCH`/v1/taches/:id`

DELETE`/v1/taches/:id`

POST`/v1/affaires`

PATCH`/v1/affaires/:id`

POST`/v1/affaires/:id/personnes`

POST`/v1/etiquettes`

POST`/v1/prospects/:id/message`

POST`/v1/prospects/:id/invitation`

POST`/v1/contacts-whatsapp/:id/message`

POST`/v1/contacts-email/:id/message`

POST`/v1/campagnes/:id/prospects`

PATCH`/v1/campagnes/:id`

POST`/v1/recherches`

POST`/v1/recherches/:id/annuler`

POST`/v1/ia/estimer`

POST`/v1/ia/message`

POST`/v1/ia/scorer`

POST`/v1/ia/modeles-offre`

POST`/v1/ia/sequence-campagne`

POST`/v1/prospects/:id/trouver-email`

POST`/v1/prospects/:id/trouver-telephone`