# Users & Groups

Gophish manages recipients for campaigns in groups. Each group can contain one or more recipients. Groups have the following format:

```
{
    id              : int64
    name            : string
    targets         : array(Target)
    modified_date   : string(datetime)
}
```

Each recipient in the `targets` field has the following format:

```
{
    email           : string
    first_name      : string
    last_name       : string
    position        : string
}
```

## Get Groups

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/groups/`

Returns a list of groups.

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "id": 1,
    "name": "Example Group",
    "modified_date": "2018-10-08T15:56:13.790016Z",
    "targets": [
      {
        "email": "user@example.com",
        "first_name": "Example",
        "last_name": "User",
        "position": ""
      },
      {
        "email": "foo@bar.com",
        "first_name": "Foo",
        "last_name": "Bar",
        "position": ""
      }
    ]
  }
]
```

{% endtab %}
{% endtabs %}

## Get Group

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/groups/:id`

Returns a group with the given ID.

#### Path Parameters

| Name | Type    | Description  |
| ---- | ------- | ------------ |
| id   | integer | The group ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1,
  "name": "Example Group",
  "modified_date": "2018-10-08T15:56:13.790016Z",
  "targets": [
    {
      "email": "user@example.com",
      "first_name": "Example",
      "last_name": "User",
      "position": ""
    },
    {
      "email": "foo@bar.com",
      "first_name": "Foo",
      "last_name": "Bar",
      "position": ""
    }
  ]
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{
  "message": "Group not found",
  "success": false,
  "data": null
}
```

{% endtab %}
{% endtabs %}

Returns a 404 error if no group is found with the provided ID.

## Get Groups Summary

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/groups/summary`

Returns a summary of each group.

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "id": 1,
    "name": "Example Group",
    "modified_date": "2018-10-08T15:56:13.790016Z",
    "num_targets": 2
  }
]
```

{% endtab %}
{% endtabs %}

## Get Group Summary

<mark style="color:blue;">`GET`</mark> `https://localhost:3333/api/groups/:id/summary`

Returns a summary for a group.

#### Path Parameters

| Name | Type    | Description  |
| ---- | ------- | ------------ |
| id   | integer | The group ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1,
  "name": "Example Group",
  "modified_date": "2018-10-08T15:56:13.790016Z",
  "num_targets": 2
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{
  "message": "Group not found",
  "success": false,
  "data": null
}
```

{% endtab %}
{% endtabs %}

It may be the case that you just want the number of members in a group, not necessarily the full member details. This API endpoint returns a summary for a group.

Returns a 404 error if no group is found with the provided ID.

## Create Group

<mark style="color:green;">`POST`</mark> `https://localhost:3333/api/groups/`

Creates a new group.

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

#### Request Body

| Name    | Type   | Description                         |
| ------- | ------ | ----------------------------------- |
| Payload | object | The group to create in JSON format. |

{% tabs %}
{% tab title="201 " %}

```javascript
{
  "id": 1,
  "name": "Example Group",
  "modified_date": "2018-10-08T15:56:13.790016Z",
  "targets": [
    {
      "email": "user@example.com",
      "first_name": "Example",
      "last_name": "User",
      "position": ""
    },
    {
      "email": "foo@bar.com",
      "first_name": "Foo",
      "last_name": "Bar",
      "position": ""
    }
  ]
}
```

{% endtab %}

{% tab title="400 If an invalid request is provided, an error message will be returned" %}

```
{
  "message": "Group name not specified",
  "success": false,
  "data": null
}
```

{% endtab %}
{% endtabs %}

When creating a new group, you must specify a unique `name`, as well as a list of `targets`. Here's an example request body:

```javascript
{
    "name": "Example Group",
    "targets": [
    {
        "email": "user@example.com",
        "first_name": "Example",
        "last_name": "User",
        "position": ""
    },
    {
        "email": "foo@bar.com",
        "first_name": "Foo",
        "last_name": "Bar",
        "position": ""
    }
    ]
}
```

## Modify Group

<mark style="color:orange;">`PUT`</mark> `https://localhost:3333/api/groups/:id`

Modifies a group.

#### Path Parameters

| Name | Type    | Description  |
| ---- | ------- | ------------ |
| id   | integer | The group ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

#### Request Body

| Name    | Type   | Description                                                                |
| ------- | ------ | -------------------------------------------------------------------------- |
| Payload | object | The updated group content. The full group must be provided in JSON format. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1,
  "name": "Example Modified Group",
  "modified_date": "2018-10-08T15:56:13.790016Z",
  "targets": [
    {
      "email": "foo@bar.com",
      "first_name": "Foo",
      "last_name": "Bar",
      "position": ""
    }
  ]
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{
  "message": "Group not found",
  "success": false,
  "data": null
}
```

{% endtab %}
{% endtabs %}

This API endpoint allows you to modify an existing group. The request must include the complete group JSON, not just the fields you're wanting to update. This means that you need to include the matching `id` field. Here's an example request:

```javascript
{
    "id": 1,
    "name": "Example Modified Go",
    "targets": [
    {
        "email": "foo@bar.com",
        "first_name": "Foo",
        "last_name": "Bar",
        "position": ""
    }
    ]
}
```

Returns a 404 if no group is found with the provided ID.

## Delete Group

<mark style="color:red;">`DELETE`</mark> `https://localhost:3333/api/groups/:id`

Deletes a group

#### Path Parameters

| Name | Type   | Description  |
| ---- | ------ | ------------ |
| id   | number | The group ID |

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "message": "Group deleted successfully!",
  "success": true,
  "data": null
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{
  "message": "Group not found",
  "success": false,
  "data": null
}
```

{% endtab %}
{% endtabs %}

Returns a 404 error if no group is found with the provided ID.

## Import Group

<mark style="color:green;">`POST`</mark> `https://localhost:3333/api/import/group`

Reads and parses a CSV, returning data that can be used to create a group.

#### Headers

| Name          | Type   | Description     |
| ------------- | ------ | --------------- |
| Authorization | string | A valid API key |

#### Request Body

| Name | Type   | Description                                        |
| ---- | ------ | -------------------------------------------------- |
| file | object | A file upload containing the CSV content to parse. |

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "email": "foobar@example.com",
    "first_name": "Example",
    "last_name": "User",
    "position": "Systems Administrator"
  },
  {
    "email": "johndoe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "position": "CEO"
  }
]
```

{% endtab %}
{% endtabs %}

This API endpoint allows you to upload a CSV, returning a list of group targets. For example, you can use the following `curl` command to upload the CSV:

```
curl -k https://localhost:3333/api/import/group -XPOST \
    -F "file=@group_template.csv" \
    -H "Authorization: Bearer 0123456789abcdef"
```

The results of this API endpoint can be used as the `targets` parameter in a call to the [Create Group](#create-group) endpoint.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.getgophish.com/api-documentation/users-and-groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.