> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapnito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Group users API

> Search a group in your Zapnito community for existing users, and add or remove known users through the API.

Search a group for existing users, and add or remove known users. To get a group's `uuid`, [create a group](/api/v1/groups) or find it in the group's settings in your community.

Before you start, read the [API overview](/api/v1/overview) for how authentication, headers, pagination and errors work.

## Find users in a group

Check whether a user is already in a group. Matching users are returned in an array, and the array is empty when nothing matches.

<ParamField path="uuid" type="string" required>
  The UUID of the group.
</ParamField>

<ParamField query="query" type="string">
  An email address, or part of one, to match against the group's users.
</ParamField>

```bash title="Find users in a group" theme={null}
curl "https://your-community.zapnito.com/api/v1/groups/GROUP_UUID/users?query=joe" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"
```

`GET https://your-community.zapnito.com/api/v1/groups/:uuid/users`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "users": [
      {
        "name": "Maya Patel",
        "email": "maya.patel@example.com",
        "title": "Head of Compliance"
      },
      {
        "name": "Daniel Reyes",
        "email": "daniel.reyes@example.com",
        "title": "Regulatory Counsel"
      }
    ]
  }
  ```
</ResponseExample>

## Add a user to a group

Add a known user to a group.

<ParamField path="uuid" type="string" required>
  The UUID of the group to add the user to.
</ParamField>

<ParamField body="user.email" type="string" required>
  The email address of the user to add.
</ParamField>

```bash title="Add a user to a group" theme={null}
curl -X POST "https://your-community.zapnito.com/api/v1/groups/GROUP_UUID/users" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"user": {"email": "alex.smith@example.com"}}'
```

`POST https://your-community.zapnito.com/api/v1/groups/:uuid/users`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "User alex.smith@example.com added to group Expert Users with UUID GROUP_UUID"
  }
  ```
</ResponseExample>

* `200 OK`: the user was added, or already belongs to the group. If they already belong, the response carries an `errors` message instead: `User alex.smith@example.com already belongs to group Expert Users with UUID GROUP_UUID`.
* `401 Unauthorized`: your API token is invalid, expired or badly formatted. See [authentication](/api/v1/overview#authentication).
* `404 Not Found`: no group matches the UUID, or no user matches the email address. The messages read `Group not found for UUID: '...'` and `User not found for email: '...'`.

## Remove a user from a group

Remove a known user from a group.

<ParamField path="uuid" type="string" required>
  The UUID of the group to remove the user from.
</ParamField>

<ParamField body="user.email" type="string" required>
  The email address of the user to remove.
</ParamField>

```bash title="Remove a user from a group" theme={null}
curl -X DELETE "https://your-community.zapnito.com/api/v1/groups/GROUP_UUID/users" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"user": {"email": "jordan.lee@example.com"}}'
```

`DELETE https://your-community.zapnito.com/api/v1/groups/:uuid/users`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "User jordan.lee@example.com removed from group Expert Users with UUID GROUP_UUID"
  }
  ```
</ResponseExample>

* `200 OK`: the user was removed, or wasn't in the group. If they weren't in the group, the response carries an `errors` message instead: `User jordan.lee@example.com does not currently belong to group Expert Users with UUID GROUP_UUID`.
* `401 Unauthorized`: your API token is incorrect or expired. See [authentication](/api/v1/overview#authentication).
* `404 Not Found`: no group matches the UUID, or no user matches the email address. The messages read `Group not found for UUID: '...'` and `User not found for email: '...'`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.