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 notes https //developer knowbe4 com/rest/reporting#tag/introduction 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 path parameters policy id number required parameters for the get a specific policy action input example {"path parameters" {"policy id" 12345}} 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 output 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 path parameters campaign id number required parameters for the get a specific training campaign action input example {"path parameters" {"campaign id" 12345}} 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 groups group id number unique identifier groups name string name of the resource status string status value content array response content content 0 object response content content 0 store purchase id number unique identifier content 0 content type string type of the resource content 0 name string name of the resource content 0 description string response content content 0 type string type of the resource content 0 duration number response content content 0 retired boolean response content content 0 retirement date object response content content 0 publish date string response content content 0 publisher string response content content 0 purchase date string response content content 0 policy url string url endpoint for the request content 1 object response content content 1 policy id number unique identifier content 1 content type string type of the resource output 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 parameters include campaign id boolean optional returns the campaign id for each training enrollment path parameters enrollment id number required parameters for the get a specific training enrollment action input example {"parameters" {"include campaign id"\ true},"path parameters" {"enrollment id" 12345}} 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 user id number unique identifier user first name string name of the resource user last name string name of the resource user email string output field user email user employee number number output field user 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 output 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" {"id" 796742,"first name" "sarah","last name" "thomas","email" "s thomas\@kb4 demo com","employee number" 123456},"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" "pass 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 parameters 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 input example {"parameters" {"full"\ true}} 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 output 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 input example {"path parameters" {},"parameters" {},"data body" {},"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 output 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 parameters 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 input example {"parameters" {"exclude percentages"\ false}} 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 groups group id number unique identifier groups name string name of the resource status string status value content array response content content 0 object response content content 0 store purchase id number unique identifier content 0 content type string type of the resource content 0 name string name of the resource content 0 description string response content content 0 type string type of the resource content 0 duration number response content content 0 retired boolean response content content 0 retirement date object response content content 0 publish date string response content content 0 publisher string response content content 0 purchase date string response content content 0 policy url string url endpoint for the request content 1 object response content content 1 policy id number unique identifier content 1 content type string type of the resource output 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 parameters store purchase id number optional returns a list of all training enrollments filtered by module parameters 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 parameters user id number optional returns a list of all training enrollments filtered by a user parameters exclude archived users boolean optional excludes archived users when returning a list of training enrollments parameters include campaign id boolean optional returns the campaign id for each training enrollment parameters include store purchase id boolean optional returns the store purchase id for each training enrollment parameters include employee number boolean optional returns the employee number for each training enrollment input example {"parameters" {"store purchase id" 12345,"campaign id" 67890,"user id" 54321,"exclude archived users"\ true,"include campaign id"\ true,"include store purchase id"\ true,"include employee number"\ true}} 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 user id number unique identifier user first name string name of the resource user last name string name of the resource user email string output field user email user employee number number output field user 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 output 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" {"id" 796742,"first name" "sarah","last name" "thomas","email" "s thomas\@kb4 demo com","employee number" 123456},"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" "pass response headers header description example content type the media type of the resource application/json