KnowBe4 API

the knowbe4 api connector allows for automated interactions with knowbe4's security awareness training platform, enabling streamlined management of training campaigns and policy enforcement knowbe4 is a platform specializing in security awareness training and simulated phishing the knowbe4 api connector for swimlane turbine allows users to automate the retrieval and management of security policies, training campaigns, and enrollment data by integrating with knowbe4, swimlane turbine users can enhance their security posture through streamlined access to risk scores, policy details, and training effectiveness, directly within their security workflows this connector empowers organizations to proactively manage employee security awareness and reduce the risk of social engineering attacks limitations none to date prerequisites to effectively utilize the knowbe4 api connector with swimlane turbine, ensure you have the following prerequisites http bearer authentication with the following parameters url endpoint for the knowbe4 api token a valid bearer token to authenticate api requests capabilities this connector provides the following capabilities get a specific policy get a specific training campaign get a specific training enrollment get account risk score history get all policies get all training campaigns get all training enrollments configurations http bearer authentication authenticates using bearer token such as a jwt, etc configuration parameters parameter description type required url a url to the target host string required token jwt token string required actions get a specific policy retrieves a specific policy using its unique id from your knowbe4 account endpoint url /v1/training/policies/{{policy id}} method get input argument name type required description policy id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase policy id number unique identifier content type string type of the resource name string name of the resource minimum time number time value default language string output field default language status number status value example \[ { "status code" 200, "response headers" { "content type" "application/json" }, "reason" "ok", "json body" { "policy id" 2420, "content type" "uploaded policy", "name" "physical security policy", "minimum time" 3, "default language" "en us", "status" 1 } } ] get a specific training campaign retrieves a specific training campaign by campaign id from your knowbe4 account endpoint url /v1/training/campaigns/{{campaign id}} method get input argument name type required description campaign id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase campaign id number unique identifier name string name of the resource groups array output field groups group id number unique identifier name string name of the resource status string status value content array response content 0 object output field 0 store purchase id number unique identifier content type string type of the resource name string name of the resource description string output field description type string type of the resource duration number output field duration retired boolean output field retired retirement date object date value publish date string date value publisher string output field publisher purchase date string date value policy url string url endpoint for the request 1 object output field 1 policy id number unique identifier content type string type of the resource example \[ { "status code" 200, "response headers" { "content type" "application/json" }, "reason" "ok", "json body" { "campaign id" 4261, "name" "annual training", "groups" \[], "status" "completed", "content" \[], "duration type" "specific end date", "start date" "2019 04 02t15 02 38 000z", "end date" "2019 04 02t15 02 38 000z", "relative duration" "string", "auto enroll" true, "allow multiple enrollments" false, "completion percentage" 0 } } ] get a specific training enrollment retrieves a specific training enrollment identified by an enrollment id from your knowbe4 account endpoint url /v1/training/enrollments/{{enrollment id}} method get input argument name type required description include campaign id boolean optional returns the campaign id for each training enrollment enrollment id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase enrollment id number unique identifier content type string type of the resource module name string name of the resource user object output field user id number unique identifier first name string name of the resource last name string name of the resource email string output field email employee number number output field employee number campaign name string name of the resource enrollment date string date value start date string date value completion date string date value status string status value time spent number output field time spent policy acknowledged boolean output field policy acknowledged example \[ { "status code" 200, "response headers" { "content type" "application/json" }, "reason" "ok", "json body" { "enrollment id" 1425526, "content type" "uploaded policy", "module name" "acceptable use policy", "user" {}, "campaign name" "new employee policies", "enrollment date" "2019 04 02t15 02 38 000z", "start date" "2019 04 02t15 02 38 000z", "completion date" "2019 04 02t15 02 38 000z", "status" "passed", "time spent" 2340, "policy acknowledged" false } } ] get account risk score history retrieve the historical risk score data for your knowbe4 account endpoint url /v1/account/risk score history method get input argument name type required description full boolean optional include the entire risk score history of your organization if this parameter isn't used, six months of data will show by default output parameter type description status code number http status code of the response reason string response reason phrase risk score number score value date string date value example \[ { "status code" 200, "response headers" { "content type" "application/json" }, "reason" "ok", "json body" { "risk score" 37 3, "date" "2021 02 07" } } ] get all policies retrieves a list of all policies uploaded to your knowbe4 account, providing an overview of account policy settings endpoint url /v1/training/policies method get input argument name type required description data body object optional data body headers object optional request headers output parameter type description status code number http status code of the response reason string response reason phrase policy id number unique identifier content type string type of the resource name string name of the resource minimum time number time value default language string output field default language status number status value example \[ { "status code" 200, "response headers" { "content type" "application/json" }, "reason" "ok", "json body" { "policy id" 2420, "content type" "uploaded policy", "name" "physical security policy", "minimum time" 3, "default language" "en us", "status" 1 } } ] get all training campaigns retrieves a comprehensive list of all training campaigns available in your knowbe4 account endpoint url /v1/training/campaigns method get input argument name type required description exclude percentages boolean optional excludes the completion percentage field from the response to greatly speed up response time if this parameter is set to anything other than true, the response limit will be set to 10 output parameter type description status code number http status code of the response reason string response reason phrase campaign id number unique identifier name string name of the resource groups array output field groups group id number unique identifier name string name of the resource status string status value content array response content 0 object output field 0 store purchase id number unique identifier content type string type of the resource name string name of the resource description string output field description type string type of the resource duration number output field duration retired boolean output field retired retirement date object date value publish date string date value publisher string output field publisher purchase date string date value policy url string url endpoint for the request 1 object output field 1 policy id number unique identifier content type string type of the resource example \[ { "status code" 200, "response headers" { "content type" "application/json" }, "reason" "ok", "json body" { "campaign id" 4261, "name" "annual training", "groups" \[], "status" "completed", "content" \[], "duration type" "specific end date", "start date" "2019 04 02t15 02 38 000z", "end date" "2019 04 02t15 02 38 000z", "relative duration" "string", "auto enroll" true, "allow multiple enrollments" false, "completion percentage" 0 } } ] get all training enrollments retrieve a comprehensive list of all training enrollments within your knowbe4 account endpoint url /v1/training/enrollments method get input argument name type required description store purchase id number optional returns a list of all training enrollments filtered by module campaign id number optional returns a list of all training enrollments filtered by a campaign, as indicated by the \[campaign id] if the show scores option is enabled for a training campaign, the scores will also be displayed in the api user id number optional returns a list of all training enrollments filtered by a user exclude archived users boolean optional excludes archived users when returning a list of training enrollments include campaign id boolean optional returns the campaign id for each training enrollment include store purchase id boolean optional returns the store purchase id for each training enrollment include employee number boolean optional returns the employee number for each training enrollment output parameter type description status code number http status code of the response reason string response reason phrase enrollment id number unique identifier content type string type of the resource module name string name of the resource user object output field user id number unique identifier first name string name of the resource last name string name of the resource email string output field email employee number number output field employee number campaign name string name of the resource enrollment date string date value start date string date value completion date string date value status string status value time spent number output field time spent policy acknowledged boolean output field policy acknowledged example \[ { "status code" 200, "response headers" { "content type" "application/json" }, "reason" "ok", "json body" { "enrollment id" 1425526, "content type" "uploaded policy", "module name" "acceptable use policy", "user" {}, "campaign name" "new employee policies", "enrollment date" "2019 04 02t15 02 38 000z", "start date" "2019 04 02t15 02 38 000z", "completion date" "2019 04 02t15 02 38 000z", "status" "passed", "time spent" 2340, "policy acknowledged" false } } ] response headers header description example content type the media type of the resource application/json notes knowbe4 api documentation https //developer knowbe4 com/rest/reporting#tag/introduction