Employee Management Workflow

Overview

This guide provides a complete walkthrough for adding employees and assigning them to groups using the NINJIO API v2.2.0. Employee management allows you to organize your workforce into logical groups for targeted training and phishing campaigns.

What You'll Accomplish

• Create new employee records in your NINJIO account
• Discover available groups within your organization
• Add employees to specific groups while preserving existing group memberships
• Verify successful employee assignment

Prerequisites

• Valid NINJIO API key with write permissions for Customer endpoints
• Basic understanding of REST API calls
• Employee information (first name, last name, email address)

---

Workflow Summary

Step	Action	Endpoint	Purpose
1	Create Employee	POST /customer/employees/	Add new employee to your account
2	Get All Groups	GET /customer/groups/	Discover available groups and their IDs
3	Get Single Group	GET /customer/groups/{group_id}/	View current employees in target group
4	Add Employee to Group	PUT /customer/groups/{group_id}/	Update group with new employee

Expected Outcome: Employee successfully created and added to designated group.

---

Step 1: Create Employee

Add a new employee record to your NINJIO account.

Endpoint: Create an Employee

Request

curl -X POST "https://apigw.goninjio.com/api/api_gateway/customer/employees/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@company.com"
  }'

Response

{
  "id": 12345,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@company.com",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Save the id value - you'll need this employee ID for Step 4.

Required Fields

• first_name (string) - Employee's first name
• last_name (string) - Employee's last name
• email (string) - Employee's email address (must be unique)

---

Step 2: Get All Groups

Retrieve a list of all groups in your account to identify which group you want to add the employee to.

Endpoint: Get All Groups

Request

curl -X GET "https://apigw.goninjio.com/api/api_gateway/customer/groups/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 101,
      "name": "Sales Team",
      "description": "All sales department employees",
      "employee_count": 25
    },
    {
      "id": 102,
      "name": "Engineering",
      "description": "Software development team",
      "employee_count": 40
    },
    {
      "id": 103,
      "name": "Management",
      "description": "Leadership and executives",
      "employee_count": 8
    }
  ]
}

Identify the target group - Note the id of the group where you want to add the employee (e.g., 102 for "Engineering").

---

Step 3: Get Single Group Details

Before adding an employee to a group, you must retrieve the current list of employees in that group. This is critical because the PUT request in Step 4 will replace the entire employee list.

Endpoint: Get Single Group

Request

curl -X GET "https://apigw.goninjio.com/api/api_gateway/customer/groups/102/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Response

{
  "id": 102,
  "name": "Engineering",
  "description": "Software development team",
  "employee_count": 40,
  "employees": [
    {
      "id": 201,
      "first_name": "Alice",
      "last_name": "Smith",
      "email": "alice.smith@company.com"
    },
    {
      "id": 202,
      "first_name": "Bob",
      "last_name": "Johnson",
      "email": "bob.johnson@company.com"
    },
    {
      "id": 203,
      "first_name": "Carol",
      "last_name": "Williams",
      "email": "carol.williams@company.com"
    }
  ]
}

Important: Save the entire list of employee IDs ([201, 202, 203]) - you'll need to include ALL of these IDs plus the new employee ID in Step 4.

---

Step 4: Add Employee to Group

Update the group to include your new employee. You must provide the complete list of employee IDs, including all existing employees plus the new one.

Endpoint: Update a Group

Request

curl -X PUT "https://apigw.goninjio.com/api/api_gateway/customer/groups/102/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_ids": [201, 202, 203, 12345]
  }'

Critical: The employee_ids array must include:

• All existing employee IDs from Step 3: [201, 202, 203]
• Plus the new employee ID from Step 1: 12345

If you only send [12345], all other employees will be removed from the group.

Response

{
  "id": 102,
  "name": "Engineering",
  "description": "Software development team",
  "employee_count": 41,
  "employees": [
    {
      "id": 201,
      "first_name": "Alice",
      "last_name": "Smith",
      "email": "alice.smith@company.com"
    },
    {
      "id": 202,
      "first_name": "Bob",
      "last_name": "Johnson",
      "email": "bob.johnson@company.com"
    },
    {
      "id": 203,
      "first_name": "Carol",
      "last_name": "Williams",
      "email": "carol.williams@company.com"
    },
    {
      "id": 12345,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@company.com"
    }
  ]
}

Success! The employee count increased from 40 to 41, and John Doe now appears in the employees array.

---

Complete End-to-End Example

Here's a complete workflow combining all steps:

# Step 1: Create Employee
EMPLOYEE_RESPONSE=$(curl -X POST "https://apigw.goninjio.com/api/api_gateway/customer/employees/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@company.com"
  }')

# Extract employee ID (using jq)
NEW_EMPLOYEE_ID=$(echo $EMPLOYEE_RESPONSE | jq -r '.id')
echo "Created employee with ID: $NEW_EMPLOYEE_ID"

# Step 2: Get All Groups (to find target group ID)
curl -X GET "https://apigw.goninjio.com/api/api_gateway/customer/groups/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

# Step 3: Get Current Employees in Target Group
GROUP_ID=102
GROUP_RESPONSE=$(curl -X GET "https://apigw.goninjio.com/api/api_gateway/customer/groups/${GROUP_ID}/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json")

# Extract existing employee IDs (using jq)
EXISTING_IDS=$(echo $GROUP_RESPONSE | jq -r '[.employees[].id]')
echo "Existing employee IDs: $EXISTING_IDS"

# Step 4: Add new employee to group (preserving existing employees)
# Manually construct the array: [201, 202, 203, 12345]
curl -X PUT "https://apigw.goninjio.com/api/api_gateway/customer/groups/${GROUP_ID}/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_ids": [201, 202, 203, 12345]
  }'

---

Troubleshooting

Issue	Possible Cause	Solution
"Email already exists" error	Employee with this email already registered	Use GET /employees/ to find existing employee ID
All existing employees removed from group	Only sent new employee ID in PUT request	Always include ALL employee IDs (existing + new)
"Group not found" error	Invalid group ID	Verify group ID using GET /groups/
401 Unauthorized	Invalid API key or insufficient permissions	Check API key has write permissions for Customer endpoints
"Invalid employee_ids" error	Employee ID doesn't exist	Verify employee was created successfully in Step 1

---

Important Notes

Group Updates Replace, Not Append

The PUT endpoint for updating groups replaces the entire employee list. It does not append to the existing list.

Wrong Approach:

{
  "employee_ids": [12345]  // ❌ This will remove all other employees!
}

Correct Approach:

{
  "employee_ids": [201, 202, 203, 12345]  // ✅ Preserves existing + adds new
}

Alternative: Multiple Groups

Employees can belong to multiple groups. To add an employee to multiple groups:

1. Create the employee once (Step 1)
2. For each target group:
   • Get the group's current employees (Step 3)
   • Update with existing IDs + new employee ID (Step 4)

Removing Employees from Groups

To remove an employee from a group, send a PUT request with employee_ids that excludes the employee you want to remove:

# Current group has: [201, 202, 203, 12345]
# To remove employee 12345, send only: [201, 202, 203]

curl -X PUT "https://apigw.goninjio.com/api/api_gateway/customer/groups/102/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_ids": [201, 202, 203]
  }'

---

Next Steps

Now that your employees are organized into groups, you can:

• Create Training Campaigns targeting specific groups
• Launch phishing simulations for different departments
• Generate reports filtered by group membership
• Manage group-level permissions and settings