Users & Groups

Last updated 4 months ago

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
Get Groups

https://localhost:3333
/api/groups/
Returns a list of groups.
Request
Response
Headers
Authorization
required
string
A valid API key
200: OK
[
{
"id": 1,
"name": "Example Group",
"modified_date": "2018-10-08T15:56:13.790016Z",
"targets": [
{
"email": "[email protected]",
"first_name": "Example",
"last_name": "User",
"position": ""
},
{
"email": "[email protected]",
"first_name": "Foo",
"last_name": "Bar",
"position": ""
}
]
}
]

get
Get Group

https://localhost:3333
/api/groups/:id
Returns a group with the given ID.
Request
Response
Path Parameters
id
required
integer
The group ID
Headers
Authorization
required
string
A valid API key
200: OK
{
"id": 1,
"name": "Example Group",
"modified_date": "2018-10-08T15:56:13.790016Z",
"targets": [
{
"email": "[email protected]",
"first_name": "Example",
"last_name": "User",
"position": ""
},
{
"email": "[email protected]",
"first_name": "Foo",
"last_name": "Bar",
"position": ""
}
]
}
404: Not Found
{
"message": "Group not found",
"success": false,
"data": null
}

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

get
Get Groups Summary

https://localhost:3333
/api/groups/summary
Returns a summary of each group.
Request
Response
Headers
Authorization
required
string
A valid API key
200: OK
[
{
"id": 1,
"name": "Example Group",
"modified_date": "2018-10-08T15:56:13.790016Z",
"num_targets": 2
}
]

get
Get Group Summary

https://localhost:3333
/api/groups/:id/summary
Returns a summary for a group.
Request
Response
Path Parameters
id
required
integer
The group ID
Headers
Authorization
required
string
A valid API key
200: OK
{
"id": 1,
"name": "Example Group",
"modified_date": "2018-10-08T15:56:13.790016Z",
"num_targets": 2
}
404: Not Found
{
"message": "Group not found",
"success": false,
"data": null
}

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.

post
Create Group

https://localhost:3333
/api/groups/
Creates a new group.
Request
Response
Headers
Authorization
required
string
A valid API key
Body Parameters
Payload
required
object
The group to create in JSON format.
201: Created
{
"id": 1,
"name": "Example Group",
"modified_date": "2018-10-08T15:56:13.790016Z",
"targets": [
{
"email": "[email protected]",
"first_name": "Example",
"last_name": "User",
"position": ""
},
{
"email": "[email protected]",
"first_name": "Foo",
"last_name": "Bar",
"position": ""
}
]
}
400: Bad Request
If an invalid request is provided, an error message will be returned
{
"message": "Group name not specified",
"success": false,
"data": null
}

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

{
"name": "Example Group",
"targets": [
{
"email": "[email protected]",
"first_name": "Example",
"last_name": "User",
"position": ""
},
{
"email": "[email protected]",
"first_name": "Foo",
"last_name": "Bar",
"position": ""
}
]
}

put
Modify Group

https://localhost:3333
/api/groups/:id
Modifies a group.
Request
Response
Path Parameters
id
required
integer
The group ID
Headers
Authorization
required
string
A valid API key
Body Parameters
Payload
required
object
The updated group content. The full group must be provided in JSON format.
200: OK
{
"id": 1,
"name": "Example Modified Group",
"modified_date": "2018-10-08T15:56:13.790016Z",
"targets": [
{
"email": "[email protected]",
"first_name": "Foo",
"last_name": "Bar",
"position": ""
}
]
}
404: Not Found
{
"message": "Group not found",
"success": false,
"data": null
}

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:

{
"id": 1,
"name": "Example Modified Go",
"targets": [
{
"email": "[email protected]",
"first_name": "Foo",
"last_name": "Bar",
"position": ""
}
]
}

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

delete
Delete Group

https://localhost:3333
/api/groups/:id
Deletes a group
Request
Response
Path Parameters
id
required
number
The group ID
Headers
Authorization
required
string
A valid API key
200: OK
{
"message": "Group deleted successfully!",
"success": true,
"data": null
}
404: Not Found
{
"message": "Group not found",
"success": false,
"data": null
}

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

post
Import Group

https://localhost:3333
/api/import/group
Reads and parses a CSV, returning data that can be used to create a group.
Request
Response
Headers
Authorization
required
string
A valid API key
Body Parameters
file
required
object
A file upload containing the CSV content to parse.
200: OK
[
{
"email": "[email protected]",
"first_name": "Example",
"last_name": "User",
"position": "Systems Administrator"
},
{
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"position": "CEO"
}
]

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 "[email protected]_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 endpoint.