Skip to content
Browse docssuggest_group_members

suggest_group_members

Reads who could join a group, from your own Rolodex only.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

When to use it#

When the member asks who to invite, or before preparing invitations so the choice is theirs. With the publicId of a group they moderate, it ranks people in their own Rolodex by how they already write with the group's members and overlap its goals, with one plain line each on why, and lists who is already in the group. With null, for a group not yet created, it returns circles of people who write together in the member's own mail, each with a name and a reason.

People already in the group or already invited are left out. It never reads another member's relationships. A member who does not moderate the group gets status: "not_moderator", the moderator’s name, and candidates from their own Rolodex with one-line reasons and no addresses. Help them draft a suggestion to the moderator. Reading candidates grants no invitation authority.

Inputs#

InputRequiredTypeDescription
groupPublicIdyesstring or nullA group you belong to, or null for a group you have not created yet.

Returns#

FieldTypeDescription
statusstringsuccess for moderator/new-group suggestions, or not_moderator for suggestions to pass to the moderator
groupobject or null{ publicId, name, members, memberCount } for an existing group; members names those already in it
suggestionslistFor an existing group: { personId, name, email, why, knownMembers }, best first
circleslistFor a new group: { name, description, why, people }, each person { personId, name, email }

For not_moderator, the result contains only status, moderatorName (string or null), message, and suggestions with { personId, name, why }. Only a moderator can use issue_invitations.

Email addresses are the member's own saved addresses for the person, for issue_invitations. Don't put them anywhere another person could read.

Example#

json
{
  "groupPublicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Result (synthetic data):

json
{
  "status": "success",
  "group": {
    "publicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "name": "Synthetic founders",
    "members": ["Synthetic connector"],
    "memberCount": 2
  },
  "suggestions": [
    {
      "personId": "00000000-0000-4000-a000-000000000005",
      "name": "Synthetic Pat",
      "email": "pat@example.test",
      "why": "Writes with Synthetic connector most weeks.",
      "knownMembers": ["Synthetic connector"]
    }
  ],
  "circles": []
}