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

KnowBe4 API Documentation

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":"[email protected]","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

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

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

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json