Creating a Campaign

Overview

This guide provides a complete walkthrough for creating training campaigns using the NINJIO API v2.2.0. Training campaigns allow you to organize and deliver security awareness content to targeted groups of employees within your organization.

What You'll Accomplish

• Create a campaign container to organize your training initiatives
• Configure training simulations with specific content and targeting
• Automatically activate campaigns and begin content delivery to employees
• Verify successful deployment and monitor campaign status

Prerequisites

• Valid NINJIO API key
• Access to customer accounts with training permissions
• Basic understanding of REST API calls

---

Workflow Summary

Step	Action	Endpoint	Purpose
1	Discover Resources	Multiple GET endpoints	Gather template, employee, and group IDs
2	Create Campaign	POST /campaigns/training/	Create campaign container
3	Create Simulation	POST /simulations/training/	Link content to campaign with targeting
4	Activate Campaign	PUT /campaigns/training/{id}	Manually set campaign to active
5	Verify Deployment	GET /campaigns/training/{id}	Confirm campaign is active

Expected Outcome: Active training campaign delivering content to targeted employees.

---

Step 1: Resource Discovery

Before creating campaigns, collect the required IDs for templates, employees, and groups.

1.1 Training Templates

Discover available training content templates.

Endpoint: Get All Training Templates

curl -X GET "https://api.ninjio.com/api/api_gateway/customer/templates/training/" \
  -H "apiKey: YOUR_API_KEY"

Key Fields: Save id values for use in simulation creation.

1.2 Email Templates

Discover available email delivery templates.

Endpoint: Get All Email Templates

curl -X GET "https://api.ninjio.com/api/api_gateway/customer/templates/email/" \
  -H "apiKey: YOUR_API_KEY"

Key Fields: Save id values - email templates are required for simulation creation and newly available in this API version.

1.3 Employee and Group Targeting

Discover available targeting options for content delivery.

Endpoints:

• Get Customer Employees
• Get All Customer Groups

# Get employees for individual targeting
curl -X GET "https://api.ninjio.com/api/api_gateway/customer/employees/" \
  -H "apiKey: YOUR_API_KEY"

# Get groups for bulk targeting
curl -X GET "https://api.ninjio.com/api/api_gateway/customer/groups/" \
  -H "apiKey: YOUR_API_KEY"

Key Fields: Save employee id values and group id values for targeting.

---

Step 2: Campaign Creation

Create the campaign container that will organize your training initiatives.

Endpoint: Creating a Campaign

curl -X POST "https://api.ninjio.com/api/api_gateway/customer/campaigns/training/" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2024 Security Awareness Campaign",
    "start_date": "2024-01-01",
    "end_date": "2024-03-31",
    "close_campaign_after_end": true
  }'

Expected Response

{
  "id": 123,
  "name": "Q1 2024 Security Awareness Campaign",
  "status": "inactive"
}

Important: Save the campaign_id (123) for the next step. The campaign starts as "inactive" until simulations are added.

---

Step 3: Training Simulation Creation & Targeting

Create training simulations that automatically link to your campaign and deliver content to targeted employees.

Endpoint: Create a New Training Simulation

Request Structure

curl -X POST "https://api.ninjio.com/api/api_gateway/customer/simulations/training/" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": 123,                    // From Step 2 campaign creation
    "name": "Security Awareness Training - Module 1",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "email_template_id": 8602,             // From Step 1.2 email templates
    "training_template_id": 59,            // From Step 1.1 training templates
    "target_employees": [1, 2, 3, 4, 5],   // From Step 1.3 employee discovery
    "target_groups": [1, 2],               // From Step 1.3 group discovery
    "target_dyn_groups": [],
    "batch_size": 50,
    "time_start": "08:00:00",
    "time_end": "17:00:00",
    "weekdays": ["mon", "tue", "wed", "thu", "fri"],
    "ssl": true,
    "schedule_and_start": false
  }'

Key Parameters

Parameter	Type	Required	Description
campaign_id	integer	Yes	Links simulation to campaign (from Step 2)
email_template_id	integer	Yes	Template for email delivery (from Step 1.2)
training_template_id	integer	No	Training content template (from Step 1.1)
target_employees	array	No	Individual employee IDs to target
target_groups	array	No	Group IDs for bulk targeting
target_dyn_groups	array	No	Dynamic group IDs for rule-based targeting

Expected Response

{
  "simulation_id": 456,
  "name": "Security Awareness Training - Module 1",
  "campaign_id": 123,
  "status": "created"
}

---

Step 4: Campaign Activation

After creating simulations, manually activate the campaign to begin content delivery.

Endpoint: Update Training Campaign Status

curl -X PUT "https://api.ninjio.com/api/api_gateway/customer/campaigns/training/123/" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active"
  }'

Expected Response

{
  "campaign_id": 123,
  "status": "active",
  "message": "Campaign status updated successfully"
}

Status Options:

• "active" - Start content delivery to targeted employees
• "inactive" - Pause content delivery
• "paused" - Temporarily halt delivery

---

Step 5: Verification & Monitoring

Verify that your campaign is active and properly configured.

5.1 Verify Campaign Status

Endpoint: Get Single Training Campaign

curl -X GET "https://api.ninjio.com/api/api_gateway/customer/campaigns/training/123/" \
  -H "apiKey: YOUR_API_KEY"

Expected Response:

{
  "campaign_id": 123,
  "campaign_name": "Q1 2024 Security Awareness Campaign",
  "status": 1,
  "start_date": "2024-01-01",
  "end_date": "2024-03-31"
}

Status Values:

• 0 = Inactive
• 1 = Active (content being delivered)
• 100 = Complete (campaign finished)

5.2 Review Simulation Details

Endpoint: Get Single Training Simulation

curl -X GET "https://api.ninjio.com/api/api_gateway/customer/simulations/training/456/" \
  -H "apiKey: YOUR_API_KEY"

This provides detailed information about targeting, progress, and employee participation.

---

Complete Implementation Example

End-to-End Workflow

# Step 1: Create campaign container
curl -X POST "https://api.ninjio.com/api/api_gateway/customer/campaigns/training/" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2024 Security Awareness Campaign",
    "start_date": "2024-01-01",
    "end_date": "2024-03-31",
    "close_campaign_after_end": true
  }'
# Returns: {"id": 123, "status": "inactive"}

# Step 2: Create simulation with targeting and campaign linking
curl -X POST "https://api.ninjio.com/api/api_gateway/customer/simulations/training/" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": 123,
    "name": "Security Awareness Training - Module 1",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "email_template_id": 8602,
    "training_template_id": 59,
    "target_employees": [1, 2, 3, 4, 5],
    "target_groups": [1],
    "batch_size": 50,
    "schedule_and_start": false
  }'
# Returns: {"simulation_id": 456, "campaign_id": 123, "status": "created"}

# Step 3: Activate campaign to begin content delivery
curl -X PUT "https://api.ninjio.com/api/api_gateway/customer/campaigns/training/123/" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active"
  }'
# Returns: {"campaign_id": 123, "status": "active", "message": "Campaign status updated successfully"}

# Step 4: Verify campaign is active and delivering content
curl -X GET "https://api.ninjio.com/api/api_gateway/customer/campaigns/training/123/" \
  -H "apiKey: YOUR_API_KEY"
# Returns: {"campaign_id": 123, "status": 1} // 1 = Active

---

Troubleshooting

Common Issues

Issue	Cause	Solution
Campaign stays inactive	No simulations created	Create at least one simulation with campaign_id
Invalid template error	Template ID doesn't exist	Use discovery endpoints to get valid template IDs
Targeting error	Employee/group IDs invalid	Verify employee and group IDs exist in your account
Permission error	API key lacks permissions	Ensure API key has training administration permissions

Validation Checklist

• ✅ API key has training permissions
• ✅ Template IDs exist and are accessible
• ✅ Employee IDs are valid and active
• ✅ Group IDs are valid and contain employees
• ✅ Campaign dates are logical (start < end)
• ✅ Simulation dates fall within campaign period

---

Next Steps

Once your campaign is active:

1. Monitor Progress: Use simulation endpoints to track employee participation
2. Add More Content: Create additional simulations linked to the same campaign
3. Generate Reports: Use reporting endpoints to analyze campaign effectiveness
4. Scale Targeting: Leverage dynamic groups for automated employee targeting

For detailed API reference, explore the individual endpoint documentation linked throughout this guide.