Gemlead
Docs
Entrar
Obter sua chave de API

Referência da API

Leads

Leads são as pessoas que o Gemlead encontra no X para as suas personas. A Dana AI dá a cada um deles um score de 0 a 100, e um lead é quente a partir de 60. Liste os leads com filtros, anexe seus próprios metadados, como um ID do CRM, ou execute ações em um lead como faria no app.

Endpoints

O objeto lead

Uma pessoa que o Gemlead encontrou no X para uma das suas personas, com o score que a Dana AI deu a ela e o ponto em que ela está na sua prospecção.

Atributos

  • idstring
    Identificador único do lead.
  • objectstring
    Sempre lead.
  • profileobject
    O perfil do lead no X.
  • scoreinteger ou null
    O quanto o lead combina com a sua persona, de 0 a 100. Null até ser pontuado.
  • score_reasonstring ou null
    Por que o lead recebeu esse score, em uma ou duas frases.
  • hotboolean
    Indica se o score é 60 ou mais.
  • statusstring
    Onde o lead está no seu pipeline.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • personaobject ou null
    A persona para a qual o lead foi encontrado.
  • campaignobject ou null
    A campanha em que o lead está, se houver.
  • conversation_idstring ou null
    A conversa com o lead, assim que existir uma. Use com Obter uma conversa.
  • locked_toobject ou null
    A única conta do X do dono reservada para essa pessoa. Um lead vai para uma só conta do X, então as outras nunca entram em contato com ele. Null enquanto o lead não está reservado.
  • found_atstring
    Quando o Gemlead encontrou o lead, em ISO 8601.
  • scored_atstring ou null
    Quando o lead foi pontuado, em ISO 8601.
  • updated_atstring
    Quando o lead mudou pela última vez, em ISO 8601.
  • metadataobject
    Seus próprios pares de chave e valor, definidos com Atualizar um lead.
O objeto 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": {}
}

Listar leads

GET/v1/leadsScope readMCPsearch_leads

Retorna seus leads, por padrão dos pontuados mais recentemente para os mais antigos. Combine filtros para obter exatamente os leads que você quer.

Parâmetros de consulta

  • personastring
    Só os leads da persona com este ID.
  • statusstring
    Só os leads nestes status, separados por vírgula, como scored,in_campaign.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • score_mininteger
    Só os leads com pelo menos este score, de 0 a 100.
  • score_maxinteger
    Só os leads com no máximo este score, de 0 a 100.
  • hotboolean
    true para os leads com score de 60 ou mais, false para os outros.
  • scored_afterstring
    Só os leads pontuados depois deste horário, em ISO 8601.
  • scored_beforestring
    Só os leads pontuados antes deste horário, em ISO 8601.
  • found_afterstring
    Só os leads encontrados depois deste horário, em ISO 8601.
  • found_beforestring
    Só os leads encontrados antes deste horário, em ISO 8601.
  • orderstring
    A ordenação. O padrão é -scored_at, com os pontuados mais recentemente primeiro.
    -scored_at-score-found_at
  • limitinteger
    Quantos objetos retornar, de 1 a 100. O padrão é 25.
  • cursorstring
    O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos lead.

Erros

  • 400parameter_invalid
    Um parâmetro tem um valor que a API não aceita. param diz qual.
GET/v1/leads
curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=10
Resposta200
{
  "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"
}

Obter um lead

GET/v1/leads/:idScope readMCPget_lead

Retorna um lead.

Parâmetros de caminho

  • idstringObrigatório
    O ID do lead.

Retorno

Um objeto lead.

Erros

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

Atualizar um lead

PATCH/v1/leads/:idScope writeMCPupdate_lead

Define seus próprios metadados num lead, ou encerra o lead quando você terminar com ele. Encerrar um lead interrompe as etapas de campanha que ainda esperavam por ele, e o Gemlead deixa de escrever para ele.

Parâmetros de caminho

  • idstringObrigatório
    O ID do lead.

Parâmetros do corpo

  • metadataobject
    Pares de chave e valor mesclados nos metadados do lead. Chaves de até 40 letras, dígitos, _ ou -, valores em string de até 500 caracteres, no máximo 20 chaves. Defina uma chave como null ou string vazia para removê-la, ou metadata como null para apagar tudo.
  • statusstring
    Defina como closed para encerrar o lead.
    closed

Retorno

O objeto lead atualizado.

Erros

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

Repontuar um lead

POST/v1/leads/:lead_id/rescoreScope writeMCPlead_action

Pede à Dana AI para pontuar o lead de novo com base na persona dele, depois de você mudar a descrição da persona, por exemplo. Usa até 2 créditos por lead: 1 pela primeira triagem, mais 1 pelo score aprofundado quando o lead passa.

Parâmetros de caminho

  • lead_idstringObrigatório
    O ID do lead.

Retorno

O objeto lead.

Erros

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

Recarregar um lead

POST/v1/leads/:lead_id/refreshScope writeMCPlead_action

Lê de novo o perfil do lead no X, para obter uma nova bio, foto ou número de seguidores.

Parâmetros de caminho

  • lead_idstringObrigatório
    O ID do lead.

Retorno

O objeto lead atualizado.

Erros

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

Seguir um lead

POST/v1/leads/:lead_id/followScope writeMCPlead_action

Segue o lead no X pela sua conta do X, na hora.

Parâmetros de caminho

  • lead_idstringObrigatório
    O ID do lead.

Retorno

O objeto lead.

Erros

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

Deixar de seguir um lead

POST/v1/leads/:lead_id/unfollowScope writeMCPlead_action

Deixa de seguir o lead no X pela sua conta do X, na hora.

Parâmetros de caminho

  • lead_idstringObrigatório
    O ID do lead.

Retorno

O objeto lead.

Erros

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

Transformar um lead em fonte

POST/v1/leads/:lead_id/convert_to_sourceScope writeMCPconvert_lead_to_source

Transforma um ótimo lead em fonte da persona dele, para encontrar mais pessoas parecidas. O Gemlead lê quem ele segue, os seguidores dele ou quem comenta nos posts dele.

Parâmetros de caminho

  • lead_idstringObrigatório
    O ID do lead.

Parâmetros do corpo

  • methodstring
    following lê quem o lead segue, competitor_followers os seguidores dele, competitor_comments quem comenta nos posts dele. O padrão é following.
    followingcompetitor_followerscompetitor_comments

Retorno

Um objeto com o lead_id, o persona_id dele, o method e a nova fonte, ou o username competitor_account para competitor_comments.

Erros

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

Excluir um lead

DELETE/v1/leads/:lead_idScope writeMCPdelete_lead

Exclui um lead. Ele sai das suas listas, todas as campanhas param para ele, e o Gemlead não traz mais a mesma pessoa para esta persona. Para deixar alguém fora de todas as personas, adicione a pessoa à lista de exclusão.

Parâmetros de caminho

  • lead_idstringObrigatório
    O ID do lead.

Retorno

Um objeto com o id do lead e deleted igual a true.

Erros

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

O objeto lead origin

Como o Gemlead encontrou um lead, o post que o revelou e cada campanha em que ele está.

Atributos

  • objectstring
    Sempre lead_origin.
  • lead_idstring
    O ID do lead.
  • personaobject ou null
    A persona para a qual ele foi encontrado.
  • methodstring ou null
    Como ele foi encontrado.
    followingkeywordscompetitor_followerscompetitor_comments
  • found_querystring ou null
    A busca por palavra-chave que o encontrou, para keywords.
  • source_usernamestring ou null
    A fonte ou a conta concorrente pela qual ele foi encontrado.
  • found_postobject ou null
    O post que revelou o lead, quando foi um post.
  • campaignsarray de objects
    As campanhas em que o lead está, cada uma com id, name, o status do lead nela, o method da campanha e o step em que o lead está.
O objeto lead origin
{
  "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"
    }
  ]
}

Obter a origem de um lead

GET/v1/leads/:lead_id/originScope readMCPget_lead_origin

Retorna como o Gemlead encontrou o lead, o post que o revelou e cada campanha em que ele está, com a etapa em que ele se encontra.

Parâmetros de caminho

  • lead_idstringObrigatório
    O ID do lead.

Retorno

Um objeto lead origin.

Erros

GET/v1/leads/:lead_id/origin
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT/origin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "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"
    }
  ]
}
Receba as novidades do Gemlead
direto no seu e-mail.
Assinar
Ao assinar, você aceita a nossa Política de Privacidade e concorda em receber novidades da nossa empresa.
Gemlead
Produto
Começar
Entrar
Para quem
Agentes de IA
Recursos
Preços
Afiliados
FAQ
Recursos
Compradores, 24/7Os quentes primeiro+60% de respostasDMs sob medidaTudo numa caixa sóSeu closer de IAEscale sem limitesAPI, MCP, webhooksPergunte ao Gemlead
Conteúdo
InícioAPIBlog
Jurídico
Termos
Privacidade
© 2026 Gemlead, Inc. Todos os direitos reservados.
Português