API-Referenz
Leads
Leads sind die Personen, die Gemlead auf X für deine Personas findet. Dana AI bewertet jeden auf einer Skala von 0 bis 100, ab 60 ist ein Lead heiß. Liste sie mit Filtern auf, hänge eigene Metadaten wie eine CRM-ID an oder löse bei einem Lead dieselben Aktionen aus wie in der App.
Das Lead-Objekt
Eine Person, die Gemlead auf X für eine deiner Personas gefunden hat, mit dem Score von Dana AI und dem Stand deiner Kontaktaufnahme.
Attribute
- idstringEindeutige Kennung des Leads.
- objectstringImmer
lead. - profileobjectDas X-Profil des Leads.
- scoreinteger oder nullWie gut der Lead zu deiner Persona passt, von 0 bis 100. Null, bis er bewertet ist.
- score_reasonstring oder nullWarum der Lead diesen Score bekommen hat, in ein oder zwei Sätzen.
- hotbooleanTrue, wenn der Score 60 oder mehr beträgt.
- statusstringWo der Lead in deiner Pipeline steht.
pendingscoringscoredin_campaigncontactedin_conversationclosed - personaobject oder nullDie Persona, für die der Lead gefunden wurde.
- campaignobject oder nullDie Kampagne, in der der Lead ist, falls es eine gibt.
- conversation_idstring oder nullDie Unterhaltung mit dem Lead, sobald es eine gibt. Nutze sie mit Unterhaltung abrufen.
- locked_toobject oder nullDas eine X-Konto des Inhabers, für das diese Person reserviert ist. Ein Lead geht nur an ein X-Konto, die anderen kontaktieren ihn also nie. Null, solange der Lead noch keinem Konto zugeordnet ist.
- found_atstringWann Gemlead den Lead gefunden hat, ISO 8601.
- scored_atstring oder nullWann der Lead bewertet wurde, ISO 8601.
- updated_atstringWann sich der Lead zuletzt geändert hat, ISO 8601.
- metadataobjectDeine eigenen Key-Value-Paare, gesetzt mit Lead ändern.
{
"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": {}
}Leads auflisten
Gibt deine Leads zurück, standardmäßig die zuletzt bewerteten zuerst. Kombiniere Filter, um genau die Leads zu bekommen, die du willst.
Query-Parameter
- personastringNur Leads dieser Persona-ID.
- statusstringNur Leads mit diesen Status, durch Kommas getrennt, etwa
scored,in_campaign.pendingscoringscoredin_campaigncontactedin_conversationclosed - score_minintegerNur Leads mit mindestens diesem Score, von 0 bis 100.
- score_maxintegerNur Leads mit höchstens diesem Score, von 0 bis 100.
- hotboolean
truefür Leads mit einem Score von 60 oder mehr,falsefür die anderen. - scored_afterstringNur Leads, die nach diesem Zeitpunkt bewertet wurden, ISO 8601.
- scored_beforestringNur Leads, die vor diesem Zeitpunkt bewertet wurden, ISO 8601.
- found_afterstringNur Leads, die nach diesem Zeitpunkt gefunden wurden, ISO 8601.
- found_beforestringNur Leads, die vor diesem Zeitpunkt gefunden wurden, ISO 8601.
- orderstringDie Sortierung. Standardmäßig
-scored_at, die zuletzt bewerteten zuerst.-scored_at-score-found_at - limitintegerWie viele Objekte zurückgegeben werden, von 1 bis 100. Standardmäßig 25.
- cursorstringDer
next_cursorder vorherigen Seite, um die nächste Seite abzurufen. Siehe Paginierung.
Rückgabe
Eine Liste von Lead-Objekten.
Fehler
- Ein Parameter hat einen Wert, den die API nicht akzeptiert.
paramnennt ihn.
curl -G https://gemlead.ai/api/v1/leads \
-H "Authorization: Bearer $GEMLEAD_API_KEY" \
-d hot=true \
-d limit=10{
"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"
}Lead abrufen
Gibt einen Lead zurück.
Pfadparameter
- idstringErforderlichDie ID des Leads.
Rückgabe
Ein Lead-Objekt.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"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": {}
}Lead ändern
Setzt eigene Metadaten für einen Lead oder schließt ihn, wenn du mit ihm fertig bist. Das Schließen stoppt die Kampagnenschritte, die noch auf ihn warten, Gemlead schreibt ihm also nicht mehr.
Pfadparameter
- idstringErforderlichDie ID des Leads.
Body-Parameter
- metadataobjectKey-Value-Paare, die in die Metadaten des Leads übernommen werden. Keys mit bis zu 40 Buchstaben, Ziffern,
_oder-, Werte als Strings mit bis zu 500 Zeichen, höchstens 20 Keys. Setze einen Key aufnulloder einen leeren String, um ihn zu entfernen, odermetadataaufnull, um alle zu löschen. - statusstringAuf
closedsetzen, um den Lead zu schließen.closed
Rückgabe
Das aktualisierte Lead-Objekt.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
- Ein Parameter hat einen Wert, den die API nicht akzeptiert.
paramnennt ihn. - Der Body enthält ein Feld, das dieser Endpoint nicht akzeptiert.
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"
}
}'{
"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"
}
}Lead neu bewerten
Lässt Dana AI den Lead anhand seiner Persona neu bewerten, zum Beispiel nachdem du die Beschreibung der Persona geändert hast. Kostet bis zu 2 Credits pro Lead: 1 für den ersten Durchgang, 1 weiterer für den Deep Score, wenn der Lead ihn besteht.
Pfadparameter
- lead_idstringErforderlichDie ID des Leads.
Rückgabe
Das Lead-Objekt.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
- X oder ein Gemlead-Dienst hat nicht geantwortet. Nichts wurde geändert, versuche es in einer Minute erneut.
curl -X POST \
https://gemlead.ai/api/v1/leads/msgOtJ8dvT/rescore \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"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": {}
}Lead aktualisieren
Liest das X-Profil des Leads neu ein, für eine neue Bio, ein neues Foto oder eine neue Followerzahl.
Pfadparameter
- lead_idstringErforderlichDie ID des Leads.
Rückgabe
Das aktualisierte Lead-Objekt.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
- Die Sitzung des X-Kontos ist abgelaufen. Verbinde es in der App neu und versuche es dann noch einmal.
- X oder ein Gemlead-Dienst hat nicht geantwortet. Nichts wurde geändert, versuche es in einer Minute erneut.
curl -X POST \
https://gemlead.ai/api/v1/leads/msgOtJ8dvT/refresh \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"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": {}
}Einem Lead folgen
Folgt dem Lead sofort auf X, von deinem X-Konto aus.
Pfadparameter
- lead_idstringErforderlichDie ID des Leads.
Rückgabe
Das Lead-Objekt.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
- Der Lead hat keine X-Konto-ID, daher kann man ihm nicht folgen.
- Die Sitzung des X-Kontos ist abgelaufen. Verbinde es in der App neu und versuche es dann noch einmal.
- X oder ein Gemlead-Dienst hat nicht geantwortet. Nichts wurde geändert, versuche es in einer Minute erneut.
curl -X POST \
https://gemlead.ai/api/v1/leads/msgOtJ8dvT/follow \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"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": {}
}Einem Lead entfolgen
Entfolgt dem Lead sofort auf X, von deinem X-Konto aus.
Pfadparameter
- lead_idstringErforderlichDie ID des Leads.
Rückgabe
Das Lead-Objekt.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
- Der Lead hat keine X-Konto-ID, daher kann man ihm nicht entfolgen.
- Die Sitzung des X-Kontos ist abgelaufen. Verbinde es in der App neu und versuche es dann noch einmal.
- X oder ein Gemlead-Dienst hat nicht geantwortet. Nichts wurde geändert, versuche es in einer Minute erneut.
curl -X POST \
https://gemlead.ai/api/v1/leads/msgOtJ8dvT/unfollow \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"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": {}
}Lead zur Quelle machen
Macht einen sehr guten Lead zur Quelle seiner Persona, um mehr Leute wie ihn zu finden. Gemlead liest, wem er folgt, wer ihm folgt oder wer seine Beiträge kommentiert.
Pfadparameter
- lead_idstringErforderlichDie ID des Leads.
Body-Parameter
- methodstring
followingliest, wem der Lead folgt,competitor_followersseine Follower,competitor_comments, wer seine Beiträge kommentiert. Standardmäßigfollowing.followingcompetitor_followerscompetitor_comments
Rückgabe
Ein Objekt mit lead_id, seiner persona_id, der method und der neuen Quelle, bei competitor_comments stattdessen mit dem Nutzernamen in competitor_account.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
- Der Lead gehört zu keiner Persona.
- Die Persona hat dieses Konto mit dieser Methode schon als Quelle.
- Die Persona hat schon 100 Konkurrenzkonten.
- Ein Parameter hat einen Wert, den die API nicht akzeptiert.
paramnennt ihn. - X oder ein Gemlead-Dienst hat nicht geantwortet. Nichts wurde geändert, versuche es in einer Minute erneut.
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"
}'{
"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
}Lead löschen
Löscht einen Lead. Er verschwindet aus deinen Listen, jede Kampagne stoppt für ihn, und Gemlead bringt dieselbe Person für diese Persona nicht zurück. Um jemanden aus allen Personas herauszuhalten, setze ihn auf die Ausschlussliste.
Pfadparameter
- lead_idstringErforderlichDie ID des Leads.
Rückgabe
Ein Objekt mit der id des Leads und dem Wert true in deleted.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
curl -X DELETE https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"id": "msgOtJ8dvT",
"object": "lead",
"deleted": true
}Das Lead-Herkunftsobjekt
Wie Gemlead einen Lead gefunden hat, über welchen Beitrag er auftauchte und in welchen Kampagnen er ist.
Attribute
- objectstringImmer
lead_origin. - lead_idstringDie ID des Leads.
- personaobject oder nullDie Persona, für die er gefunden wurde.
- methodstring oder nullWie er gefunden wurde.
followingkeywordscompetitor_followerscompetitor_comments - found_querystring oder nullDie Keyword-Suche, die ihn gefunden hat, bei
keywords. - source_usernamestring oder nullDie Quelle oder das Konkurrenzkonto, über das er gefunden wurde.
- found_postobject oder nullDer Beitrag, über den der Lead auftauchte, falls es einen gab.
- campaignsArray von objectsDie Kampagnen des Leads, jeweils mit
id,name, demstatusdes Leads darin, dermethodder Kampagne und demstep, auf dem der Lead steht.
{
"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"
}
]
}Herkunft eines Leads abrufen
Gibt zurück, wie Gemlead den Lead gefunden hat, über welchen Beitrag er auftauchte und in welchen Kampagnen er ist, jeweils mit seinem aktuellen Schritt.
Pfadparameter
- lead_idstringErforderlichDie ID des Leads.
Rückgabe
Ein Lead-Herkunftsobjekt.
Fehler
- Kein Lead mit dieser ID im Konto des Schlüssels.
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT/origin \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"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"
}
]
}