La référence de l’API.

Référence API

Base : https://api.fantomhunt.com/v1 · Authentification : Authorization: Bearer fh_live_… · Quota : 120 requêtes par minute et par clé (en-têtes RateLimit-* sur chaque réponse). Une limite par adresse s’ajoute : 600 requêtes par minute. Les prospects et les contacts se paginent : la réponse est { donnees, curseur_suivant }, repassez curseur pour la page suivante (limite : 50 par défaut, 200 maximum ; curseur_suivant vaut null à la dernière page). Les autres listes renvoient { donnees } en une fois. Les dates sont en ISO 8601 (UTC), les montants des affaires en centimes.

Les prospects, filtrés

statut (voir le tableau ci-dessous), etiquette, recherche, campagne, offre (identifiants), score_min, q (nom, entreprise ou poste), les dates cree_depuis, contacte_depuis, repondu_depuis, et modifie_depuis (date ISO) pour ne tirer que ce qui a bougé — le mécanisme idéal pour une synchronisation périodique. Plusieurs statuts à la fois : statut=replied,rdv. Pour retrouver la fiche d’une personne que votre CRM connaît : email, url_linkedin (avec ou sans https://) ou telephone (06…, +33 6… : même numéro).

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

curl -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  "https://api.fantomhunt.com/v1/prospects?statut=replied,rdv&repondu_depuis=2026-09-01&limite=50"

curl -H "Authorization: Bearer fh_live_VOTRE_CLE" \
  "https://api.fantomhunt.com/v1/prospects?email=martin@acme.fr"

{
  "donnees": [{
"id": "6f2b…", "nom": "Martin Dupont", "entreprise": "Acme",
"poste": "Directeur commercial", "url_linkedin": "https://www.linkedin.com/in/…",
"localisation": "Lyon", "email": "martin@acme.fr", "email_score": 95,
"telephone": "+33612345678", "statut": "replied", "score": 82,
"source": "extension", "recherche_id": "…", "offre_id": "…",
"offre": { "id": "…", "nom": "Paie externalisée" },
"etiquettes": [{ "id": "…", "nom": "Chaud", "couleur": "#ff5555" }],
"campagnes": [{ "id": "…", "nom": "Relance DAF" }],
"cree_le": "…", "modifie_le": "…", "contacte_le": "…",
"connecte_le": "…", "repondu_le": "…", "rdv_le": null
  }],
  "curseur_suivant": "eyJ0Ijoi…"
}

Les conversations

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 maximum ; pour remonter plus loin, repassez avant_suivant dans avant.

{
  "donnees": [
{ "canal": "email", "id": "…", "sens": "recu", "objet": "Re: votre offre",
  "texte": "Oui, appelons-nous jeudi.", "date": "2026-09-24T09:12:00.000Z",
  "media": null, "reponse_automatique": false, "non_verifie": false },
{ "canal": "linkedin", "id": "…", "sens": "envoye", "objet": null,
  "texte": "Bonjour Martin, …", "date": "2026-09-22T08:30:00.000Z",
  "media": null, "reponse_automatique": false, "non_verifie": false }
  ],
  "avant_suivant": null
}

Modifier le CRM

Avec une clé qui a le droit crm (« Modifier le CRM », décoché par défaut). Chaque modification passe par le même chemin que l’application : la personne est une (note, offre, étiquettes et statut client suivent sur ses autres canaux), le rendez-vous arrive dans votre agenda connecté, le journal et les webhooks suivent. Tout est vérifié avant d’écrire : une requête refusée ne laisse rien à moitié fait. Rien ne part vers un prospect et aucun crédit n’est dépensé.

curl -X PATCH https://api.fantomhunt.com/v1/prospects/6f2b… \
  -H "Authorization: Bearer fh_live_VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{ "statut": "rdv", "rdv_le": "2026-10-02T09:30:00Z", "rdv_duree_min": 30,
    "etiquettes_ajouter": ["Chaud"], "note": "Budget validé en comité" }'

Les statuts d’un prospect : nouveau, pending_connection, contacted, connected, replied, rdv, snoozed, client, not_interested, off_topic, archived, ecarte. Les gardes de l’application s’appliquent aussi aux intégrations : un parcours ne recule pas, une fiche close (client, pas intéressé, archivée…) n’est pas rouverte. Dans ce cas la réponse reste 200, la fiche est rendue telle quelle et un champ avertissements l’explique. Un champ inconnu est refusé (400) plutôt qu’ignoré : une faute de frappe ne passe pas en silence.

Rejouer sans doublon : ajoutez l’en-tête Idempotency-Key (une valeur unique par action, 200 caractères au plus) à vos créations. 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) au lieu de créer une seconde tâche. La clé vaut 24 heures, pour une seule requête.

Envoyer

Avec une clé qui a le droit envoyer (décoché par défaut). Ça part tout de suite, sans relecture dans l’application, exactement comme un envoi fait à la main : mêmes plafonds (invitations LinkedIn 100 par jour et 300 par semaine, vos limites WhatsApp et, pour l’email, celles de chaque boîte), même frein LinkedIn, même conversation. Donnez ce droit seulement à un outil de confiance.

Un message ou une invitation LinkedIn part quand l’extension peut l’envoyer. La réponse 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.

{
  "canal": "linkedin", "prospect_id": "6f2b…", "envoi_id": "a41c…",
  "statut_envoi": "en_file",
  "attentes": ["Hors de vos horaires d’envoi : l’envoi partira à la prochaine plage."]
}

Dépenser des crédits

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 Réglages sans changer de clé). Chaque action est d’abord estimée par le même calcul que la fenêtre de confirmation de l’application, 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.

{
  "prospect_id": "6f2b…", "mode": "premier_message",
  "message": "Bonjour Martin, j’ai vu votre parcours chez Acme…",
  "conseils": "Si réponse positive : proposer un créneau…",
  "credits": { "type": "ia", "estimes": 4, "debites": 4,
           "cle_ce_mois": { "depenses": 12, "plafond": 100 } }
}

Les erreurs, normalisées

Toujours { "error": code_stable, "message": explication } — le code se teste en machine, le message se lit.