Gemlead
Docs
Accedi
Ottieni la tua chiave API

Riferimento API

Lead

I lead sono le persone che Gemlead trova su X per le tue buyer persona. Dana AI valuta ognuno da 0 a 100, e un lead è caldo da 60 in su. Elencali con dei filtri, aggiungi i tuoi metadati come un ID del CRM, oppure agisci su uno come faresti nell'app.

Endpoint

L'oggetto lead

Qualcuno che Gemlead ha trovato su X per una delle tue buyer persona, con il punteggio che gli ha dato Dana AI e il punto in cui si trova nel tuo outreach.

Attributi

  • idstring
    Identificatore univoco del lead.
  • objectstring
    Sempre lead.
  • profileobject
    Il profilo X del lead.
  • scoreinteger o null
    Quanto il lead corrisponde alla tua buyer persona, da 0 a 100. Null finché non è valutato.
  • score_reasonstring o null
    Perché il lead ha ricevuto questo punteggio, in una o due frasi.
  • hotboolean
    True quando il punteggio è 60 o più.
  • statusstring
    Dove si trova il lead nella tua pipeline.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • personaobject o null
    La buyer persona per cui è stato trovato il lead.
  • campaignobject o null
    La campagna in cui si trova il lead, se c'è.
  • conversation_idstring o null
    La conversazione con il lead, quando esiste. Usala con Recupera una conversazione.
  • locked_toobject o null
    L'unico account X del proprietario a cui è riservato questo lead. Un lead va a un solo account X, quindi gli altri non lo contattano mai. Null finché nessuno ha in carico il lead.
  • found_atstring
    Quando Gemlead ha trovato il lead, ISO 8601.
  • scored_atstring o null
    Quando il lead è stato valutato, ISO 8601.
  • updated_atstring
    Quando il lead è cambiato l'ultima volta, ISO 8601.
  • metadataobject
    Le tue coppie chiave-valore, impostate con Aggiorna un lead.
L'oggetto 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": {}
}

Elenca i lead

GET/v1/leadsScope readMCPsearch_leads

Restituisce i tuoi lead, di default prima gli ultimi valutati. Combina i filtri per ottenere esattamente i lead che vuoi.

Parametri di query

  • personastring
    Solo i lead della buyer persona con questo ID.
  • statusstring
    Solo i lead in questi stati, separati da virgole, come scored,in_campaign.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • score_mininteger
    Solo i lead con almeno questo punteggio, da 0 a 100.
  • score_maxinteger
    Solo i lead con al massimo questo punteggio, da 0 a 100.
  • hotboolean
    true per i lead con un punteggio di 60 o più, false per gli altri.
  • scored_afterstring
    Solo i lead valutati dopo questo momento, ISO 8601.
  • scored_beforestring
    Solo i lead valutati prima di questo momento, ISO 8601.
  • found_afterstring
    Solo i lead trovati dopo questo momento, ISO 8601.
  • found_beforestring
    Solo i lead trovati prima di questo momento, ISO 8601.
  • orderstring
    L'ordinamento. Di default -scored_at, prima gli ultimi valutati.
    -scored_at-score-found_at
  • limitinteger
    Quanti oggetti restituire, da 1 a 100. Di default 25.
  • cursorstring
    Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti lead.

Errori

  • 400parameter_invalid
    Un parametro ha un valore che l'API non accetta. param lo indica.
GET/v1/leads
curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=10
Risposta200
{
  "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"
}

Recupera un lead

GET/v1/leads/:idScope readMCPget_lead

Restituisce un lead.

Parametri di percorso

  • idstringObbligatorio
    L'ID del lead.

Restituisce

Un oggetto lead.

Errori

GET/v1/leads/:id
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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": {}
}

Aggiorna un lead

PATCH/v1/leads/:idScope writeMCPupdate_lead

Imposta i tuoi metadati su un lead, oppure lo chiude quando hai finito di lavorarci. Chiudere un lead ferma i passaggi di campagna ancora in sospeso per quel lead, così Gemlead smette di scrivergli.

Parametri di percorso

  • idstringObbligatorio
    L'ID del lead.

Parametri del body

  • metadataobject
    Coppie chiave-valore unite ai metadati del lead. Chiavi fino a 40 caratteri tra lettere, cifre, _ o -, valori stringa fino a 500 caratteri, al massimo 20 chiavi. Imposta una chiave su null o su una stringa vuota per rimuoverla, oppure metadata su null per cancellarle tutte.
  • statusstring
    Impostalo su closed per chiudere il lead.
    closed

Restituisce

L'oggetto lead aggiornato.

Errori

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"
    }
  }'
Risposta200
{
  "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"
  }
}

Rivaluta un lead

POST/v1/leads/:lead_id/rescoreScope writeMCPlead_action

Chiede a Dana AI di valutare di nuovo il lead rispetto alla sua buyer persona, per esempio dopo che ne hai cambiato la descrizione. Usa fino a 2 crediti per lead: 1 per la prima valutazione, 1 in più per quella approfondita se il lead la supera.

Parametri di percorso

  • lead_idstringObbligatorio
    L'ID del lead.

Restituisce

L'oggetto lead.

Errori

  • 404resource_missing
    Nessun lead con questo ID sull'account della chiave.
  • 502upstream_unavailable
    X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra un minuto.
POST/v1/leads/:lead_id/rescore
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/rescore \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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": {}
}

Aggiorna il profilo di un lead

POST/v1/leads/:lead_id/refreshScope writeMCPlead_action

Rilegge il profilo X del lead, per una nuova bio, una nuova foto o un nuovo numero di follower.

Parametri di percorso

  • lead_idstringObbligatorio
    L'ID del lead.

Restituisce

L'oggetto lead aggiornato.

Errori

  • 404resource_missing
    Nessun lead con questo ID sull'account della chiave.
  • 409x_session_expired
    La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.
  • 502upstream_unavailable
    X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra un minuto.
POST/v1/leads/:lead_id/refresh
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/refresh \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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": {}
}

Segui un lead

POST/v1/leads/:lead_id/followScope writeMCPlead_action

Segue subito il lead su X dal tuo account X.

Parametri di percorso

  • lead_idstringObbligatorio
    L'ID del lead.

Restituisce

L'oggetto lead.

Errori

POST/v1/leads/:lead_id/follow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/follow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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": {}
}

Smetti di seguire un lead

POST/v1/leads/:lead_id/unfollowScope writeMCPlead_action

Smette subito di seguire il lead su X dal tuo account X.

Parametri di percorso

  • lead_idstringObbligatorio
    L'ID del lead.

Restituisce

L'oggetto lead.

Errori

  • 404resource_missing
    Nessun lead con questo ID sull'account della chiave.
  • 400lead_without_x_id
    Il lead non ha un ID account X, quindi non si può smettere di seguirlo.
  • 409x_session_expired
    La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.
  • 502upstream_unavailable
    X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra un minuto.
POST/v1/leads/:lead_id/unfollow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/unfollow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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": {}
}

Trasforma un lead in una fonte

POST/v1/leads/:lead_id/convert_to_sourceScope writeMCPconvert_lead_to_source

Fa di un ottimo lead una fonte della sua buyer persona, per trovare altre persone simili. Gemlead legge chi segue, i suoi follower o chi commenta i suoi post.

Parametri di percorso

  • lead_idstringObbligatorio
    L'ID del lead.

Parametri del body

  • methodstring
    following legge chi segue il lead, competitor_followers i suoi follower, competitor_comments chi commenta i suoi post. Di default following.
    followingcompetitor_followerscompetitor_comments

Restituisce

Un oggetto con il lead_id, il suo persona_id, il method e la nuova fonte, oppure lo username competitor_account per competitor_comments.

Errori

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"
  }'
Risposta200
{
  "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
}

Elimina un lead

DELETE/v1/leads/:lead_idScope writeMCPdelete_lead

Elimina un lead. Esce dai tuoi elenchi, ogni campagna si ferma per lui e Gemlead non ti riproporrà questo profilo per questa buyer persona. Per tenere qualcuno fuori da tutte le buyer persona, aggiungilo alla lista di esclusione.

Parametri di percorso

  • lead_idstringObbligatorio
    L'ID del lead.

Restituisce

Un oggetto con l'id del lead e deleted impostato su true.

Errori

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

L'oggetto origine del lead

Come Gemlead ha trovato un lead, il post che lo ha fatto emergere e ogni campagna in cui si trova.

Attributi

  • objectstring
    Sempre lead_origin.
  • lead_idstring
    L'ID del lead.
  • personaobject o null
    La buyer persona per cui è stato trovato.
  • methodstring o null
    Come è stato trovato.
    followingkeywordscompetitor_followerscompetitor_comments
  • found_querystring o null
    La ricerca per parola chiave che lo ha trovato, per keywords.
  • source_usernamestring o null
    La fonte o l'account concorrente attraverso cui è stato trovato.
  • found_postobject o null
    Il post che ha fatto emergere il lead, quando c'è.
  • campaignsarray di objects
    Le campagne in cui si trova il lead, ognuna con il suo id, il name, lo status del lead al suo interno, il method della campagna e lo step a cui è arrivato il lead.
L'oggetto origine del 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"
    }
  ]
}

Recupera l'origine di un lead

GET/v1/leads/:lead_id/originScope readMCPget_lead_origin

Restituisce come Gemlead ha trovato il lead, il post che lo ha fatto emergere e ogni campagna in cui si trova, con il passaggio a cui è arrivato.

Parametri di percorso

  • lead_idstringObbligatorio
    L'ID del lead.

Restituisce

Un oggetto origine del lead.

Errori

GET/v1/leads/:lead_id/origin
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT/origin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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"
    }
  ]
}
Ricevi gli aggiornamenti di Gemlead
direttamente nella tua casella email.
Iscriviti
Iscrivendoti accetti la nostra Informativa sulla privacy e acconsenti a ricevere aggiornamenti dalla nostra azienda.
Gemlead
Prodotto
Inizia
Accedi
Per chi
Agenti IA
Funzionalità
Prezzi
Affiliazione
FAQ
Funzionalità
Acquirenti, 24/7Prima i lead caldiOltre il 60% rispondeDM su misuraTutti i DM in un'inboxIl tuo closer IAScala senza limitiAPI, MCP, webhookChiedi a Gemlead
Risorse
HomeAPIBlog
Note legali
Termini
Privacy
© 2026 Gemlead, Inc. Tutti i diritti riservati.
Italiano