Gemlead
Docs
Iniciar sesión
Obtén tu clave API

Referencia de la API

Personas

Un buyer persona es un tipo de comprador al que quieres llegar, como tipsters o dueños de agencia. Gemlead encuentra leads para cada buyer persona activo y los puntúa según su descripción. Sus fuentes deciden dónde busca Gemlead.

Un propietario con varias cuentas de X puede compartir un buyer persona entre ellas. Trabajan con las mismas fuentes, los mismos ajustes y los mismos leads, cada una con sus propias campañas, y un lead va a una sola cuenta de X. Compartir el buyer persona define qué cuentas de X lo comparten.

Endpoints

El objeto persona

Un tipo de comprador al que quieres llegar. Gemlead busca leads que encajen con cada buyer persona activo y los puntúa según él.

Atributos

  • idstring
    Identificador único del buyer persona.
  • objectstring
    Siempre persona.
  • namestring
    El nombre corto del buyer persona, como Tipsters.
  • descriptionstring
    Quién es este comprador, en tus palabras. El scoring parte de este texto.
  • marketstring
    Si vendes a empresas o a consumidores.
    b2bb2c
  • statusstring
    Si Gemlead está buscando leads para este buyer persona.
    activepaused
  • websitestring o null
    El sitio web de lo que vendes a este buyer persona.
  • statsobject
    Totales desde que se creó el buyer persona, y los de hoy en la zona horaria de tu perfil.
  • sharingobject
    Las cuentas de X del propietario que comparten el buyer persona. Consulta compartir un buyer persona.
  • created_atstring
    Cuándo se creó el buyer persona, en ISO 8601.
  • updated_atstring
    Cuándo cambió el buyer persona por última vez, en ISO 8601.
El objeto persona
{
  "id": "lvWBPnytpS",
  "object": "persona",
  "name": "Tipsters",
  "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
  "market": "b2c",
  "status": "active",
  "website": "https://example.com",
  "stats": {
    "leads_found": 18420,
    "leads_scored": 17960,
    "hot_leads": 2134,
    "avg_score": 41,
    "today": {
      "leads_found": 312,
      "hot_leads": 38,
      "dms_sent": 25,
      "replies": 4
    }
  },
  "sharing": {
    "home_account": {
      "id": "a9PzK2vRtM",
      "username": "acme"
    },
    "shared_with": [
      {
        "id": "Hq4TnW8cLm",
        "username": "acme_sales"
      }
    ]
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Listar buyer personas

GET/v1/personasScope readMCPlist_personas

Devuelve tus buyer personas en el orden de tu página Personas.

Parámetros de consulta

  • limitinteger
    Cuántos objetos devolver, de 1 a 100. 25 por defecto.
  • cursorstring
    El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos persona.

GET/v1/personas
curl https://gemlead.ai/api/v1/personas \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "object": "list",
  "data": [
    {
      "id": "lvWBPnytpS",
      "object": "persona",
      "name": "Tipsters",
      "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
      "market": "b2c",
      "status": "active",
      "website": "https://example.com",
      "stats": {
        "leads_found": 18420,
        "leads_scored": 17960,
        "hot_leads": 2134,
        "avg_score": 41,
        "today": {
          "leads_found": 312,
          "hot_leads": 38,
          "dms_sent": 25,
          "replies": 4
        }
      },
      "sharing": {
        "home_account": {
          "id": "a9PzK2vRtM",
          "username": "acme"
        },
        "shared_with": [
          {
            "id": "Hq4TnW8cLm",
            "username": "acme_sales"
          }
        ]
      },
      "created_at": "2026-09-14T09:21:05.300Z",
      "updated_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Obtener un buyer persona

GET/v1/personas/:idScope readMCPget_persona

Devuelve un buyer persona con sus estadísticas.

Parámetros de ruta

  • idstringObligatorio
    El ID del buyer persona.

Devuelve

Un objeto persona.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
GET/v1/personas/:id
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "id": "lvWBPnytpS",
  "object": "persona",
  "name": "Tipsters",
  "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
  "market": "b2c",
  "status": "active",
  "website": "https://example.com",
  "stats": {
    "leads_found": 18420,
    "leads_scored": 17960,
    "hot_leads": 2134,
    "avg_score": 41,
    "today": {
      "leads_found": 312,
      "hot_leads": 38,
      "dms_sent": 25,
      "replies": 4
    }
  },
  "sharing": {
    "home_account": {
      "id": "a9PzK2vRtM",
      "username": "acme"
    },
    "shared_with": [
      {
        "id": "Hq4TnW8cLm",
        "username": "acme_sales"
      }
    ]
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Crear un buyer persona

POST/v1/personasScope writeMCPcreate_persona

Crea un buyer persona y empieza a buscar sus leads al instante. El scoring usa hasta 2 créditos por lead: 1 por la primera pasada y 1 más por la puntuación a fondo si la supera, con un máximo de daily_scoring_limit leads al día. Añade fuentes ahora o más tarde con Añadir una fuente.

Parámetros del cuerpo

  • namestringObligatorio
    El nombre del buyer persona, de una a tres palabras como Ghostwriters, hasta 100 caracteres.
  • websitestring
    El sitio web de tu producto, hasta 500 caracteres. La IA que puntúa los leads lo lee.
  • descriptionstringObligatorio
    Quién es este comprador, con palabras sencillas. La IA puntúa cada lead de 0 a 100 según este texto, así que es lo más importante. Puede incluir tus propias reglas de scoring. Hasta 12 000 caracteres.
  • marketstring
    b2b cuando compran empresas, b2c cuando la gente compra para sí misma. Por defecto b2b.
    b2bb2c
  • keywordsarray de strings
    Palabras de un perfil o de sus publicaciones que indican que encaja. Hasta 100, de hasta 100 caracteres cada una.
  • competitorsarray de strings
    Productos como el tuyo, quien usa alguno encaja. Hasta 100.
  • avoidarray de strings
    A quién puntuar bajo, como agencies o students. Hasta 100.
  • min_followersinteger
    Los perfiles con menos seguidores no se puntúan, de 0 a 10 000 000. Por defecto 100.
  • include_closed_inboxesboolean
    Puntuar también a la gente con los DM cerrados, una campaña los alcanza con un comentario. Por defecto true.
  • auto_expandboolean
    Dejar que Gemlead añada fuentes por su cuenta a partir de los mejores leads cuando las demás se agotan. Por defecto false.
  • auto_expand_directionstring
    Hacia dónde va después la expansión automática, con palabras sencillas como more US founders. Hasta 500 caracteres.
  • daily_scoring_limitinteger
    El máximo de leads puntuados al día para este buyer persona, con un coste de hasta 2 créditos por lead: 1 por la primera pasada y 1 más por la puntuación a fondo si la supera. De 100 a 20 000. Por defecto, el ritmo de tu plan, 3 300 al día en Starter y 10 000 en Business.
  • sourcesarray de objects
    Hasta 20 fuentes iniciales. Las cuentas de inversores, aceleradoras y medios se rechazan, no traen compradores.

Devuelve

El nuevo objeto persona.

Errores

POST/v1/personas
curl -X POST https://gemlead.ai/api/v1/personas \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tipsters",
    "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
    "market": "b2c",
    "keywords": ["tipster", "betting tips"],
    "sources": [
      {
        "username": "pickswithmike"
      }
    ]
  }'
Respuesta200
{
  "id": "lvWBPnytpS",
  "object": "persona",
  "name": "Tipsters",
  "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
  "market": "b2c",
  "status": "active",
  "website": "https://example.com",
  "stats": {
    "leads_found": 18420,
    "leads_scored": 17960,
    "hot_leads": 2134,
    "avg_score": 41,
    "today": {
      "leads_found": 312,
      "hot_leads": 38,
      "dms_sent": 25,
      "replies": 4
    }
  },
  "sharing": {
    "home_account": {
      "id": "a9PzK2vRtM",
      "username": "acme"
    },
    "shared_with": [
      {
        "id": "Hq4TnW8cLm",
        "username": "acme_sales"
      }
    ]
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Activar un buyer persona

POST/v1/personas/:persona_id/activateScope writeMCPupdate_persona

Vuelve a poner en marcha un buyer persona en pausa. Sus fuentes vuelven a leerse y sus leads a puntuarse.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

El objeto persona.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
POST/v1/personas/:persona_id/activate
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/activate \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "id": "lvWBPnytpS",
  "object": "persona",
  "name": "Tipsters",
  "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
  "market": "b2c",
  "status": "active",
  "website": "https://example.com",
  "stats": {
    "leads_found": 18420,
    "leads_scored": 17960,
    "hot_leads": 2134,
    "avg_score": 41,
    "today": {
      "leads_found": 312,
      "hot_leads": 38,
      "dms_sent": 25,
      "replies": 4
    }
  },
  "sharing": {
    "home_account": {
      "id": "a9PzK2vRtM",
      "username": "acme"
    },
    "shared_with": [
      {
        "id": "Hq4TnW8cLm",
        "username": "acme_sales"
      }
    ]
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Pausar un buyer persona

POST/v1/personas/:persona_id/pauseScope writeMCPupdate_persona

Pausa un buyer persona. Gemlead deja de leer sus fuentes y de puntuar sus leads, que se conservan.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

El objeto persona, con su status en paused.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
POST/v1/personas/:persona_id/pause
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/pause \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "id": "lvWBPnytpS",
  "object": "persona",
  "name": "Tipsters",
  "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
  "market": "b2c",
  "status": "paused",
  "website": "https://example.com",
  "stats": {
    "leads_found": 18420,
    "leads_scored": 17960,
    "hot_leads": 2134,
    "avg_score": 41,
    "today": {
      "leads_found": 312,
      "hot_leads": 38,
      "dms_sent": 25,
      "replies": 4
    }
  },
  "sharing": {
    "home_account": {
      "id": "a9PzK2vRtM",
      "username": "acme"
    },
    "shared_with": [
      {
        "id": "Hq4TnW8cLm",
        "username": "acme_sales"
      }
    ]
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Eliminar un buyer persona

DELETE/v1/personas/:persona_idScope writeMCPdelete_persona

Elimina un buyer persona con sus fuentes y los leads que ninguna campaña trabajó. Sus campañas se archivan. No se puede deshacer.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

Un objeto con el id del buyer persona, deleted en true y los totales de archived_campaigns y deleted_sources. Sus leads se eliminan en segundo plano, así que deleted_leads es null y pueden seguir apareciendo en Listar leads unos minutos.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
DELETE/v1/personas/:persona_id
curl -X DELETE https://gemlead.ai/api/v1/personas/lvWBPnytpS \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "id": "lvWBPnytpS",
  "object": "persona",
  "deleted": true,
  "archived_campaigns": 1,
  "deleted_sources": 6,
  "deleted_leads": null
}

Reordenar buyer personas

POST/v1/personas/reorderScope writeMCPreorder_personas

Define el orden de tus buyer personas, tal como los lista la app. Envía cada buyer persona una sola vez.

Parámetros del cuerpo

  • persona_idsarray de stringsObligatorio
    Todos los ID de buyer persona de la cuenta, en el nuevo orden.

Devuelve

Una lista de objetos persona en el nuevo orden.

Errores

POST/v1/personas/reorder
curl -X POST https://gemlead.ai/api/v1/personas/reorder \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_ids": ["lvWBPnytpS", "pQ8nX2rTjk"]
  }'
Respuesta200
{
  "object": "list",
  "data": [
    {
      "id": "lvWBPnytpS",
      "object": "persona",
      "name": "Tipsters",
      "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
      "market": "b2c",
      "status": "active",
      "website": "https://example.com",
      "stats": {
        "leads_found": 18420,
        "leads_scored": 17960,
        "hot_leads": 2134,
        "avg_score": 41,
        "today": {
          "leads_found": 312,
          "hot_leads": 38,
          "dms_sent": 25,
          "replies": 4
        }
      },
      "sharing": {
        "home_account": {
          "id": "a9PzK2vRtM",
          "username": "acme"
        },
        "shared_with": [
          {
            "id": "Hq4TnW8cLm",
            "username": "acme_sales"
          }
        ]
      },
      "created_at": "2026-09-14T09:21:05.300Z",
      "updated_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

El objeto persona settings

Todo lo que decide qué leads encuentra un buyer persona y cómo los puntúa la IA, tal como se edita en la página del buyer persona en la app.

Atributos

  • objectstring
    Siempre persona_settings.
  • persona_idstring
    El ID del buyer persona.
  • namestring
    El nombre del buyer persona, de una a tres palabras como Ghostwriters.
  • websitestring o null
    El sitio web de tu producto. La IA que puntúa los leads lo lee.
  • descriptionstring o null
    Quién es este comprador, con palabras sencillas. La IA puntúa cada lead de 0 a 100 según este texto, así que es lo más importante. Puede incluir tus propias reglas de scoring.
  • marketstring
    b2b cuando compran empresas, b2c cuando la gente compra para sí misma.
    b2bb2c
  • keywordsarray de strings
    Palabras de un perfil o de sus publicaciones que indican que encaja.
  • competitorsarray de strings
    Productos como el tuyo. Quien usa uno encaja.
  • avoidarray de strings
    A quién puntuar bajo, como agencies o students.
  • min_followersinteger
    Los perfiles con menos seguidores no se puntúan.
  • include_closed_inboxesboolean
    Si también se puntúa a la gente con los DM cerrados. Una campaña los alcanza con un comentario.
  • auto_expandboolean
    Si Gemlead añade fuentes por su cuenta a partir de los mejores leads cuando las demás se agotan.
  • auto_expand_directionstring o null
    Hacia dónde va después la expansión automática, con palabras sencillas, como more US founders.
  • daily_scoring_limitinteger
    El máximo de leads puntuados al día para este buyer persona, con un coste de hasta 2 créditos por lead: 1 por la primera pasada y 1 más por la puntuación a fondo si la supera.
  • statusstring
    Si Gemlead está buscando y puntuando leads para él.
    activepaused
  • search_queriesarray de strings
    Sus búsquedas por palabras clave.
  • competitor_accountsarray de strings
    Sus cuentas de competidores, usuarios de X sin la @.
  • updated_atstring
    Cuándo cambió el buyer persona por última vez, en ISO 8601.
El objeto persona settings
{
  "object": "persona_settings",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters",
  "website": "https://example.com",
  "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
  "market": "b2c",
  "status": "active",
  "keywords": ["tipster", "betting tips", "trading signals"],
  "competitors": ["Patreon", "Whop"],
  "avoid": ["betting brands", "news accounts"],
  "min_followers": 500,
  "include_closed_inboxes": true,
  "auto_expand": false,
  "auto_expand_direction": null,
  "daily_scoring_limit": 3300,
  "search_queries": ["paid discord picks", "vip tips telegram"],
  "competitor_accounts": ["whop"],
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Obtener los ajustes de un buyer persona

GET/v1/personas/:persona_id/settingsScope readMCPget_persona_settings

Devuelve todos los ajustes de un buyer persona, con sus búsquedas por palabras clave y sus cuentas de competidores.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

Un objeto persona settings.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
GET/v1/personas/:persona_id/settings
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "object": "persona_settings",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters",
  "website": "https://example.com",
  "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
  "market": "b2c",
  "status": "active",
  "keywords": ["tipster", "betting tips", "trading signals"],
  "competitors": ["Patreon", "Whop"],
  "avoid": ["betting brands", "news accounts"],
  "min_followers": 500,
  "include_closed_inboxes": true,
  "auto_expand": false,
  "auto_expand_direction": null,
  "daily_scoring_limit": 3300,
  "search_queries": ["paid discord picks", "vip tips telegram"],
  "competitor_accounts": ["whop"],
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Actualizar los ajustes de un buyer persona

PATCH/v1/personas/:persona_id/settingsScope writeMCPupdate_persona

Cambia los ajustes que envías y conserva los demás. Cada lista que envías reemplaza la lista entera, así que envía keywords con la palabra nueva añadida para conservar las demás.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • namestring
    El nombre del buyer persona, de una a tres palabras como Ghostwriters, hasta 100 caracteres.
  • websitestring
    El sitio web de tu producto, hasta 500 caracteres. La IA que puntúa los leads lo lee.
  • descriptionstring
    Quién es este comprador, con palabras sencillas. La IA puntúa cada lead de 0 a 100 según este texto, así que es lo más importante. Puede incluir tus propias reglas de scoring. Hasta 12 000 caracteres.
  • marketstring
    b2b cuando compran empresas, b2c cuando la gente compra para sí misma. Por defecto b2b.
    b2bb2c
  • keywordsarray de strings
    Palabras de un perfil o de sus publicaciones que indican que encaja. Hasta 100, de hasta 100 caracteres cada una.
  • competitorsarray de strings
    Productos como el tuyo, quien usa alguno encaja. Hasta 100.
  • avoidarray de strings
    A quién puntuar bajo, como agencies o students. Hasta 100.
  • min_followersinteger
    Los perfiles con menos seguidores no se puntúan, de 0 a 10 000 000. Por defecto 100.
  • include_closed_inboxesboolean
    Puntuar también a la gente con los DM cerrados, una campaña los alcanza con un comentario. Por defecto true.
  • auto_expandboolean
    Dejar que Gemlead añada fuentes por su cuenta a partir de los mejores leads cuando las demás se agotan. Por defecto false.
  • auto_expand_directionstring
    Hacia dónde va después la expansión automática, con palabras sencillas como more US founders. Hasta 500 caracteres.
  • daily_scoring_limitinteger
    El máximo de leads puntuados al día para este buyer persona, con un coste de hasta 2 créditos por lead: 1 por la primera pasada y 1 más por la puntuación a fondo si la supera. De 100 a 20 000 por cada cuenta de X que comparte el buyer persona.

Devuelve

El objeto persona settings actualizado.

Errores

PATCH/v1/personas/:persona_id/settings
curl -X PATCH \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "min_followers": 500,
    "avoid": ["betting brands", "news accounts"]
  }'
Respuesta200
{
  "object": "persona_settings",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters",
  "website": "https://example.com",
  "description": "Sports and trading tipsters who sell picks or signals to a paying community.",
  "market": "b2c",
  "status": "active",
  "keywords": ["tipster", "betting tips", "trading signals"],
  "competitors": ["Patreon", "Whop"],
  "avoid": ["betting brands", "news accounts"],
  "min_followers": 500,
  "include_closed_inboxes": true,
  "auto_expand": false,
  "auto_expand_direction": null,
  "daily_scoring_limit": 3300,
  "search_queries": ["paid discord picks", "vip tips telegram"],
  "competitor_accounts": ["whop"],
  "updated_at": "2026-11-06T07:45:12.904Z"
}

El objeto persona sharing

Las cuentas de X de un mismo propietario que trabajan con el mismo buyer persona. Comparten sus fuentes, sus ajustes, sus leads y su lista de exclusión, y cada una lleva sus propias campañas con él. Un lead va a una sola cuenta de X, indicada en su locked_to.

Atributos

  • objectstring
    Siempre persona_sharing.
  • persona_idstring
    El ID del buyer persona.
  • home_accountobject o null
    La cuenta de X en la que se creó el buyer persona. Sus fuentes y sus leads están en ella.
  • shared_witharray de objects
    Las otras cuentas de X que comparten el buyer persona. Vacío cuando no se comparte.
  • available_accountsarray de objects
    Las otras cuentas de X del propietario con las que se puede compartir el buyer persona. Siempre vacío para un miembro del equipo, que no puede cambiar el uso compartido.
  • daily_scoring_limitinteger
    El máximo de leads puntuados al día para el buyer persona, para todo el grupo. Puede llegar a 20 000 por cada cuenta de X que comparte el buyer persona.
El objeto persona sharing
{
  "object": "persona_sharing",
  "persona_id": "lvWBPnytpS",
  "home_account": {
    "id": "a9PzK2vRtM",
    "username": "acme"
  },
  "shared_with": [
    {
      "id": "Hq4TnW8cLm",
      "username": "acme_sales"
    }
  ],
  "available_accounts": [
    {
      "id": "Rb7YsK3dQp",
      "username": "acme_founder"
    }
  ],
  "daily_scoring_limit": 3300
}

Obtener el uso compartido de un buyer persona

GET/v1/personas/:persona_id/sharingScope readMCPget_persona_sharing

Devuelve qué cuentas de X del propietario comparten un buyer persona, y las otras con las que se puede compartir.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

Un objeto persona sharing.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
GET/v1/personas/:persona_id/sharing
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sharing \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "object": "persona_sharing",
  "persona_id": "lvWBPnytpS",
  "home_account": {
    "id": "a9PzK2vRtM",
    "username": "acme"
  },
  "shared_with": [
    {
      "id": "Hq4TnW8cLm",
      "username": "acme_sales"
    }
  ],
  "available_accounts": [
    {
      "id": "Rb7YsK3dQp",
      "username": "acme_founder"
    }
  ],
  "daily_scoring_limit": 3300
}

Actualizar el uso compartido de un buyer persona

PUT/v1/personas/:persona_id/sharingScope writeMCPupdate_persona_sharing

Define qué otras cuentas de X del propietario comparten un buyer persona, desde cualquier cuenta de X del grupo, como hace Compartida con en la app. Envía la lista completa, o una vacía para dejar de compartirlo. El daily_scoring_limit sigue el tamaño del grupo, al mismo ritmo para cada cuenta de X. Solo las claves del propietario pueden hacerlo.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • account_idsarray de stringsObligatorio
    Todas las demás cuentas de X del propietario que comparten el buyer persona, hasta 20. Su cuenta de origen siempre lo conserva.

Devuelve

El objeto persona sharing actualizado.

Errores

  • 400parameter_missing
    Falta un parámetro obligatorio. param lo indica.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
  • 400parameter_unknown
    El cuerpo tiene un campo que este endpoint no acepta.
  • 403forbidden
    La clave es de un miembro del equipo. Solo el propietario puede compartir un buyer persona.
  • 404resource_missing
    No hay ningún buyer persona con este ID, o la cuenta de X no es del propietario. param lo indica.
  • 400shared_account_has_campaigns
    Una cuenta de X que quitas aún tiene campañas con el buyer persona. Elimínalas primero.
PUT/v1/personas/:persona_id/sharing
curl -X PUT \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sharing \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ids": ["Hq4TnW8cLm", "Rb7YsK3dQp"]
  }'
Respuesta200
{
  "object": "persona_sharing",
  "persona_id": "lvWBPnytpS",
  "home_account": {
    "id": "a9PzK2vRtM",
    "username": "acme"
  },
  "shared_with": [
    {
      "id": "Hq4TnW8cLm",
      "username": "acme_sales"
    },
    {
      "id": "Rb7YsK3dQp",
      "username": "acme_founder"
    }
  ],
  "available_accounts": [],
  "daily_scoring_limit": 5000
}

El objeto persona suggestion

Un buyer persona que la IA escribió para ti a partir de un nombre y de tu producto, listo para crearlo tal cual o editarlo antes.

Atributos

  • objectstring
    Siempre persona_suggestion.
  • statusstring
    pending mientras la IA escribe, luego ready o error. none antes de la primera solicitud.
    pendingreadyerrornone
  • persona_namestring o null
    El nombre que se pidió.
  • suggestionobject o null
    Una vez en ready, la description, las keywords, los competitors y el avoid del buyer persona, los campos de Crear un buyer persona.
  • generated_atstring o null
    Cuándo se escribió, en ISO 8601.
  • errorstring o null
    Qué falló, cuando status es error.
El objeto persona suggestion
{
  "object": "persona_suggestion",
  "status": "ready",
  "persona_name": "Tipsters",
  "suggestion": {
    "description": "Sports and trading tipsters who sell picks or signals to a paying community on Discord or Telegram.",
    "keywords": ["tipster", "vip picks", "trading signals"],
    "competitors": ["Patreon", "Whop"],
    "avoid": ["betting brands", "sports media"]
  },
  "generated_at": "2026-11-06T07:45:12.904Z",
  "error": null
}

Sugerir un buyer persona

POST/v1/persona_suggestionsScope writeMCPsuggest_persona

Pide a la IA que escriba un buyer persona a partir de un nombre y de lo que vendes, o que reescriba una descripción. Tarda unos segundos, así que la respuesta es pending. Lee el resultado con Obtener la sugerencia de buyer persona.

Parámetros del cuerpo

  • persona_namestringObligatorio
    El buyer persona que se va a escribir, de una a tres palabras como Ghostwriters.
  • websitestring
    El sitio web de tu producto. Por defecto, el de tu perfil de X.
  • briefstring
    Qué vendes y a quién, con tus palabras, hasta 1 000 caracteres.
  • current_descriptionstring
    Una descripción que reescribir, con instruction.
  • instructionstring
    Cómo cambiar current_description, como shorter u only US agencies. Hasta 2 000 caracteres.

Devuelve

Un objeto persona suggestion, con su status en pending.

Errores

POST/v1/persona_suggestions
curl -X POST https://gemlead.ai/api/v1/persona_suggestions \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_name": "Tipsters",
    "brief": "A checkout for paid Discord and Telegram groups."
  }'
Respuesta202
{
  "object": "persona_suggestion",
  "status": "pending",
  "persona_name": "Tipsters",
  "suggestion": null,
  "generated_at": null,
  "error": null
}

Obtener la sugerencia de buyer persona

GET/v1/persona_suggestions/latestScope readMCPget_persona_suggestion

Devuelve la última sugerencia de buyer persona de la cuenta. Vuelve a pedirla cada pocos segundos mientras esté en pending.

Devuelve

Un objeto persona suggestion.

GET/v1/persona_suggestions/latest
curl https://gemlead.ai/api/v1/persona_suggestions/latest \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "object": "persona_suggestion",
  "status": "ready",
  "persona_name": "Tipsters",
  "suggestion": {
    "description": "Sports and trading tipsters who sell picks or signals to a paying community on Discord or Telegram.",
    "keywords": ["tipster", "vip picks", "trading signals"],
    "competitors": ["Patreon", "Whop"],
    "avoid": ["betting brands", "sports media"]
  },
  "generated_at": "2026-11-06T07:45:12.904Z",
  "error": null
}
Recibe las novedades de Gemlead
directamente en tu bandeja de entrada.
Suscribirme
Al suscribirte aceptas nuestra Política de privacidad y das tu consentimiento para recibir novedades de nuestra empresa.
Gemlead
Producto
Empezar
Iniciar sesión
Para quién
Agentes de IA
Funciones
Precios
Afiliados
FAQ
Funciones
Compradores 24/7Primero los calientes+60% de respuestasDM a medidaUna bandeja para todoTu closer con IAEscala sin límitesAPI, MCP, webhooksPregunta a Gemlead
Recursos
InicioAPIBlog
Legal
Términos
Privacidad
© 2026 Gemlead, Inc. Todos los derechos reservados.
Español