CyberHoot API
Overview
The CyberHoot API is available to our partners. It is organized around REST, uses standard HTTP response codes, accepts form-encoded request bodies, and returns JSON-encoded responses.
Authentication
All API requests require a valid API Key. The Items API uses HTTP Basic Auth. Provide your API Key as the basic auth username value in the request Authentication header (You don’t need to provide a password). Your API Key can be found under MSP Settings in your CyberHoot deployment. You can also generate a new API Key here (Note this will make your current API Key invalid).
To authenticate to the Items API you must provide your API Key in the Basic Authorization header of your HTTP request. All API requests must be made over HTTPS. Calls made over HTTP will fail and API requests without authentication will also fail.
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/ \
-u <API_KEY>:
# The colon prevents curl from asking for a password.
# Replace <DEPLOYMENT_SUBDOMAIN> with your deployment subdomain
# Replace <API_KEY> with your API Key
Status Codes
The CyberHoot API utilizes the following HTTP Status Codes in its responses.
Status Code | Description |
|---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
Errors
The CyberHoot API returns errors in this format along with the corresponding HTTP Status Code.
{
"error" : string,
"error_description" : string
}
# error = short code of error(s) that occurred
# error description = details of error(s) that occurred
API Endpoints
Customers
Get Customers
Returns a list of customers.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/ |
Parameter | Required | Data Type | Details |
|---|---|---|---|
limit | Optional | Integer | Limit number of customers returned. Max of 1,000, default is 100. |
starting_after | Optional | Integer | Id of customer to start pulling customers after. Used for pagination. |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/ \
-u <API_KEY>: \
-d limit=10 \
-G
Get Customer
Returns a specific customer.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/?id=:id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/ \
-u <API_KEY>: \
-d id=1000 \
-G
Get Customer Security Awareness Rank
Returns the security awareness rank for a specific customer.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-rank/customer/customer-hoot-rank.php?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-ranks/customer/customer-hoot-rank.php \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Managers
Get Managers
Returns a list of managers.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/managers/ |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
limit | Optional | Integer | number of results to pull |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/managers/ \
-u <API_KEY>: \
-d customer_id=1000 \
-d limit=10 \
-G
Users
Get Users
Returns a list of users.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/ \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Get User
Returns a specific user.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/?customer_id=:customer_id&id=:id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
id | Required | Integer | id of the user |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/ \
-u <API_KEY>: \
-d customer_id=1000 \
-d id=1001 \
-G
Get User Security Awareness Rank
Returns security awareness rank for a specific user.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-ranks//user/user-hoot-rank.php?customer_id=:customer_id&user_id=:user_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
user_id | Required | Integer | id of the user |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-ranks/users/user-hoot-rank.php \
-u <API_KEY>: \
-d customer_id=1000 \
-d user_id=1001 \
-G
Groups
Get Groups
Returns a list of groups.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/groups/?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/groups/ \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Get Group
Returns a specific group.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/groups/?customer_id=:customer_id&id=:id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
id | Required | Integer | id of the group |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/groups/ \
-u <API_KEY>: \
-d customer_id=1000 \
-d id=1001 \
-G
Assignments
Get Assignments
Returns a list of assignments.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/assignments/?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/assignments/ \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Get Assignment
Returns a specific assignment.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/assignments/?customer_id=:customer_id&id=:id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
id | Required | Integer | id of the assignment |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/assignments/ \
-u <API_KEY>: \
-d customer_id=1000 \
-d id=1001 \
-G
Dark Web Exposures
Get All Users Exposures
Returns a list of all exposed users for a customer.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/exposed-users-all.php/?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/exposed-users-all.php/ \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Get User Exposures
Returns a list of all dark web exposures found for a users.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/exposed-user.php/?customer_id=:customer_id&user_id=:user_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
user_id | Required | Integer | id of the user |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/exposed-user.php/ \
-u <API_KEY>: \
-d customer_id=1000 \
-d user_id=1001 \
-G
Notify All Users With Exposures
Sends an email to all exposed users notifying each of them about their exposures with exposure details.
Request Method | Endpoint |
|---|---|
POST | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/notify-all.php/?customer_id=:customer_id&message=:message |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
message | Required | String | email body message to send to each user along with their exposure report |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/notify-all.php/ \
-u <API_KEY>: \
-d customer_id=1000 \
-d message='Example Message' \
-P
Notify A Specific With Exposures
Sends an email to a specific user notifying them about their exposures with exposure details.
Request Method | Endpoint |
|---|---|
POST | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/notify.php/?customer_id=:customer_id&user_id=:user_idmessage=:message&emails=:emails |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
user_id | Required | Integer | id of the user |
message | Required | String | email body message to send to each user along with their exposure report |
emails | Optional | String | comma delimited list of additional emails to send the report to |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/notify.php/ \
-u <API_KEY>: \
-d customer_id=1000 \
-d user_id=1001 \
-d message='Example Message' \
- d emails='test@example.com,test2@example.com'
-P
Administrators
Get Administrators
Returns a list of administrators.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/administrators/ |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/administrators/ \
-u <API_KEY>: \
-G
Get Administrator
Returns a specific administrator.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/administrators/?id=:id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
id | Required | Integer | id of the administrator |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/administrators/ \
-u <API_KEY>: \
-d id=1000 \
-G
Compliance Metrics
Get Compliance Metrics
Return customer compliance metrics and supporting data.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/?id=customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/ \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Response Fields for Metrics:
overallPolicyCompliance = Percent compliant for policies
overallVideoCompliance = Percent compliant for videos/training
overallSurveyCompliance = Percent compliant for surveys
overallPhishingCompliance = Percent compliant for phishing training
overallZacFoundationalCompliance = Percent compliant for foundational training. *If using Autopilot
activePolicyCount = Number of active policies
activeVideoCount = Number of active videos/trainings
activeSurveyCount = Number of active surveys
activePolicyCount = Number of active phishing trainings
userCount = Number of users included in these metrics
Training Schedules
Get Training Schedule
Returns a list of all scheduled training including Foundational Training.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/training/?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/training/ \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Get Scheduled Automatic Foundational Training Program
Returns the automatic training schedule for CyberHoot's foundational training.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-training/foundational.php?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-training/foundational.php \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Get Scheduled Automatic Training Program
Returns the automatic training schedule for CyberHoot's annual training program.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-training/?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-training/ \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Get Scheduled Automatic Phishing Program
Returns the automatic training schedule for CyberHoot's annual phishing program.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-phishing/?customer_id=:customer_id |
Parameter | Required | Data Type | Details |
|---|---|---|---|
customer_id | Required | Integer | id of the customer |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-phishing/ \
-u <API_KEY>: \
-d customer_id=1000 \
-G
Partner Settings
Get Partner Settings
Returns current partner settings.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/partner/settings/ |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/partner/settings/ \
-u <API_KEY>: \
-G
Subscription Information
Get Subscription Information
Returns partner subscription information.
Request Method | Endpoint |
|---|---|
GET | https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/partner/subscription/ |
Example:
curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/partner/subscription/ \
-u <API_KEY>: \
-G
More Information
Resource Limits
CyberHoot does NOT limit the amount of calls you perform against your platform.
Just note that if you overwork your platform, you may experience a delay or sub-optimal experience while using the platform.
More Powerful Integration
CyberHoot does offer a number of write-able API endpoints that are not publicly documented, but are available.
Access to these calls require a meeting to discuss your needs.
Questions or Problems with the API?
Contact us at support@cyberhoot.com for any questions or to report any problems concerning our API.