Riferimento API

Team

Il proprietario di un account X può condividerlo con altri utenti Gemlead. Ogni membro ci lavora con il piano e i crediti del proprietario, e il suo ruolo decide cosa può modificare, area per area. La fatturazione e la connessione dell'account X restano al proprietario.

Il proprietario e gli admin invitano e modificano i membri. Solo il proprietario può nominare o modificare un admin. Un account X ha al massimo 50 membri, inviti compresi.

Un membro il cui ruolo può modificare le impostazioni può creare una sua chiave API o collegare un'app di IA. Quella chiave ha gli stessi permessi del ruolo del membro, mai di più, e smette di funzionare appena il membro lascia il team.

Endpoint

GET/v1/team
POST/v1/team/members
PATCH/v1/team/members/:member_id
DELETE/v1/team/members/:member_id
POST/v1/team/leave

L'oggetto team

Chi lavora sull'account X in Gemlead, prima il proprietario, e cosa può farci l'utente della chiave.

Attributi

objectstring
Sempre team.
account_idstring
L'ID dell'account X, come nell'oggetto account.
your_rolestring
Il ruolo dell'utente della chiave. owner per le chiavi del proprietario.
ownerviewersettereditoradmincustom
your_member_idstring o null
L'utente della chiave come membro, null per il proprietario.
ownerobject
L'utente Gemlead che ha collegato l'account X e lo paga.
membersarray di objects
I membri e gli inviti, come oggetti membro del team.
max_membersinteger
Il numero massimo di membri di un account X, inviti compresi.

L'oggetto team

{
  "object": "team",
  "account_id": "a9PzK2vRtM",
  "your_role": "owner",
  "your_member_id": null,
  "owner": {
    "name": "Alex Moreau",
    "email": "alex@acme.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg"
  },
  "members": [
    {
      "id": "Tm4kQ9wZrB",
      "object": "team_member",
      "email": "sara@acme.com",
      "name": "Sara Kim",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1733920571/sara_400x400.jpg",
      "role": "setter",
      "zones": {
        "personas": "view",
        "campaigns": "view",
        "chat": "edit",
        "leads": "edit",
        "settings": "view"
      },
      "status": "active",
      "created_at": "2026-09-14T09:21:05.300Z"
    },
    {
      "id": "Tm8vX2pLnC",
      "object": "team_member",
      "email": "dev@acme.com",
      "name": null,
      "profile_image_url": null,
      "role": "custom",
      "zones": {
        "personas": "edit",
        "campaigns": "view",
        "chat": "view",
        "leads": "edit",
        "settings": "view"
      },
      "status": "invited",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "max_members": 50
}

Recupera il team

GET/v1/teamScope readMCPget_team

Restituisce il proprietario dell'account X, poi ogni membro e ogni invito con ruolo e aree, e il ruolo dell'utente della chiave.

Restituisce

L'oggetto team.

GET/v1/team

curl https://gemlead.ai/api/v1/team \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Risposta200

{
  "object": "team",
  "account_id": "a9PzK2vRtM",
  "your_role": "owner",
  "your_member_id": null,
  "owner": {
    "name": "Alex Moreau",
    "email": "alex@acme.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg"
  },
  "members": [
    {
      "id": "Tm4kQ9wZrB",
      "object": "team_member",
      "email": "sara@acme.com",
      "name": "Sara Kim",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1733920571/sara_400x400.jpg",
      "role": "setter",
      "zones": {
        "personas": "view",
        "campaigns": "view",
        "chat": "edit",
        "leads": "edit",
        "settings": "view"
      },
      "status": "active",
      "created_at": "2026-09-14T09:21:05.300Z"
    },
    {
      "id": "Tm8vX2pLnC",
      "object": "team_member",
      "email": "dev@acme.com",
      "name": null,
      "profile_image_url": null,
      "role": "custom",
      "zones": {
        "personas": "edit",
        "campaigns": "view",
        "chat": "view",
        "leads": "edit",
        "settings": "view"
      },
      "status": "invited",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "max_members": 50
}

L'oggetto membro del team

Una persona con cui il proprietario condivide l'account X, o un invito non ancora accettato.

Attributi

idstring
Identificatore univoco del membro.
objectstring
Sempre team_member.
emailstring
L'email a cui è stato inviato l'invito.
namestring o null
Il suo nome in Gemlead. Null finché non entra nel team.
profile_image_urlstring o null
L'URL della sua foto profilo.
rolestring
viewer vede tutto e non modifica niente. setter gestisce la chat e i lead. editor modifica tutto tranne le impostazioni. admin modifica tutto e gestisce il team. custom modifica le aree che scegli.
viewersettereditoradmincustom
zonesobject
Cosa può modificare il membro, area per area, ciascuna su view o edit. Il ruolo le imposta, e custom tiene quelle che scegli.
statusstring
active appena ha un account Gemlead con questa email, invited fino ad allora.
invitedactive
created_atstring
Quando è stato inviato l'invito, ISO 8601.

L'oggetto membro del team

{
  "id": "Tm4kQ9wZrB",
  "object": "team_member",
  "email": "sara@acme.com",
  "name": "Sara Kim",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1733920571/sara_400x400.jpg",
  "role": "setter",
  "zones": {
    "personas": "view",
    "campaigns": "view",
    "chat": "edit",
    "leads": "edit",
    "settings": "view"
  },
  "status": "active",
  "created_at": "2026-09-14T09:21:05.300Z"
}

Invita un membro

POST/v1/team/membersScope writeMCPedit_team

Invita qualcuno nel team dell'account X via email, con un ruolo, e gli manda un'email. Chi ha un account Gemlead con questa email entra subito, gli altri appena si iscrivono con questa email.

Parametri del body

emailstringObbligatorio
L'email della persona da invitare, fino a 200 caratteri.
rolestringObbligatorio
Cosa può fare il membro. Vedi role nell'oggetto membro del team.
viewersettereditoradmincustom
zonesobject
Solo con il ruolo custom, cosa può modificare il membro, area per area, ciascuna su view o edit. Un'area non indicata resta su view.

Restituisce

Il nuovo oggetto membro del team, con status su active se ha un account Gemlead, altrimenti invited.

Errori

400parameter_missing
Manca un parametro obbligatorio. param lo indica.
400parameter_invalid
Un parametro ha un valore che l'API non accetta, come zones con un ruolo diverso da custom o l'email stessa del proprietario. param lo indica.
400parameter_unknown
Il body ha un campo che questo endpoint non accetta.
403forbidden
L'utente della chiave non può modificare il team. Possono farlo il proprietario e gli admin, e solo il proprietario può nominare o modificare un admin.
400resource_already_exists
Questa email è già nel team, come membro o come invito.
400limit_reached
L'account X ha già 50 membri, inviti compresi.

POST/v1/team/members

curl -X POST https://gemlead.ai/api/v1/team/members \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@acme.com",
    "role": "custom",
    "zones": {
      "personas": "edit",
      "leads": "edit"
    }
  }'

Risposta200

{
  "id": "Tm8vX2pLnC",
  "object": "team_member",
  "email": "dev@acme.com",
  "name": null,
  "profile_image_url": null,
  "role": "custom",
  "zones": {
    "personas": "edit",
    "campaigns": "view",
    "chat": "view",
    "leads": "edit",
    "settings": "view"
  },
  "status": "invited",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Aggiorna un membro

PATCH/v1/team/members/:member_idScope writeMCPedit_team

Cambia il ruolo di un membro, o cosa può modificare area per area. Se invii zones, il ruolo diventa custom e cambiano solo le aree che invii.

Parametri di percorso

member_idstringObbligatorio
L'ID del membro del team.

Parametri del body

rolestring
Cosa può fare il membro. Vedi role nell'oggetto membro del team.
viewersettereditoradmincustom
zonesobject
Le aree da cambiare, ciascuna su view o edit. Le altre restano come sono.

Restituisce

L'oggetto membro del team aggiornato.

Errori

404resource_missing
Nessun membro del team con questo ID sull'account della chiave.
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
L'utente della chiave non può modificare il team. Possono farlo il proprietario e gli admin, e solo il proprietario può nominare o modificare un admin.

PATCH/v1/team/members/:member_id

curl -X PATCH \
  https://gemlead.ai/api/v1/team/members/Tm4kQ9wZrB \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "editor"
  }'

Risposta200

{
  "id": "Tm4kQ9wZrB",
  "object": "team_member",
  "email": "sara@acme.com",
  "name": "Sara Kim",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1733920571/sara_400x400.jpg",
  "role": "editor",
  "zones": {
    "personas": "edit",
    "campaigns": "edit",
    "chat": "edit",
    "leads": "edit",
    "settings": "view"
  },
  "status": "active",
  "created_at": "2026-09-14T09:21:05.300Z"
}

Rimuovi un membro

DELETE/v1/team/members/:member_idScope writeMCPedit_team

Rimuove un membro dal team, o annulla un invito. Perde subito l'accesso all'account X.

Parametri di percorso

member_idstringObbligatorio
L'ID del membro del team.

Restituisce

Un oggetto con l'id del membro e deleted impostato su true.

Errori

404resource_missing
Nessun membro del team con questo ID sull'account della chiave.
403forbidden
L'utente della chiave non può modificare il team. Possono farlo il proprietario e gli admin, e solo il proprietario può nominare o modificare un admin.

DELETE/v1/team/members/:member_id

curl -X DELETE \
  https://gemlead.ai/api/v1/team/members/Tm8vX2pLnC \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Risposta200

{
  "id": "Tm8vX2pLnC",
  "object": "team_member",
  "deleted": true
}

Lascia il team

POST/v1/team/leaveScope writeMCPedit_team

Toglie l'utente della chiave dal team dell'account X. Funziona con la chiave di un membro, mai con quella del proprietario.

Restituisce

Un oggetto con l'id del membro e deleted impostato su true.

Errori

400owner_cannot_leave
La chiave è del proprietario, che può invece rimuovere i membri.

POST/v1/team/leave

curl -X POST https://gemlead.ai/api/v1/team/leave \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Risposta200

{
  "id": "Tm4kQ9wZrB",
  "object": "team_member",
  "deleted": true
}