Gemlead
Docs
Se connecter
Obtenir ta clé API

Référence API

Leads

Les leads sont les personnes que Gemlead trouve sur X pour tes personas. Dana AI score chacun de 0 à 100, et un lead est chaud à partir de 60. Liste-les avec des filtres, ajoute tes propres métadonnées comme un ID de CRM, ou agis sur un lead comme tu le ferais dans l'app.

Endpoints

L'objet lead

Une personne que Gemlead a trouvée sur X pour un de tes personas, avec le score que Dana AI lui a donné et où elle en est dans ta prospection.

Attributs

  • idstring
    Identifiant unique du lead.
  • objectstring
    Toujours lead.
  • profileobject
    Le profil X du lead.
  • scoreinteger ou null
    À quel point le lead correspond à ton persona, de 0 à 100. Null tant qu'il n'est pas scoré.
  • score_reasonstring ou null
    Pourquoi le lead a eu ce score, en une ou deux phrases.
  • hotboolean
    Vaut true quand le score est de 60 ou plus.
  • statusstring
    Où en est le lead dans ton pipeline.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • personaobject ou null
    Le persona pour lequel le lead a été trouvé.
  • campaignobject ou null
    La campagne du lead, s'il y en a une.
  • conversation_idstring ou null
    La conversation avec le lead, dès qu'elle existe. Utilise-la avec Récupérer une conversation.
  • locked_toobject ou null
    Le seul compte X du propriétaire auquel cette personne est réservée. Un lead ne va qu'à un compte X, les autres ne le contactent donc jamais. Null tant que rien ne retient le lead.
  • found_atstring
    Date à laquelle Gemlead a trouvé le lead, en ISO 8601.
  • scored_atstring ou null
    Date à laquelle le lead a été scoré, en ISO 8601.
  • updated_atstring
    Date de la dernière modification du lead, en ISO 8601.
  • metadataobject
    Tes propres paires clé-valeur, définies avec Modifier un lead.
L'objet lead
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "score": 86,
  "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
  "hot": true,
  "status": "scored",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "campaign": null,
  "conversation_id": null,
  "locked_to": null,
  "found_at": "2026-11-05T14:02:11.482Z",
  "scored_at": "2026-11-05T14:03:40.117Z",
  "updated_at": "2026-11-05T14:03:40.117Z",
  "metadata": {}
}

Lister les leads

GET/v1/leadsScope readMCPsearch_leads

Renvoie tes leads, les plus récemment scorés en premier par défaut. Combine les filtres pour obtenir exactement les leads que tu veux.

Paramètres de requête

  • personastring
    Seulement les leads du persona avec cet ID.
  • statusstring
    Seulement les leads avec ces statuts, séparés par des virgules, comme scored,in_campaign.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • score_mininteger
    Seulement les leads avec au moins ce score, de 0 à 100.
  • score_maxinteger
    Seulement les leads avec au plus ce score, de 0 à 100.
  • hotboolean
    true pour les leads avec un score de 60 ou plus, false pour les autres.
  • scored_afterstring
    Seulement les leads scorés après cette date, en ISO 8601.
  • scored_beforestring
    Seulement les leads scorés avant cette date, en ISO 8601.
  • found_afterstring
    Seulement les leads trouvés après cette date, en ISO 8601.
  • found_beforestring
    Seulement les leads trouvés avant cette date, en ISO 8601.
  • orderstring
    L'ordre de tri. -scored_at par défaut, les plus récemment scorés en premier.
    -scored_at-score-found_at
  • limitinteger
    Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
  • cursorstring
    Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets lead.

Erreurs

  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
GET/v1/leads
curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=10
Réponse200
{
  "object": "list",
  "data": [
    {
      "id": "msgOtJ8dvT",
      "object": "lead",
      "profile": {
        "x_user_id": "1460283925",
        "username": "jane_builds",
        "name": "Jane Doe",
        "bio": "Runs a paid trading community. Daily setups, no hype.",
        "followers_count": 12400,
        "following_count": 380,
        "location": "Austin, TX",
        "website": "https://janedoe.com",
        "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
        "verified": true,
        "url": "https://x.com/jane_builds"
      },
      "score": 86,
      "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
      "hot": true,
      "status": "scored",
      "persona": {
        "id": "lvWBPnytpS",
        "name": "Tipsters"
      },
      "campaign": null,
      "conversation_id": null,
      "locked_to": null,
      "found_at": "2026-11-05T14:02:11.482Z",
      "scored_at": "2026-11-05T14:03:40.117Z",
      "updated_at": "2026-11-05T14:03:40.117Z",
      "metadata": {}
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0"
}

Récupérer un lead

GET/v1/leads/:idScope readMCPget_lead

Renvoie un lead.

Paramètres de chemin

  • idstringObligatoire
    L'ID du lead.

Renvoie

Un objet lead.

Erreurs

GET/v1/leads/:id
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "score": 86,
  "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
  "hot": true,
  "status": "scored",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "campaign": null,
  "conversation_id": null,
  "locked_to": null,
  "found_at": "2026-11-05T14:02:11.482Z",
  "scored_at": "2026-11-05T14:03:40.117Z",
  "updated_at": "2026-11-05T14:03:40.117Z",
  "metadata": {}
}

Modifier un lead

PATCH/v1/leads/:idScope writeMCPupdate_lead

Ajoute tes propres métadonnées à un lead, ou le clôture quand tu en as fini avec lui. Clôturer un lead arrête les étapes de campagne encore en attente pour lui, et Gemlead ne lui écrit plus.

Paramètres de chemin

  • idstringObligatoire
    L'ID du lead.

Paramètres du corps

  • metadataobject
    Paires clé-valeur fusionnées dans les métadonnées du lead. Clés de 40 lettres, chiffres, _ ou - au plus, valeurs en chaînes de 500 caractères au plus, 20 clés maximum. Mets une clé à null ou à une chaîne vide pour la retirer, ou metadata à null pour tout effacer.
  • statusstring
    Indique closed pour clôturer le lead.
    closed

Renvoie

L'objet lead à jour.

Erreurs

PATCH/v1/leads/:id
curl -X PATCH https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "crm_id": "hs_48213"
    }
  }'
Réponse200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "score": 86,
  "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
  "hot": true,
  "status": "scored",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "campaign": null,
  "conversation_id": null,
  "locked_to": null,
  "found_at": "2026-11-05T14:02:11.482Z",
  "scored_at": "2026-11-05T14:03:40.117Z",
  "updated_at": "2026-11-05T14:03:40.117Z",
  "metadata": {
    "crm_id": "hs_48213"
  }
}

Rescorer un lead

POST/v1/leads/:lead_id/rescoreScope writeMCPlead_action

Demande à Dana AI de rescorer le lead par rapport à son persona, par exemple après une modification de sa description. Coûte jusqu'à 2 crédits par lead : 1 pour le premier tri, 1 de plus pour le score approfondi s'il passe ce tri.

Paramètres de chemin

  • lead_idstringObligatoire
    L'ID du lead.

Renvoie

L'objet lead.

Erreurs

POST/v1/leads/:lead_id/rescore
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/rescore \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "score": 86,
  "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
  "hot": true,
  "status": "scored",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "campaign": null,
  "conversation_id": null,
  "locked_to": null,
  "found_at": "2026-11-05T14:02:11.482Z",
  "scored_at": "2026-11-05T14:03:40.117Z",
  "updated_at": "2026-11-05T14:03:40.117Z",
  "metadata": {}
}

Actualiser un lead

POST/v1/leads/:lead_id/refreshScope writeMCPlead_action

Relit le profil X du lead, pour une nouvelle bio, une nouvelle photo ou un nouveau nombre d'abonnés.

Paramètres de chemin

  • lead_idstringObligatoire
    L'ID du lead.

Renvoie

L'objet lead à jour.

Erreurs

  • 404resource_missing
    Aucun lead avec cet ID sur le compte de la clé.
  • 409x_session_expired
    La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.
  • 502upstream_unavailable
    X ou un service Gemlead n'a pas répondu. Rien n'a changé, réessaie dans une minute.
POST/v1/leads/:lead_id/refresh
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/refresh \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "score": 86,
  "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
  "hot": true,
  "status": "scored",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "campaign": null,
  "conversation_id": null,
  "locked_to": null,
  "found_at": "2026-11-05T14:02:11.482Z",
  "scored_at": "2026-11-05T14:03:40.117Z",
  "updated_at": "2026-11-05T14:03:40.117Z",
  "metadata": {}
}

Suivre un lead

POST/v1/leads/:lead_id/followScope writeMCPlead_action

Suit immédiatement le lead sur X depuis ton compte X.

Paramètres de chemin

  • lead_idstringObligatoire
    L'ID du lead.

Renvoie

L'objet lead.

Erreurs

POST/v1/leads/:lead_id/follow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/follow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "score": 86,
  "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
  "hot": true,
  "status": "scored",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "campaign": null,
  "conversation_id": null,
  "locked_to": null,
  "found_at": "2026-11-05T14:02:11.482Z",
  "scored_at": "2026-11-05T14:03:40.117Z",
  "updated_at": "2026-11-05T14:03:40.117Z",
  "metadata": {}
}

Ne plus suivre un lead

POST/v1/leads/:lead_id/unfollowScope writeMCPlead_action

Arrête immédiatement de suivre le lead sur X depuis ton compte X.

Paramètres de chemin

  • lead_idstringObligatoire
    L'ID du lead.

Renvoie

L'objet lead.

Erreurs

  • 404resource_missing
    Aucun lead avec cet ID sur le compte de la clé.
  • 400lead_without_x_id
    Le lead n'a pas d'ID de compte X, on ne peut donc pas arrêter de le suivre.
  • 409x_session_expired
    La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.
  • 502upstream_unavailable
    X ou un service Gemlead n'a pas répondu. Rien n'a changé, réessaie dans une minute.
POST/v1/leads/:lead_id/unfollow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/unfollow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "score": 86,
  "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
  "hot": true,
  "status": "scored",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "campaign": null,
  "conversation_id": null,
  "locked_to": null,
  "found_at": "2026-11-05T14:02:11.482Z",
  "scored_at": "2026-11-05T14:03:40.117Z",
  "updated_at": "2026-11-05T14:03:40.117Z",
  "metadata": {}
}

Faire d'un lead une source

POST/v1/leads/:lead_id/convert_to_sourceScope writeMCPconvert_lead_to_source

Fait d'un excellent lead une source de son persona, pour trouver plus de gens comme lui. Gemlead lit ses abonnements, ses abonnés ou ceux qui commentent ses posts.

Paramètres de chemin

  • lead_idstringObligatoire
    L'ID du lead.

Paramètres du corps

  • methodstring
    following lit les abonnements du lead, competitor_followers ses abonnés, competitor_comments ceux qui commentent ses posts. following par défaut.
    followingcompetitor_followerscompetitor_comments

Renvoie

Un objet avec le lead_id, son persona_id, la method et la nouvelle source, ou le nom d'utilisateur competitor_account pour competitor_comments.

Erreurs

POST/v1/leads/:lead_id/convert_to_source
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/convert_to_source \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "following"
  }'
Réponse200
{
  "object": "lead_conversion",
  "lead_id": "msgOtJ8dvT",
  "persona_id": "lvWBPnytpS",
  "method": "following",
  "source": {
    "id": "s9KdT3pXwM",
    "object": "source",
    "persona_id": "lvWBPnytpS",
    "method": "following",
    "profile": {
      "username": "pickswithmike",
      "name": "Mike Picks",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1722093311/mike_400x400.jpg",
      "followers_count": 8400,
      "following_count": 1210,
      "url": "https://x.com/pickswithmike"
    },
    "status": "pending",
    "paused": false,
    "error": null,
    "read_following": true,
    "read_followers": false,
    "score_self": true,
    "self_lead_id": "Lp4WqZ7sXe",
    "origin_lead_id": "msgOtJ8dvT",
    "stats": {
      "leads": 1184,
      "scored_leads": 1160,
      "hot_leads": 212,
      "avg_score": 44
    },
    "last_activity_at": "2026-11-05T14:03:40.117Z",
    "last_scraped_at": "2026-11-05T14:02:11.482Z",
    "created_at": "2026-09-14T09:21:05.300Z"
  },
  "competitor_account": null
}

Supprimer un lead

DELETE/v1/leads/:lead_idScope writeMCPdelete_lead

Supprime un lead. Il disparaît de tes listes, toutes les campagnes s'arrêtent pour lui, et Gemlead ne ramène pas la même personne pour ce persona. Pour écarter quelqu'un de tous les personas, ajoute-le à la liste d'exclusion.

Paramètres de chemin

  • lead_idstringObligatoire
    L'ID du lead.

Renvoie

Un objet avec l'id du lead et deleted à true.

Erreurs

DELETE/v1/leads/:lead_id
curl -X DELETE https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "deleted": true
}

L'objet origine du lead

Comment Gemlead a trouvé un lead, le post qui l'a fait remonter et chaque campagne où il se trouve.

Attributs

  • objectstring
    Toujours lead_origin.
  • lead_idstring
    L'ID du lead.
  • personaobject ou null
    Le persona pour lequel il a été trouvé.
  • methodstring ou null
    Comment il a été trouvé.
    followingkeywordscompetitor_followerscompetitor_comments
  • found_querystring ou null
    La recherche par mots-clés qui l'a trouvé, pour keywords.
  • source_usernamestring ou null
    La source ou le compte concurrent par lequel il a été trouvé.
  • found_postobject ou null
    Le post qui a fait remonter le lead, s'il y en a un.
  • campaignstableau d'objects
    Les campagnes du lead, chacune avec son id, son name, le status du lead dans cette campagne, la method de la campagne et le step où se trouve le lead.
L'objet origine du lead
{
  "object": "lead_origin",
  "lead_id": "msgOtJ8dvT",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "found_query": "paid discord picks",
  "source_username": null,
  "found_post": {
    "method": "keywords",
    "query": "paid discord picks",
    "post_id": "1985102233445566778",
    "text": "Thinking of moving my paid discord picks to a real checkout. Any tips?",
    "url": "https://x.com/i/status/1985102233445566778",
    "posted_at": "2026-11-05T13:40:02.000Z",
    "found_at": "2026-11-05T14:02:11.482Z"
  },
  "campaigns": [
    {
      "id": "c7RkQ2wLxe",
      "name": "Tipsters warm intro",
      "status": "waiting",
      "method": "keywords",
      "step": "Timer"
    }
  ]
}

Récupérer l'origine d'un lead

GET/v1/leads/:lead_id/originScope readMCPget_lead_origin

Renvoie comment Gemlead a trouvé le lead, le post qui l'a fait remonter et chaque campagne où il se trouve, avec son étape actuelle.

Paramètres de chemin

  • lead_idstringObligatoire
    L'ID du lead.

Renvoie

Un objet origine du lead.

Erreurs

GET/v1/leads/:lead_id/origin
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT/origin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "object": "lead_origin",
  "lead_id": "msgOtJ8dvT",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "found_query": "paid discord picks",
  "source_username": null,
  "found_post": {
    "method": "keywords",
    "query": "paid discord picks",
    "post_id": "1985102233445566778",
    "text": "Thinking of moving my paid discord picks to a real checkout. Any tips?",
    "url": "https://x.com/i/status/1985102233445566778",
    "posted_at": "2026-11-05T13:40:02.000Z",
    "found_at": "2026-11-05T14:02:11.482Z"
  },
  "campaigns": [
    {
      "id": "c7RkQ2wLxe",
      "name": "Tipsters warm intro",
      "status": "waiting",
      "method": "keywords",
      "step": "Timer"
    }
  ]
}
Reçois les nouveautés de Gemlead
directement dans ta boîte mail.
S'abonner
En t'abonnant, tu acceptes notre Politique de confidentialité et l'envoi de nos nouveautés.
Gemlead
Produit
Commencer
Se connecter
Pour qui
Agents IA
Fonctionnalités
Tarifs
Affiliation
FAQ
Fonctionnalités
Tes acheteurs, 24/7Leads chauds d'abord60 %+ de réponsesDes DM sur mesureTous les DM, une inboxTon closer IAScale sans limiteAPI, MCP, webhooksDemande à Gemlead
Ressources
AccueilAPIBlog
Juridique
Conditions
Confidentialité
© 2026 Gemlead, Inc. Tous droits réservés.
Français