Start phishing simulation for a customer

As a Reseller you can create a phishing campaign for a customer and immediately start it so the simulation emails go out to target users. The flow: get the customer's Company ID, pick a scenario and target group, create the campaign, then start the campaign job. Use a credential with Client Role = Reseller. Send X-KEEPNET-Company-Id with every request.

---

POST /api/companies/search

Get the customer's Company ID first. Use the resourceId from the response as X-KEEPNET-Company-Id in all subsequent requests. Test it: Authorize with Client ID/Secret, then Send — request body is pre-filled.

Retrieves a list of all companies

post

Required scopes

This endpoint requires the following scopes:

• : API

Authorizations

oauth2bearerAuth

OAuth2clientCredentialsRequired

Client ID and Client Secret from Company → Company Settings → REST API. Enter credentials to auto-fetch token.

Token URL:

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

pageNumberintegerRequiredExample: 1

pageSizeintegerRequiredExample: 10

orderBystringRequiredExample: CreateTime

ascendingbooleanRequiredExample: false

isTargetUserCountExceededLimitbooleanOptional

If true, only companies exceeding license limit are returned

Example: false

Responses

200

OK

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/companies/search

HTTPcURLJavaScriptPython

POST /api/companies/search HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 126

{
  "pageNumber": 1,
  "pageSize": 10,
  "orderBy": "CreateTime",
  "ascending": false,
  "filter": {
    "Condition": "AND",
    "SearchInputTextValue": ""
  }
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

OK

{
  "data": {
    "limitExceededCompanyCount": 1,
    "pageNumber": 1,
    "pageSize": 1,
    "totalNumberOfPages": 1,
    "totalNumberOfRecords": 1,
    "results": [
      {
        "companyName": "text",
        "companyResourceId": "text",
        "resellerName": "text",
        "industryName": "text",
        "industryResourceId": "text",
        "licenseTypeName": "text",
        "licenseTypeResourceId": "text",
        "isNumberOfUsersLimited": true,
        "numberOfUsers": "text",
        "privacyDurationId": 1,
        "licenceExpired": true,
        "licenseEndDate": "2026-03-09T13:45:31.894Z",
        "createTime": "2026-03-09T13:45:31.894Z",
        "targetUserCount": 1,
        "children": [
          {
            "companyName": "text",
            "companyResourceId": "text",
            "resellerName": "text",
            "industryName": "text",
            "industryResourceId": "text",
            "licenseTypeName": "text",
            "licenseTypeResourceId": "text",
            "isNumberOfUsersLimited": true,
            "numberOfUsers": "text",
            "privacyDurationId": 1,
            "licenceExpired": true,
            "licenseEndDate": "2026-03-09T13:45:31.894Z",
            "createTime": "2026-03-09T13:45:31.894Z",
            "targetUserCount": 1,
            "children": "[Circular Reference]",
            "tags": [
              "text"
            ],
            "deletedTargetUserCount": 1,
            "inactiveTargetUserCount": 1,
            "monthlyActiveUserCount": 1
          }
        ],
        "tags": [
          "text"
        ],
        "deletedTargetUserCount": 1,
        "inactiveTargetUserCount": 1,
        "monthlyActiveUserCount": 1
      }
    ]
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

---

POST /api/phishing-simulator/phishing-scenario/search

List phishing scenarios available for the customer. Send X-KEEPNET-Company-Id. Pick a scenario and note its resourceId — use it as phishingScenarioResourceIds in the campaign body.

Returns a list of the phishing scenarios

post

Required scopes

This endpoint requires the following scopes:

• : API

Authorizations

oauth2bearerAuth

OAuth2clientCredentialsRequired

Client ID and Client Secret from Company → Company Settings → REST API. Enter credentials to auto-fetch token.

Token URL:

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

pageNumberintegerRequiredExample: 1

pageSizeintegerRequiredExample: 20

orderBystringOptionalExample: Name

ascendingbooleanOptionalExample: true

Responses

200

OK

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/phishing-simulator/phishing-scenario/search

HTTPcURLJavaScriptPython

POST /api/phishing-simulator/phishing-scenario/search HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 119

{
  "pageNumber": 1,
  "pageSize": 20,
  "orderBy": "Name",
  "ascending": true,
  "filter": {
    "Condition": "AND",
    "SearchInputTextValue": ""
  }
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

OK

{
  "data": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalNumberOfPages": 1,
    "totalNumberOfRecords": 1,
    "results": [
      {
        "resourceId": "text",
        "name": "text",
        "quishingType": "text",
        "method": "text",
        "difficulty": "text",
        "category": "text",
        "languageTypeName": [
          "text"
        ],
        "languageTypeCode": [
          "text"
        ],
        "tags": [
          "text"
        ],
        "isOwner": true,
        "isSelected": true,
        "createdBy": "text",
        "createTime": "2026-03-09T13:45:31.894Z",
        "roles": [
          {
            "name": "text"
          }
        ]
      }
    ]
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

---

POST /api/target-groups/search/current-company

List target groups for the customer. Send X-KEEPNET-Company-Id. Use one or more resourceId values as targetGroupResourceIds in the campaign body.

Returns a list of target groups for my company

post

Required scopes

This endpoint requires the following scopes:

• : API

Authorizations

oauth2bearerAuth

OAuth2clientCredentialsRequired

Client ID and Client Secret from Company → Company Settings → REST API. Enter credentials to auto-fetch token.

Token URL:

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

pageNumberintegerRequiredExample: 1

pageSizeintegerRequiredExample: 20

orderBystringOptionalExample: Name

ascendingbooleanOptionalExample: true

Responses

200

OK

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/target-groups/search/current-company

HTTPcURLJavaScriptPython

POST /api/target-groups/search/current-company HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 139

{
  "pageNumber": 1,
  "pageSize": 20,
  "orderBy": "Name",
  "ascending": true,
  "filter": {
    "condition": "and",
    "searchInputTextValue": null,
    "filterGroups": []
  }
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

OK

{
  "data": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalNumberOfPages": 1,
    "totalNumberOfRecords": 1,
    "results": [
      {
        "resourceId": "text",
        "name": "text",
        "companyName": "text",
        "userCount": 1,
        "priority": "text",
        "createTime": "2026-03-09T13:45:31.894Z",
        "updateTime": "2026-03-09T13:45:31.894Z"
      }
    ]
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

---

GET /api/phishing-simulator/phishing-campaign/form-details

Returns dropdown and reference data (email delivery settings, schedule types, etc.) needed to build the campaign. Send X-KEEPNET-Company-Id.

Retrieves the create/edit form details

get

Required scopes

This endpoint requires the following scopes:

• : API

Authorizations

oauth2bearerAuth

OAuth2clientCredentialsRequired

Client ID and Client Secret from Company → Company Settings → REST API. Enter credentials to auto-fetch token.

Token URL:

Responses

200

OK

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

get

/api/phishing-simulator/phishing-campaign/form-details

HTTPcURLJavaScriptPython

GET /api/phishing-simulator/phishing-campaign/form-details HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

OK

{
  "data": {
    "distributionEmailOverTimeTypes": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ],
    "distributionSmtpDelayTimeTypes": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ],
    "phishingCampaignCategoryDistributionType": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ],
    "distributionTypes": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ],
    "scheduleTypes": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ],
    "sendRandomlyUsersCalculateTypes": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ],
    "status": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ],
    "categories": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ],
    "sendUserPreferredLanguageTypes": [
      {
        "text": "text",
        "value": "text",
        "extraDatas": [
          {
            "text": "text",
            "value": "text",
            "extraDatas": "[Circular Reference]"
          }
        ]
      }
    ]
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

---

POST /api/phishing-simulator/phishing-campaign

Creates a new phishing campaign for the customer. Send X-KEEPNET-Company-Id. Body: name (required), scheduleTypeId (required), phishingScenarioResourceIds, targetGroupResourceIds, duration, distribution, and email delivery settings. See Endpoints → PhishingCampaign for the full schema.

Creates a new phishing campaign for a company

post

Required scopes

This endpoint requires the following scopes:

• : API

Authorizations

oauth2bearerAuth

OAuth2clientCredentialsRequired

Client ID and Client Secret from Company → Company Settings → REST API. Enter credentials to auto-fetch token.

Token URL:

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

namestringRequiredExample: Q1 Phishing Simulation

scheduleTypeIdintegerRequiredExample: 1

phishingScenarioResourceIdsstring[]Optional

targetGroupResourceIdsstring[]Optional

durationintegerOptionalExample: 7

distributionTypeIdintegerOptionalExample: 1

distributionDelayEveryintegerOptionalExample: 0

distributionDelayTimeTypeIdintegerOptionalExample: 1

sendingLimitintegerOptionalExample: 0

emailDeliverySettingTypeintegerOptionalExample: 1

excludeFromReportsbooleanOptionalExample: false

sendOnlyActiveUsersbooleanOptionalExample: true

Responses

200

OK

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/phishing-simulator/phishing-campaign

HTTPcURLJavaScriptPython

POST /api/phishing-simulator/phishing-campaign HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 355

{
  "name": "Q1 Phishing Simulation",
  "scheduleTypeId": 1,
  "phishingScenarioResourceIds": [
    "<scenarioResourceId>"
  ],
  "targetGroupResourceIds": [
    "<targetGroupResourceId>"
  ],
  "duration": 7,
  "distributionTypeId": 1,
  "distributionDelayEvery": 0,
  "distributionDelayTimeTypeId": 1,
  "sendingLimit": 0,
  "emailDeliverySettingType": 1,
  "excludeFromReports": false,
  "sendOnlyActiveUsers": true
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

OK

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

Example body (minimal — send immediately):

{
  "name": "Q1 Phishing Simulation",
  "scheduleTypeId": 1,
  "phishingScenarioResourceIds": ["<scenarioResourceId>"],
  "targetGroupResourceIds": ["<targetGroupResourceId>"],
  "duration": 7,
  "distributionTypeId": 1,
  "distributionDelayEvery": 0,
  "distributionDelayTimeTypeId": 1,
  "sendingLimit": 0,
  "emailDeliverySettingType": 1,
  "excludeFromReports": false,
  "sendOnlyActiveUsers": true
}

From the response, note the campaign resourceId. Use it in the next step.

---

POST /api/phishing-simulator/phishing-campaign-job/start/{resourceId}

Starts the campaign — emails go out to target users. Replace {resourceId} with the campaign ID from the create response. Send X-KEEPNET-Company-Id. Body: scheduleTypeId, targetGroupResourceIds, and optional distribution config.

Start new phishing campaign job with phishing campaign resource id.

post

Required scopes

This endpoint requires the following scopes:

• : API

Authorizations

oauth2bearerAuth

OAuth2clientCredentialsRequired

Client ID and Client Secret from Company → Company Settings → REST API. Enter credentials to auto-fetch token.

Token URL:

Path parameters

resourceIdstringRequired

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

scheduleTypeIdintegerOptionalExample: 1

targetGroupResourceIdsstring[]Optional

excludeFromReportsbooleanOptionalExample: false

sendingLimitintegerOptionalExample: 0

distributionDelayEveryintegerOptionalExample: 0

distributionDelayTimeTypeIdintegerOptionalExample: 1

useTargetUserTimeZonebooleanOptionalExample: false

Responses

200

OK

application/json

statusstringOptional

messagestring · nullableOptional

validationMessagesstring[] · nullableOptional

post

/api/phishing-simulator/phishing-campaign-job/start/{resourceId}

HTTPcURLJavaScriptPython

POST /api/phishing-simulator/phishing-campaign-job/start/{resourceId} HTTP/1.1
Host: api.keepnetlabs.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 206

{
  "scheduleTypeId": 1,
  "targetGroupResourceIds": [
    "<targetGroupResourceId>"
  ],
  "excludeFromReports": false,
  "sendingLimit": 0,
  "distributionDelayEvery": 0,
  "distributionDelayTimeTypeId": 1,
  "useTargetUserTimeZone": false
}

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

200

OK

{
  "data": {
    "resourceId": "text"
  },
  "status": "text",
  "message": "text",
  "validationMessages": [
    "text"
  ]
}

Example body (start immediately):

{
  "scheduleTypeId": 1,
  "targetGroupResourceIds": ["<targetGroupResourceId>"],
  "excludeFromReports": false,
  "sendingLimit": 0,
  "distributionDelayEvery": 0,
  "distributionDelayTimeTypeId": 1,
  "useTargetUserTimeZone": false
}

---

Common errors

• 403 Forbidden — Credential is not Reseller, or the Company ID is not one you manage. Set Client Role = Reseller. Roles and permissions →

• 401 Unauthorized — Missing or invalid token. Request a new token via POST /connect/token.

• 400 Bad Request — Invalid request body (missing scenario, target group, or schedule). Verify IDs from the search endpoints above; check Endpoints → PhishingCampaign for the full schema.

• 404 Not Found — Invalid Company ID, scenario ID, or campaign ID.

Platform UI: Create phishing campaigns under Phishing Simulator → Campaign Manager. Campaign Manager →

Related: Create and start phishing campaign for a customer → (compact version). List phishing scenarios for a customer →. View customer's campaign list and report →. Scope API requests to a customer →.