Справочник 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
    Почему лид получил такую оценку, в одном или двух предложениях.
  • hotboolean
    True, если оценка 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": {}
}

Список лидов

GET/v1/leadsПраво readMCPsearch_leads

Возвращает ваших лидов, по умолчанию сначала недавно оценённых. Комбинируйте фильтры, чтобы получить именно тех лидов, которые нужны.

Параметры запроса

  • 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.
GET/v1/leads
curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=10
Ответ200
{
  "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"
}

Получение лида

GET/v1/leads/:idПраво readMCPget_lead

Возвращает одного лида.

Параметры пути

  • idstringОбязательно
    ID лида.

Возвращает

Объект лида.

Ошибки

  • В аккаунте ключа нет лида с этим ID.
GET/v1/leads/:id
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Ответ200
{
  "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": {}
}

Изменение лида

PATCH/v1/leads/:idПраво writeMCPupdate_lead

Сохраняет в лиде ваши метаданные или закрывает его, когда работа с ним закончена. Закрытие лида останавливает шаги кампании, которые ещё его ждут, и Gemlead перестаёт ему писать.

Параметры пути

  • idstringОбязательно
    ID лида.

Параметры тела

  • metadataobject
    Пары ключей и значений, которые объединяются с метаданными лида. Ключи до 40 символов из букв, цифр, _ или -, значения в виде строк до 500 символов, не больше 20 ключей. Чтобы удалить ключ, задайте ему null или пустую строку, а чтобы очистить все, задайте metadata значение null.
  • statusstring
    Задайте closed, чтобы закрыть лида.
    closed

Возвращает

Обновлённый объект лида.

Ошибки

  • В аккаунте ключа нет лида с этим ID.
  • API не принимает значение параметра. Название параметра указано в param.
  • В теле есть поле, которое этот эндпоинт не принимает.
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"
    }
  }'
Ответ200
{
  "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"
  }
}

Переоценка лида

POST/v1/leads/:lead_id/rescoreПраво writeMCPlead_action

Просит Dana AI заново оценить лида по его персоне, например после того, как вы изменили описание персоны. Стоит до 2 кредита за лида: 1 за первичный отбор и ещё 1 за глубокую оценку, если лид прошёл отбор.

Параметры пути

  • lead_idstringОбязательно
    ID лида.

Возвращает

Объект лида.

Ошибки

  • В аккаунте ключа нет лида с этим ID.
  • X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
POST/v1/leads/:lead_id/rescore
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/rescore \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Ответ200
{
  "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": {}
}

Обновление лида

POST/v1/leads/:lead_id/refreshПраво writeMCPlead_action

Заново читает профиль лида в X, чтобы получить новое био, фото или число подписчиков.

Параметры пути

  • lead_idstringОбязательно
    ID лида.

Возвращает

Обновлённый объект лида.

Ошибки

  • В аккаунте ключа нет лида с этим ID.
  • Сессия аккаунта X истекла. Переподключите его в приложении и повторите попытку.
  • X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
POST/v1/leads/:lead_id/refresh
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/refresh \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Ответ200
{
  "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": {}
}

Подписка на лида

POST/v1/leads/:lead_id/followПраво writeMCPlead_action

Сразу подписывается на лида в X с вашего аккаунта X.

Параметры пути

  • lead_idstringОбязательно
    ID лида.

Возвращает

Объект лида.

Ошибки

  • В аккаунте ключа нет лида с этим ID.
  • У лида нет ID аккаунта X, на который можно подписаться.
  • Сессия аккаунта X истекла. Переподключите его в приложении и повторите попытку.
  • X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
POST/v1/leads/:lead_id/follow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/follow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Ответ200
{
  "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": {}
}

Отписка от лида

POST/v1/leads/:lead_id/unfollowПраво writeMCPlead_action

Сразу отписывается от лида в X с вашего аккаунта X.

Параметры пути

  • lead_idstringОбязательно
    ID лида.

Возвращает

Объект лида.

Ошибки

  • В аккаунте ключа нет лида с этим ID.
  • У лида нет ID аккаунта X, от которого можно отписаться.
  • Сессия аккаунта X истекла. Переподключите его в приложении и повторите попытку.
  • X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.
POST/v1/leads/:lead_id/unfollow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/unfollow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Ответ200
{
  "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": {}
}

Превращение лида в источник

POST/v1/leads/:lead_id/convert_to_sourceПраво writeMCPconvert_lead_to_source

Делает отличного лида источником его персоны, чтобы находить больше похожих людей. 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 не ответил. Ничего не изменилось, повторите через минуту.
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"
  }'
Ответ200
{
  "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
}

Удаление лида

DELETE/v1/leads/:lead_idПраво writeMCPdelete_lead

Удаляет лида. Он пропадает из ваших списков, все кампании для него останавливаются, и Gemlead больше не вернёт этого человека для этой персоны. Чтобы исключить человека из всех персон, добавьте его в список исключений.

Параметры пути

  • lead_idstringОбязательно
    ID лида.

Возвращает

Объект с id лида и deleted, равным true.

Ошибки

  • В аккаунте ключа нет лида с этим ID.
DELETE/v1/leads/:lead_id
curl -X DELETE https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Ответ200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "deleted": true
}

Объект происхождения лида

Как Gemlead нашёл лида, пост, по которому он был найден, и все кампании, в которых он участвует.

Атрибуты

  • objectstring
    Всегда lead_origin.
  • lead_idstring
    ID лида.
  • 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"
    }
  ]
}

Происхождение лида

GET/v1/leads/:lead_id/originПраво readMCPget_lead_origin

Возвращает, как Gemlead нашёл лида, пост, по которому он был найден, и все кампании, в которых он участвует, с текущим шагом.

Параметры пути

  • lead_idstringОбязательно
    ID лида.

Возвращает

Объект происхождения лида.

Ошибки

  • В аккаунте ключа нет лида с этим ID.
GET/v1/leads/:lead_id/origin
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT/origin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Ответ200
{
  "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"
    }
  ]
}