Employees & Groups

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

{
  "id"            : int64,
  "user_id"       : int64,
  "name"          : string,
  "modified_date" : string(datetime),
  "targets"       : []Target,
  "customer_id"   : int64
}

Each recipient in the targets field has the following format:

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

Get Groups

GET /api/groups/

Returns a list of groups.

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

{
    "id": 1,
    "user_id": 64,
    "name": "Example Group",
    "modified_date": "2018-10-08T15:56:13.790016Z",
    "targets": [
      {
        "id": 84,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "created_date": "YYYY-MM-DD",
        "services_used": null,
        "domain_verified": false,
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "manager": "",
        "canal": "",
        "language": "",
        "departement": ""
      },
      {
        "id": 85,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "created_date": "YYYY-MM-DD",
        "services_used": null,
        "domain_verified": false,
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "manager": "",
        "canal": "",
        "language": "",
        "departement": ""
      }
    ],
    "customerId": 138,
    "external_id": "",
    "filters": [],
    "nb_targets": 0
  }

Get Group

GET /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

200

{
    "id": 1,
    "user_id": 64,
    "name": "Example Group",
    "modified_date": "2018-10-08T15:56:13.790016Z",
    "targets": [
      {
        "id": 84,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "created_date": "YYYY-MM-DD",
        "services_used": null,
        "domain_verified": false,
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "manager": "",
        "canal": "",
        "language": "",
        "departement": ""
      },
      {
        "id": 85,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "created_date": "YYYY-MM-DD",
        "services_used": null,
        "domain_verified": false,
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "manager": "",
        "canal": "",
        "language": "",
        "departement": ""
      }
    ],
    "customerId": 138,
    "external_id": "",
    "filters": [],
    "nb_targets": 0
  }

404

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

Get Groups Summary

GET /api/groups/summary

Returns a summary of each group.

Headers

Name	Type	Description
Authorization*	string	A valid API key

200

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

Get Group Summary

GET /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

200

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

404

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

POST /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.

201

{
    "user_id": 64,
    "name": "Example Group",
    "modified_date": "2018-10-08T15:56:13.790016Z",
    "targets": [
      {
        "id": 84,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "created_date": "YYYY-MM-DD",
        "services_used": null,
        "domain_verified": false,
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "manager": "",
        "canal": "",
        "language": "",
        "departement": ""
      },
      {
        "id": 85,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "created_date": "YYYY-MM-DD",
        "services_used": null,
        "domain_verified": false,
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "manager": "",
        "canal": "",
        "language": "",
        "departement": ""
      }
    ],
    "customerId": 138,
    "external_id": "",
    "filters": [],
    "nb_targets": 0
  }

400

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": [
    {
        "id": 84,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "language": "",
      },
    {
        "id": 85,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "email": "[email protected]",
        "first_name": "Example2",
        "last_name": "USER2",
        "position": "",
        "language": "",
      }
    ]
}

Modify Group

PUT /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.

200

  {
    "id": 1,
    "user_id": 64,
    "name": "Example Group",
    "modified_date": "2018-10-08T15:56:13.790016Z",
    "targets": [
      {
        "id": 84,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "language": "",
      },
      {
        "id": 85,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "email": "[email protected]",
        "first_name": "Example2",
        "last_name": "USER2",
        "position": "",
        "language": "",
      }
    ],
    "Customer": {},
    "customerId": 138,
    "external_id": "",
  }

404

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": [
    {
        "id": 84,
        "Customer": {},
        "customerId": 0,
        "bashImportId": 0,
        "userId": 0,
        "statusLicence": "",
        "external_id": "",
        "keycloack_id": "",
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "USER",
        "position": "",
        "language": "",
      },
    ]
}

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

Delete Group

DELETE /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

200

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

404

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

Import Group

POST /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.

200

  {
    "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 "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 endpoint.