Add Organization Users to a Group

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: The caller must be an owner of the group. canBeManaged on the group is the same check. Read access on the organization is not enough.
Group UUID: Identify the organization group you want to add users to. Use List Organization Groups to discover group UUIDs.
Organization members: Provide at least one email or user UUID of someone who is already an organization member. This call does not invite people who are outside the organization.

Step 1: Find the Group UUID

List an organization's groups with List Organization Groups and take the uuid of the group you want.
See our Get resource IDs page for more on retrieving resource identifiers.
Read provisioned from that query, or from Retrieve a Group, Its Owners, Users, and Available Interfaces. Stop if provisioned is true. Users can only be added to a provisioned group by the Identity Provider.

Step 2: Add the Users

The inviteUserToGroup mutation adds existing organization members to an organization group. Send at least one of usersEmails or usersUuids. Sending both adds the union of the two lists. The users payload is that matched set, not every member of the group, and order is not guaranteed.

mutation {
  inviteUserToGroup(
    input: {
      groupUuid: "group-uuid-here"
      usersEmails: ["[email protected]"]
    }
  ) {
    success
    users {
      id
      uuid
      name
      email
      avatarUrl
    }
  }
}

Arguments

groupUuid (ID!, required): the UUID of the organization group.
usersEmails ([String], optional): emails of users who already belong to the organization.
usersUuids ([ID], optional): UUIDs of users who already belong to the organization.
clientMutationId (String, optional): a Relay client id. When you send it, the payload echoes it.

At least one of usersEmails and usersUuids must be a non-empty list. Null entries inside the lists are not a supported input.

To add by email and UUID in one call, send both lists:

mutation {
  inviteUserToGroup(
    input: {
      groupUuid: "group-uuid-here"
      usersEmails: ["[email protected]"]
      usersUuids: ["user-uuid-here"]
    }
  ) {
    success
    users {
      id
      uuid
      name
      email
      avatarUrl
    }
  }
}

Sample response

id is a string. name may be null.

{
  "data": {
    "inviteUserToGroup": {
      "success": true,
      "users": [
        {
          "id": "456",
          "uuid": "user-uuid-here",
          "name": "Ada Lovelace",
          "email": "[email protected]",
          "avatarUrl": "https://app.pipefy.com/avatar.png"
        }
      ]
    }
  }
}

Step 3: Confirm Membership

After a successful call, confirm the users belong to the group with the groupUsers query in Retrieve a Group, Its Owners, Users, and Available Interfaces.

Key Notes

Permission: when the caller cannot manage the group, the error is Permission denied. That error is the only one that sets extensions.code to PERMISSION_DENIED.
Unknown group: an unknown UUID, or a group that is not an organization group, returns Couldn't find Group with uuid: ....
Empty input: when neither list is present or both are empty, the error is At least one item in 'users_uuids' or 'users_emails' argument is required.
User not in the organization: when the person is missing or is not in the organization, the error is Couldn't find User with email: ... or Couldn't find User with uuid: .... Several values are comma-separated in one message.
Already a member: after every requested user is found in the organization, an existing member returns User email: ... is already in this group or User uuid: ... is already in this group.
Provisioned group: a group with provisioned: true returns Users can only be added to provisioned groups by the Identity Provider.
These failures are GraphQL errors with inviteUserToGroup: null. success: false is not a response. A validation failure adds nobody.

Only users who already belong to the organization can be added.