Gemlead
Docs
Accedi
Ottieni la tua chiave API

Riferimento API

Buyer persona

Una buyer persona è un tipo di acquirente che vuoi raggiungere, come tipster o titolari di agenzia. Gemlead trova lead per ogni buyer persona attiva e li valuta in base alla sua descrizione. Le sue fonti decidono dove cerca Gemlead.

Un proprietario con più account X può condividere una buyer persona tra questi account. Lavorano con le stesse fonti, le stesse impostazioni e gli stessi lead, ognuno con le sue campagne, e un lead va a un solo account X. La condivisione della buyer persona stabilisce quali account X la condividono.

Endpoint

L'oggetto buyer persona

Un tipo di acquirente che vuoi raggiungere. Gemlead cerca i lead che corrispondono a ogni buyer persona attiva e li valuta rispetto a essa.

Attributi

  • idstring
    Identificatore univoco della buyer persona.
  • objectstring
    Sempre persona.
  • namestring
    Il nome breve della buyer persona, come Tipsters.
  • descriptionstring
    Chi è questo acquirente, con parole tue. Lo scoring si basa su questo testo.
  • marketstring
    Se vendi ad aziende o a consumatori.
    b2bb2c
  • statusstring
    Se Gemlead sta cercando lead per questa buyer persona.
    activepaused
  • websitestring o null
    Il sito web di ciò che vendi a questa buyer persona.
  • statsobject
    Conteggi dalla creazione della buyer persona, e per oggi nel fuso orario del tuo profilo.
  • sharingobject
    Gli account X del proprietario che condividono la buyer persona. Vedi la condivisione della buyer persona.
  • created_atstring
    Quando è stata creata la buyer persona, ISO 8601.
  • updated_atstring
    Quando la buyer persona è cambiata l'ultima volta, ISO 8601.
L'oggetto buyer 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"
}

Elenca le buyer persona

GET/v1/personasScope readMCPlist_personas

Restituisce le tue buyer persona nello stesso ordine della pagina Persona.

Parametri di query

  • limitinteger
    Quanti oggetti restituire, da 1 a 100. Di default 25.
  • cursorstring
    Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti buyer persona.

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

Recupera una buyer persona

GET/v1/personas/:idScope readMCPget_persona

Restituisce una buyer persona con le sue statistiche.

Parametri di percorso

  • idstringObbligatorio
    L'ID della buyer persona.

Restituisce

Un oggetto buyer persona.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
GET/v1/personas/:id
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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"
}

Crea una buyer persona

POST/v1/personasScope writeMCPcreate_persona

Crea una buyer persona e inizia subito a trovare i suoi lead. Lo scoring usa fino a 2 crediti per lead: 1 per la prima valutazione, 1 in più per quella approfondita se il lead la supera, con un massimo di daily_scoring_limit lead al giorno. Aggiungi le fonti ora o più tardi con Aggiungi una fonte.

Parametri del body

  • namestringObbligatorio
    Il nome della buyer persona, da una a tre parole come Ghostwriters, fino a 100 caratteri.
  • websitestring
    Il sito web del tuo prodotto, fino a 500 caratteri. L'IA che valuta i lead lo legge.
  • descriptionstringObbligatorio
    Chi è questo acquirente, con parole semplici. L'IA valuta ogni lead da 0 a 100 rispetto a questo testo, quindi è il campo più importante. Può contenere le tue regole di scoring. Fino a 12 000 caratteri.
  • marketstring
    b2b quando comprano le aziende, b2c quando le persone comprano per sé. Di default b2b.
    b2bb2c
  • keywordsarray di strings
    Parole in un profilo o nei suoi post che segnalano un fit. Fino a 100, ognuna fino a 100 caratteri.
  • competitorsarray di strings
    Prodotti come il tuo, chi ne usa uno è in target. Fino a 100.
  • avoidarray di strings
    A chi dare un punteggio basso, come agencies o students. Fino a 100.
  • min_followersinteger
    I profili con meno follower non vengono valutati, da 0 a 10 000 000. Di default 100.
  • include_closed_inboxesboolean
    Valuta anche le persone con i DM chiusi, una campagna le raggiunge con un commento. Di default true.
  • auto_expandboolean
    Lascia che Gemlead aggiunga fonti da solo partendo dai lead migliori quando le altre si esauriscono. Di default false.
  • auto_expand_directionstring
    Dove deve puntare l'espansione automatica, in parole semplici come more US founders. Fino a 500 caratteri.
  • daily_scoring_limitinteger
    Il numero massimo di lead valutati al giorno per questa buyer persona, fino a 2 crediti per lead: 1 per la prima valutazione, 1 in più per quella approfondita se il lead la supera. Da 100 a 20 000. Di default il ritmo del tuo piano, 3 300 al giorno su Starter e 10 000 su Business.
  • sourcesarray di objects
    Fino a 20 fonti di partenza. Gli account di investitori, acceleratori e media vengono rifiutati, non portano acquirenti.

Restituisce

Il nuovo oggetto buyer persona.

Errori

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

Attiva una buyer persona

POST/v1/personas/:persona_id/activateScope writeMCPupdate_persona

Riattiva una buyer persona in pausa. Le sue fonti vengono lette e i suoi lead valutati.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Restituisce

L'oggetto buyer persona.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
POST/v1/personas/:persona_id/activate
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/activate \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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"
}

Metti in pausa una buyer persona

POST/v1/personas/:persona_id/pauseScope writeMCPupdate_persona

Mette in pausa una buyer persona. Gemlead smette di leggere le sue fonti e di valutare i suoi lead, e i lead restano.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Restituisce

L'oggetto buyer persona, con lo status su paused.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
POST/v1/personas/:persona_id/pause
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/pause \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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"
}

Elimina una buyer persona

DELETE/v1/personas/:persona_idScope writeMCPdelete_persona

Elimina una buyer persona con le sue fonti e i lead su cui nessuna campagna ha lavorato. Le sue campagne vengono archiviate. Non si può annullare.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Restituisce

Un oggetto con l'id della buyer persona, deleted impostato su true e i conteggi di archived_campaigns e deleted_sources. I suoi lead vengono eliminati in background, quindi deleted_leads è null e possono ancora comparire in Elenca i lead per qualche minuto.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
DELETE/v1/personas/:persona_id
curl -X DELETE https://gemlead.ai/api/v1/personas/lvWBPnytpS \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "id": "lvWBPnytpS",
  "object": "persona",
  "deleted": true,
  "archived_campaigns": 1,
  "deleted_sources": 6,
  "deleted_leads": null
}

Riordina le buyer persona

POST/v1/personas/reorderScope writeMCPreorder_personas

Imposta l'ordine delle tue buyer persona, come le elenca l'app. Invia ogni buyer persona una sola volta.

Parametri del body

  • persona_idsarray di stringsObbligatorio
    Gli ID di tutte le buyer persona dell'account, nel nuovo ordine.

Restituisce

Un elenco di oggetti buyer persona nel nuovo ordine.

Errori

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

L'oggetto impostazioni della buyer persona

Tutto ciò che determina quali lead trova una buyer persona e come l'IA li valuta, come nella pagina della buyer persona nell'app.

Attributi

  • objectstring
    Sempre persona_settings.
  • persona_idstring
    L'ID della buyer persona.
  • namestring
    Il nome della buyer persona, da una a tre parole come Ghostwriters.
  • websitestring o null
    Il sito web del tuo prodotto. L'IA che valuta i lead lo legge.
  • descriptionstring o null
    Chi è questo acquirente, con parole semplici. L'IA valuta ogni lead da 0 a 100 rispetto a questo testo, quindi è il campo più importante. Può contenere le tue regole di scoring.
  • marketstring
    b2b quando comprano le aziende, b2c quando le persone comprano per sé.
    b2bb2c
  • keywordsarray di strings
    Parole in un profilo o nei suoi post che segnalano un fit.
  • competitorsarray di strings
    Prodotti come il tuo. Chi ne usa uno è in target.
  • avoidarray di strings
    A chi dare un punteggio basso, come agencies o students.
  • min_followersinteger
    I profili con meno follower non vengono valutati.
  • include_closed_inboxesboolean
    Se vengono valutate anche le persone con i DM chiusi. Una campagna le raggiunge con un commento.
  • auto_expandboolean
    Se Gemlead aggiunge fonti da solo partendo dai lead migliori quando le altre si esauriscono.
  • auto_expand_directionstring o null
    Dove deve puntare l'espansione automatica, in parole semplici, come more US founders.
  • daily_scoring_limitinteger
    Il numero massimo di lead valutati al giorno per questa buyer persona, fino a 2 crediti per lead: 1 per la prima valutazione, 1 in più per quella approfondita se il lead la supera.
  • statusstring
    Se Gemlead sta trovando e valutando lead per questa buyer persona.
    activepaused
  • search_queriesarray di strings
    Le sue ricerche per parola chiave.
  • competitor_accountsarray di strings
    I suoi account concorrenti, username X senza la @.
  • updated_atstring
    Quando la buyer persona è cambiata l'ultima volta, ISO 8601.
L'oggetto impostazioni della buyer persona
{
  "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"
}

Recupera le impostazioni della buyer persona

GET/v1/personas/:persona_id/settingsScope readMCPget_persona_settings

Restituisce tutte le impostazioni di una buyer persona, con le sue ricerche per parola chiave e i suoi account concorrenti.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Restituisce

Un oggetto impostazioni della buyer persona.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
GET/v1/personas/:persona_id/settings
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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"
}

Aggiorna le impostazioni della buyer persona

PATCH/v1/personas/:persona_id/settingsScope writeMCPupdate_persona

Modifica le impostazioni che invii e mantiene le altre. Un elenco che invii sostituisce l'intero elenco, quindi invia keywords con la nuova parola aggiunta per mantenere le altre.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri del body

  • namestring
    Il nome della buyer persona, da una a tre parole come Ghostwriters, fino a 100 caratteri.
  • websitestring
    Il sito web del tuo prodotto, fino a 500 caratteri. L'IA che valuta i lead lo legge.
  • descriptionstring
    Chi è questo acquirente, con parole semplici. L'IA valuta ogni lead da 0 a 100 rispetto a questo testo, quindi è il campo più importante. Può contenere le tue regole di scoring. Fino a 12 000 caratteri.
  • marketstring
    b2b quando comprano le aziende, b2c quando le persone comprano per sé. Di default b2b.
    b2bb2c
  • keywordsarray di strings
    Parole in un profilo o nei suoi post che segnalano un fit. Fino a 100, ognuna fino a 100 caratteri.
  • competitorsarray di strings
    Prodotti come il tuo, chi ne usa uno è in target. Fino a 100.
  • avoidarray di strings
    A chi dare un punteggio basso, come agencies o students. Fino a 100.
  • min_followersinteger
    I profili con meno follower non vengono valutati, da 0 a 10 000 000. Di default 100.
  • include_closed_inboxesboolean
    Valuta anche le persone con i DM chiusi, una campagna le raggiunge con un commento. Di default true.
  • auto_expandboolean
    Lascia che Gemlead aggiunga fonti da solo partendo dai lead migliori quando le altre si esauriscono. Di default false.
  • auto_expand_directionstring
    Dove deve puntare l'espansione automatica, in parole semplici come more US founders. Fino a 500 caratteri.
  • daily_scoring_limitinteger
    Il numero massimo di lead valutati al giorno per questa buyer persona, fino a 2 crediti per lead: 1 per la prima valutazione, 1 in più per quella approfondita se il lead la supera. Da 100 a 20 000 per ogni account X che condivide la buyer persona.

Restituisce

L'oggetto impostazioni della buyer persona aggiornato.

Errori

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

L'oggetto condivisione della buyer persona

Gli account X di uno stesso proprietario che lavorano con la stessa buyer persona. Ne condividono le fonti, le impostazioni, i lead e la lista di esclusione, e ognuno ci porta avanti le sue campagne. Un lead va a un solo account X, indicato dal suo locked_to.

Attributi

  • objectstring
    Sempre persona_sharing.
  • persona_idstring
    L'ID della buyer persona.
  • home_accountobject o null
    L'account X su cui è stata creata la buyer persona. Le sue fonti e i suoi lead fanno capo a questo account.
  • shared_witharray di objects
    Gli altri account X che condividono la buyer persona. Vuoto se non è condivisa.
  • available_accountsarray di objects
    Gli altri account X del proprietario con cui si può condividere la buyer persona. Sempre vuoto per un membro del team, che non può cambiare la condivisione.
  • daily_scoring_limitinteger
    Il numero massimo di lead valutati al giorno per la buyer persona, per tutto il gruppo. Può arrivare a 20 000 per ogni account X che condivide la buyer persona.
L'oggetto condivisione della buyer persona
{
  "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
}

Recupera la condivisione della buyer persona

GET/v1/personas/:persona_id/sharingScope readMCPget_persona_sharing

Restituisce quali account X del proprietario condividono una buyer persona, e gli altri con cui si può condividere.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Restituisce

Un oggetto condivisione della buyer persona.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
GET/v1/personas/:persona_id/sharing
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sharing \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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
}

Aggiorna la condivisione della buyer persona

PUT/v1/personas/:persona_id/sharingScope writeMCPupdate_persona_sharing

Imposta quali altri account X del proprietario condividono una buyer persona, da qualsiasi account X del gruppo, come fa Condivisa con nell'app. Invia la lista completa, o una vuota per smettere di condividerla. Il daily_scoring_limit segue la dimensione del gruppo, con lo stesso ritmo per ogni account X. Solo le chiavi del proprietario possono farlo.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri del body

  • account_idsarray di stringsObbligatorio
    Tutti gli altri account X del proprietario che condividono la buyer persona, fino a 20. Il suo account d'origine la tiene sempre.

Restituisce

L'oggetto condivisione della buyer persona aggiornato.

Errori

  • 400parameter_missing
    Manca un parametro obbligatorio. param lo indica.
  • 400parameter_invalid
    Un parametro ha un valore che l'API non accetta. param lo indica.
  • 400parameter_unknown
    Il body ha un campo che questo endpoint non accetta.
  • 403forbidden
    La chiave appartiene a un membro del team. Solo il proprietario può condividere una buyer persona.
  • 404resource_missing
    Nessuna buyer persona con questo ID, o un account X che non è del proprietario. param lo indica.
  • 400shared_account_has_campaigns
    Un account X che togli ha ancora campagne sulla buyer persona. Eliminale prima.
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"]
  }'
Risposta200
{
  "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
}

L'oggetto suggerimento di buyer persona

Una buyer persona che l'IA ha scritto per te partendo da un nome e dal tuo prodotto, pronta da creare così com'è o da modificare prima.

Attributi

  • objectstring
    Sempre persona_suggestion.
  • statusstring
    pending mentre l'IA scrive, poi ready o error. none prima della prima richiesta.
    pendingreadyerrornone
  • persona_namestring o null
    Il nome richiesto.
  • suggestionobject o null
    Quando è ready, la description, le keywords, i competitors e l'avoid della buyer persona, cioè i campi di Crea una buyer persona.
  • generated_atstring o null
    Quando è stata scritta, ISO 8601.
  • errorstring o null
    Cosa è andato storto, quando status è error.
L'oggetto suggerimento di buyer persona
{
  "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
}

Suggerisci una buyer persona

POST/v1/persona_suggestionsScope writeMCPsuggest_persona

Chiede all'IA di scrivere una buyer persona partendo da un nome e da ciò che vendi, oppure di riscrivere una descrizione. Richiede qualche secondo, quindi la risposta è pending. Leggi il risultato con Recupera il suggerimento di buyer persona.

Parametri del body

  • persona_namestringObbligatorio
    La buyer persona da scrivere, da una a tre parole come Ghostwriters.
  • websitestring
    Il sito web del tuo prodotto. Di default quello sul tuo profilo X.
  • briefstring
    Cosa vendi e a chi, con parole tue, fino a 1 000 caratteri.
  • current_descriptionstring
    Una descrizione da riscrivere, con instruction.
  • instructionstring
    Come modificare current_description, per esempio shorter o only US agencies. Fino a 2 000 caratteri.

Restituisce

Un oggetto suggerimento di buyer persona, con lo status su pending.

Errori

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."
  }'
Risposta202
{
  "object": "persona_suggestion",
  "status": "pending",
  "persona_name": "Tipsters",
  "suggestion": null,
  "generated_at": null,
  "error": null
}

Recupera il suggerimento di buyer persona

GET/v1/persona_suggestions/latestScope readMCPget_persona_suggestion

Restituisce l'ultimo suggerimento di buyer persona dell'account. Richiedilo di nuovo ogni qualche secondo finché è pending.

Restituisce

Un oggetto suggerimento di buyer persona.

GET/v1/persona_suggestions/latest
curl https://gemlead.ai/api/v1/persona_suggestions/latest \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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
}
Ricevi gli aggiornamenti di Gemlead
direttamente nella tua casella email.
Iscriviti
Iscrivendoti accetti la nostra Informativa sulla privacy e acconsenti a ricevere aggiornamenti dalla nostra azienda.
Gemlead
Prodotto
Inizia
Accedi
Per chi
Agenti IA
Funzionalità
Prezzi
Affiliazione
FAQ
Funzionalità
Acquirenti, 24/7Prima i lead caldiOltre il 60% rispondeDM su misuraTutti i DM in un'inboxIl tuo closer IAScala senza limitiAPI, MCP, webhookChiedi a Gemlead
Risorse
HomeAPIBlog
Note legali
Termini
Privacy
© 2026 Gemlead, Inc. Tutti i diritti riservati.
Italiano