Справочник API
Лиды
Лидами называются люди, которых Gemlead находит в X для ваших персон. Dana AI ставит каждому оценку от 0 до 100, и лид считается горячим при оценке от 60. Получайте их списком с фильтрами, добавляйте свои метаданные, например ID в CRM, или действуйте с лидом так же, как в приложении.
Объект лида
Человек, которого Gemlead нашёл в X для одной из ваших персон, с оценкой от Dana AI и текущим этапом вашего аутрича.
Атрибуты
- idstringУникальный идентификатор лида.
- objectstringВсегда
lead. - profileobjectПрофиль лида в X.
- scoreinteger или nullНасколько лид подходит вашей персоне, от 0 до 100. Null, пока лид не оценён.
- score_reasonstring или nullПочему лид получил такую оценку, в одном или двух предложениях.
- hotbooleanTrue, если оценка 60 или выше.
- statusstringНа каком этапе вашей воронки находится лид.
pendingscoringscoredin_campaigncontactedin_conversationclosed - personaobject или nullПерсона, для которой найден лид.
- campaignobject или nullКампания, в которой находится лид, если есть.
- conversation_idstring или nullДиалог с лидом, когда он появится. Используйте его в запросе Получение диалога.
- locked_toobject или nullЕдинственный аккаунт X владельца, за которым закреплён этот человек. Лид достаётся только одному аккаунту X, поэтому остальные никогда с ним не связываются. Null, пока лид ни за кем не закреплён.
- found_atstringКогда Gemlead нашёл лида, ISO 8601.
- scored_atstring или nullКогда лид был оценён, ISO 8601.
- updated_atstringВремя последнего изменения лида, ISO 8601.
- metadataobjectВаши собственные пары ключей и значений, заданные запросом Изменение лида.
{
"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": {}
}Список лидов
Возвращает ваших лидов, по умолчанию сначала недавно оценённых. Комбинируйте фильтры, чтобы получить именно тех лидов, которые нужны.
Параметры запроса
- personastringТолько лиды персоны с этим ID.
- statusstringТолько лиды с этими статусами, через запятую, например
scored,in_campaign.pendingscoringscoredin_campaigncontactedin_conversationclosed - score_minintegerТолько лиды с оценкой не ниже этой, от 0 до 100.
- score_maxintegerТолько лиды с оценкой не выше этой, от 0 до 100.
- hotboolean
trueдля лидов с оценкой 60 или выше,falseдля остальных. - scored_afterstringТолько лиды, оценённые после этого времени, ISO 8601.
- scored_beforestringТолько лиды, оценённые до этого времени, ISO 8601.
- found_afterstringТолько лиды, найденные после этого времени, ISO 8601.
- found_beforestringТолько лиды, найденные до этого времени, ISO 8601.
- orderstringПорядок сортировки. По умолчанию
-scored_at, сначала недавно оценённые.-scored_at-score-found_at - limitintegerСколько объектов вернуть, от 1 до 100. По умолчанию 25.
- cursorstring
next_cursorпредыдущей страницы, чтобы получить следующую. См. раздел Пагинация.
Возвращает
Список объектов лида.
Ошибки
- API не принимает значение параметра. Название параметра указано в
param.
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"
}Получение лида
Возвращает одного лида.
Параметры пути
- idstringОбязательноID лида.
Возвращает
Ошибки
- В аккаунте ключа нет лида с этим ID.
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": {}
}Изменение лида
Сохраняет в лиде ваши метаданные или закрывает его, когда работа с ним закончена. Закрытие лида останавливает шаги кампании, которые ещё его ждут, и Gemlead перестаёт ему писать.
Параметры пути
- idstringОбязательноID лида.
Параметры тела
- metadataobjectПары ключей и значений, которые объединяются с метаданными лида. Ключи до 40 символов из букв, цифр,
_или-, значения в виде строк до 500 символов, не больше 20 ключей. Чтобы удалить ключ, задайте емуnullили пустую строку, а чтобы очистить все, задайтеmetadataзначениеnull. - statusstringЗадайте
closed, чтобы закрыть лида.closed
Возвращает
Обновлённый объект лида.
Ошибки
- В аккаунте ключа нет лида с этим ID.
- API не принимает значение параметра. Название параметра указано в
param. - В теле есть поле, которое этот эндпоинт не принимает.
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"
}
}Переоценка лида
Просит Dana AI заново оценить лида по его персоне, например после того, как вы изменили описание персоны. Стоит до 2 кредита за лида: 1 за первичный отбор и ещё 1 за глубокую оценку, если лид прошёл отбор.
Параметры пути
- lead_idstringОбязательноID лида.
Возвращает
Ошибки
- В аккаунте ключа нет лида с этим ID.
- X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
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": {}
}Обновление лида
Заново читает профиль лида в X, чтобы получить новое био, фото или число подписчиков.
Параметры пути
- lead_idstringОбязательноID лида.
Возвращает
Обновлённый объект лида.
Ошибки
- В аккаунте ключа нет лида с этим ID.
- Сессия аккаунта X истекла. Переподключите его в приложении и повторите попытку.
- X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
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": {}
}Подписка на лида
Сразу подписывается на лида в X с вашего аккаунта X.
Параметры пути
- lead_idstringОбязательноID лида.
Возвращает
Ошибки
- В аккаунте ключа нет лида с этим ID.
- У лида нет ID аккаунта X, на который можно подписаться.
- Сессия аккаунта X истекла. Переподключите его в приложении и повторите попытку.
- X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
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": {}
}Отписка от лида
Сразу отписывается от лида в X с вашего аккаунта X.
Параметры пути
- lead_idstringОбязательноID лида.
Возвращает
Ошибки
- В аккаунте ключа нет лида с этим ID.
- У лида нет ID аккаунта X, от которого можно отписаться.
- Сессия аккаунта X истекла. Переподключите его в приложении и повторите попытку.
- X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
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": {}
}Превращение лида в источник
Делает отличного лида источником его персоны, чтобы находить больше похожих людей. Gemlead читает, на кого он подписан, его подписчиков или тех, кто комментирует его посты.
Параметры пути
- lead_idstringОбязательноID лида.
Параметры тела
- methodstring
followingчитает, на кого подписан лид,competitor_followersего подписчиков,competitor_commentsтех, кто комментирует его посты. По умолчаниюfollowing.followingcompetitor_followerscompetitor_comments
Возвращает
Объект с lead_id, его persona_id, method и новым источником, а для competitor_comments с именем пользователя competitor_account.
Ошибки
- В аккаунте ключа нет лида с этим ID.
- Лид не относится ни к одной персоне.
- У персоны уже есть этот аккаунт как источник с этим методом.
- У персоны уже 100 аккаунтов конкурентов.
- API не принимает значение параметра. Название параметра указано в
param. - X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
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
}Удаление лида
Удаляет лида. Он пропадает из ваших списков, все кампании для него останавливаются, и Gemlead больше не вернёт этого человека для этой персоны. Чтобы исключить человека из всех персон, добавьте его в список исключений.
Параметры пути
- lead_idstringОбязательноID лида.
Возвращает
Объект с id лида и deleted, равным true.
Ошибки
- В аккаунте ключа нет лида с этим ID.
curl -X DELETE https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"id": "msgOtJ8dvT",
"object": "lead",
"deleted": true
}Объект происхождения лида
Как Gemlead нашёл лида, пост, по которому он был найден, и все кампании, в которых он участвует.
Атрибуты
- objectstringВсегда
lead_origin. - lead_idstringID лида.
- personaobject или nullПерсона, для которой он найден.
- methodstring или nullКак он был найден.
followingkeywordscompetitor_followerscompetitor_comments - found_querystring или nullПоиск по ключевым словам, который его нашёл, для
keywords. - source_usernamestring или nullИсточник или аккаунт конкурента, через который он найден.
- found_postobject или nullПост, по которому найден лид, если лид найден через пост.
- campaignsмассив objectsКампании, в которых участвует лид, у каждой
id,name,statusлида в ней,methodкампании иstep, на котором находится лид.
{
"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"
}
]
}Происхождение лида
Возвращает, как Gemlead нашёл лида, пост, по которому он был найден, и все кампании, в которых он участвует, с текущим шагом.
Параметры пути
- lead_idstringОбязательноID лида.
Возвращает
Ошибки
- В аккаунте ключа нет лида с этим ID.
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"
}
]
}