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.

customer_type

Optional

String

Options are: 'power', 'standard', or 'hootphish'.  Use 'standard' for Autopilot customers.

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/ \
  -u <API_KEY>: \
  -d limit=2 \
  -G

Response Fields:

[id] => STRING
[domain] => STRING
[name] => STRING
[customer_type] => STRING
[training_start_date] => INTEGER
[foundational_program_speed] => STRING
[support_email] => STRING
[primary_color] => HEX COLOR
[secondary_color] => HEX COLOR
[branding_override] => INTEGER (1 = override, 0 = use default)
[date_created] => INTEGER
[report_frequency] => STRING (weekly or monthly)
[report_day] => INTEGER (day of the month 1-31)
[report_recipients_json] => JSON
[welcome_email_enabled] => INTEGER (1 = enabled, 0 = disabled)
[hoot_score] => INTEGER
[hoot_rank] => STRING
[activePolicyCount] => INTEGER
[overallPolicyCompliance] => PERCENT
[activeVideoCount] => INTEGER
[overallVideoCompliance] => PERCENT
[activeSurveyCount] => INTEGER
[overallSurveyCompliance] => PERCENT
[activePhishingCount] => INTEGER
[overallPhishingCompliance] => PERCENT
[activeZacFoundationalCount] => INTEGER
[overallZacFoundationalCompliance] => PERCENT
[userCount] => INTEGER

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/ \
  -u <API_KEY>: \
  -d id=1000 \
  -G

Response Fields:

Same as the Get Customers request.

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-ranks/customer/customer-hoot-rank.php?customer_id=:customer_id

Parameter

Required

Data Type

Details

customer_id

Required

Integer

id of the customer

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-ranks/customer/customer-hoot-rank.php \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

{
"hootRank": STRING (ID of HootRank),
"hootScore": INT (Current HootScore),
"badgeImage": STRING (Path to HootRank owl image),
"badgeIcon": STRING (Path to HootRank owl icon image),
}

Get Customer Available Security Awareness Rank Levels

•Returns a list of all available HootRanks at a customer level.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-ranks/customer/

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-ranks/customer/ \
  -u <API_KEY>: \
  -G

Response Fields:

[
"hoot rank ID": {
"id": STRING (ID of HootRank),
"jsonFile": STRING (Location of information file),
"name": STRING (Name of HootRank),
"training_threshold": STRING (Combined amount of assignments users must complete to achieve this HootRank),
"training_threshold_desc": STRING (Description of amount of assignments users must complete to achieve this HootRank),
"score_threshold": STRING (Combined scores users must have to achieve this HootRank),
"score_threshold_desc": STRING (Description of how scoring works to achieve this HootRank),
"description": STRING (Description of this HootRank),
"image": STRING (Path to HootRank owl image),
"image_icon": STRING (Path to HootRank owl icon image),
"color": STRING (bootstrap color of badge),
"contrast_color": STRING (contrast color)
}
]

Get Customer Logs

Returns a list of all customer logs.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/logs/?customer_id=:customer_id&type=:type&type_id=:type_id&admin_id=:admin_id

Parameter

Required

Data Type

Details

customer_id

Required

Integer

Id of the customer

type

Optional

String

Source of log. Options are: video, policy, user, group, customer, general, training_program, manager, training_program_instance, phishing, automated_phishing, automated_training

type_id

Optional

Integer

Id of the selected type in the row above

admin_id

Optional

Integer

Id of admin who performed for this log

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/logs/ \
  -u <API_KEY>: \
  -d customer_id=1000 \

  -d type=video

  -d admin_id=100
  -G

Response Fields:

[
{
"message": STRING (log message),
"type": STRING (Source of log),
"typeId": INT (ID of the type of log this is),
"logTimestamp": INT (Unix timestamp of when log was created),
"adminId": INT (ID of admin who performed action for this log)

"adminFirstName": STRING (Admin first name)
"adminLastName": STRING (Admin last name)
}
]


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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/managers/ \
  -u <API_KEY>: \

 -d customer_id=1000 \
  -d limit=10 \
  -G

Response Fields:

[id] => INTEGER (id of manager)
[first_name] => STRING
[last_name] => STRING
[email_addr] => STRING
[manager_type] => STRING
[external_id] => STRING
[default] => INTEGER
[active] => INTEGER (1 = active in system, 0 = not active)



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

Response Fields:

[id] => INTEGER (id of user)
[parent_user_id] => INTEGER (DEPRECATED)
[new_user_id] => INTEGER (DEPRECATED)
[date_created] => INTEGER (UNIX timestamp)
[customer_id] => INTEGER
[compliant] => STRING (yes or no)
[first_name] => STRING
[last_name] => STRING
[email_address] => STRING
[manager_id] => INTEGER
[user_type] => STRING
[external_id] => STRING
[onboarding_email_sent] => INTEGER (1 = sent, 0 = not sent)
[onboarding_email_sent_date] => INTEGER (UNIX timestamp)
[phishing_difficulty] => STRING
[reset_phishing_difficulty] => STRING
[hoot_score] => INTEGER (will send 'n/a' when not applicable)
[video_score] => INTEGER (will send 'n/a' when not applicable)
[phishing_score] => INTEGER (will send 'n/a' when not applicable)
[policy_score] => INTEGER (will send 'n/a' when not applicable)
[optional_score] => INTEGER (will send 'n/a' when not applicable)
[completed_assignments] => INTEGER
[num_attempts] => INTEGER (attempts to complete assignments)
[hoot_rank] => STRING
[archived_date] =>  INTEGER (UNIX timestamp)
[active] => INTEGER (1 = active in system, 0 = not active)
[manager_first_name] => STRING (DEPRECATED)
[manager_last_name] => STRING (DEPRECATED)
[manager_email_address] => STRING (DEPRECATED)
[error] => STRING
[complianceInfo] => ARRAY (
    [compliantCount] => INTEGER
)
[assignments] => ARRAY (
    [active] => ARRAY (

            [0] => ARRAY (
                [id] => INTEGER
                [name] => STRING
                 [type] => STRING
                [completed_date] => INTEGER (UNIX timestamp)
            )   

)

)
    [pending] => ARRAY (

             [0] => ARRAY (
                 [id] => INTEGER
                 [name] => STRING
                 [type] => STRING
                [completed_date] => INTEGER (UNIX timestamp)
            )

)

    [archived] => ARRAY (
        [0] => ARRAY (
            [id] => INTEGER
            [name] => STRING
            [type] => STRING
            [completed_date] => INTEGER (UNIX timestamp)
        )
)

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/ \
  -u <API_KEY>: \

  -d customer_id=1000 \
  -d id=1001 \
  -G

Response Fields:

Same as the Get Users request.

Get User Available HootRanks

Returns a list of all available HootRanks at a user level.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-ranks/user/

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/hoot-ranks/user/ \
  -u <API_KEY>: \
  -G

Response Fields:

[
"hoot rank ID": {
"id": STRING (ID of HootRank),
"jsonFile": STRING (Location of information file),
"name": STRING (Name of HootRank),
"training_threshold": STRING (Amount of assignments user must complete to achieve this HootRank),
"training_threshold_desc": STRING (Description of amount of assignments users must complete to achieve this HootRank),
"score_threshold": STRING (Score user must have to achieve this HootRank),
"score_threshold_desc": STRING (Description of how scoring works to achieve this HootRank),
"description": STRING (Description of this HootRank),
"image": STRING (Path to HootRank owl image),
"image_icon": STRING (Path to HootRank owl icon image),
"color": STRING (bootstrap color of badge),
"contrast_color": STRING (contrast color)
}
]

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 Request:

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

Response Fields:

{
"hootRank": STRING (ID of HootRank),
"hootScore": INT (Current HootScore),
"videoScore": INT (Current video score),
"phishingScore": INT (Current Phishing score),
"policyScore": INT (Current policy score),
"badgeImage": STRING (Path to HootRank owl image),
"badgeIcon": STRING (Path to HootRank owl icon image),
}

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/groups/ \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

[id] => INTEGER (id of group)
[name] => STRING
[hr_first_name] => STRING
[hr_last_name] => STRING
[hr_email] => STRING
[group_type] => STRING
[external_id] => STRING
[users] => ARRAY (
    [45] => ARRAY (
        [id] => INTEGER (id of user in group)
        [name] => STRING
        [email] => STRING

)

[assignments] => ARRAY (
    [active] => ARRAY (
        [772] => ARRAY (
            [id] => INTEGER (id of training)
            [name] => STRING
            [type] => STRING
       )
)

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/groups/ \
  -u <API_KEY>: \

  -d customer_id=1000 \
  -d id=1001 \
  -G

Response Fields:

Same as the Get Groups request.

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/assignments/ \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

[id] => INTEGER (id of assignment)
[policy_name] => STRING
[policy_type] => STRING
[is_optional] => INTEGER (1 = optional, 0 = required)
[effective_start] => INTEGER (Date format:  YYYYMMDD)
[effective_end] => INTEGER (Date format:  YYYYMMDD)
[policy_file_name] => STRING (could be a file name or URL)
[policy_file_type] => STRING
[public] => INTEGER (1 = public, 0 = not public)
[archived] => INTEGER (1 = archived, 0 = not archived)
[groups] => ARRAY (
    [1] => ARRAY (
        [group_id] => INTEGER
        [group_name] => STRING
    )
)

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/assignments/ \
  -u <API_KEY>: \

  -d customer_id=1000 \
  -d id=1001 \
  -G

Response Fields:

Same as the Get Assignments request.

Get Assignment History

Returns a list of all (active or archived) assignment compliance history for the selected customer.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/reports/training-history/?customer_id=:customer_id&archived=:archived

Parameter

Required

Data Type

Details

customer_id

Required

Integer

id of the customer

archived

Optional

Integer

1 for active or 0 for archived (defaults to 1)

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/reports/training-history/ \
  -u <API_KEY>: \

  -d customer_id=1000 \
  -d archived=1 \
  -G

Response Fields:

{
"policyId": {
"policyName": Training name,
"policyType": Type of policy this is (policy, video, or phishing),
"effectiveStart": INTEGER (Date format YYYYMMDD),
"effectiveEnd": INTEGER (Date format YYYYMMDD),
"overallCompliance": INTEGER (compliance score for this policy)
}

Get Assignment User Compliance

Returns a breakdown of user compliance information for a given assignment.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/reports/training-history/training-users-compliance.php?customer_id=:customer_id&policy_id=:assignment_id

Parameter

Required

Data Type

Details

customer_id

Required

Integer

id of the customer

policy_id

Required

Integer

Id of the assignment

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/reports/training-history/training-users-compliance.php \
  -u <API_KEY>: \

  -d customer_id=1000 \
  -d policy_id=10 \
  -G

Response Fields:

{
"policyName": Training Name,
"users": [
{
"compliant": STRING (user compliance status),
"userFirstName": STRING (user first name),
"userLastName": STRING (user last name),
"managerId": INTEGER (ID of manager),
"managerFullName": STRING (manager full name),
"score": INTEGER (Users score on this training),
"attempts": INTEGER (Number of attempts user has taken on this training),
"dateLastSent": STRING (Last email notification date/time),
"dateResponded": STRING (When user responded date/time),
},
],
"overview": {
"percentCompliant": INTEGER (Overall compliance percentage of all users for this training),
"percentResponded": INTEGER (Percent of assigned users who have responded to this training),
"percentNotResponded": INTEGER (Percent of assigned users who have not responded to this training)
}
}

Get User Training History

Returns a list of compliance and response information for all active/archived training history for a given user.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/policy-response/training-history.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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/policy-response/training-history.php \
  -u <API_KEY>: \

  -d customer_id=1000 \
  -d user_id=10 \
  -G

Response Fields:

[
"user policy response ID": {
"id": INT (ID of the user’s policy response),
"policyId": INT (ID of the policy),
"policyType": STRING (type of training: policy, video or phishing),
"dateLastSent": STRING (Date of last email sent to user for this policy – YYYY-MM-DD, h:ia format),
"userFirstOpenedDate": STRING (Date user first opened email for this policy – YYYY-MM-DD, h:ia format),
"dateResponded": STRING (Date user responded to this policy – YYYY-MM-DD, h:ia format),
"fourthEmailSentDate": STRING (Date HR email was sent – YYYY-MM-DD, h:ia format),
"thirdEmailSentDate": STRING (Date manager email was sent – YYYY-MM-DD, h:ia format),
"secondEmailSentDate": STRING (Date reminder email was sent – YYYY-MM-DD, h:ia format),
"firstEmailSentDate STRING (Date initial was sent – YYYY-MM-DD, h:ia format),
"accepted": INT (1 if user has accepted the policy, otherwise 0),
"firstEmailNeeded": STRING (Yes or no),
"secondEmailNeeded": STRING (Yes or no),
"thirdEmailNeeded": STRING (Yes or no),
"fourthEmailNeeded": STRING (Yes or no),
"notificationNeeded": STRING (Yes or no),
"whichNotification": INT (Which notification is needed, 1-4),
"questionScore": STRING (serialized JSON of user scoring details),
"quizResults": STRING (serialized JSON of user quiz results details),
"userGroupName": STRING (Name of group user is a part of that is assigned to this policy),
"policyName": STRING (Policy name),
"isOptional": INT (1 if policy is optional, otherwise 0),
"questionEnabled": INT (1 if quiz is enabled, otherwise 0),
"policyStatus": STRING (Active, Pending, or Archived),
"emailExpiresDate": "20240405",
"effectiveStart": INT (Date policy starts, YYYYMMDD format),
"effectiveEnd": INT (Date policy ends, YYYYMMDD format),
"firstNotifyDate": INT (Date initial email gets sent, YYYYMMDD format),
"secondNotifyDate": INT (Date reminder email gets sent, YYYYMMDD format),
"thirdNotifyDate": INT (Date manager email gets sent, YYYYMMDD format),
"fourthNotifyDate": INT (Date HR email gets sent, YYYYMMDD format),
"notificationName": STRING (Current notification that is needed),
"status": STRING (users current status/step in the policy response),
},
]

Get User Training History Details

Returns response details for a specific training for a given user.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/policy-response/training-history-details.php?customer_id=:customer_id&user_id=:user_id&policy_id=assignment_id

Parameter

Required

Data Type

Details

customer_id

Required

Integer

id of the customer

user_id

Required

Integer

Id of the user

policy_id

Required

Integer

Id of the assignment

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/policy-response/training-history-details.php \
  -u <API_KEY>: \

  -d customer_id=1000 \
  -d user_id=10 \

 -d policy_id=100 \
  -G

Response Fields:

{
"dateLastSent": STRING (Date of last email sent to user for this policy – YYYY-MM-DD, h:ia format),
"userFirstOpenedDate": STRING (Date user first opened email for this policy – YYYY-MM-DD, h:ia format),
"dateResponded": STRING (Date user responded to this policy – YYYY-MM-DD, h:ia format),
"fourthEmailSentDate": STRING (Date HR email was sent – YYYY-MM-DD, h:ia format),
"thirdEmailSentDate": STRING (Date manager email was sent – YYYY-MM-DD, h:ia format),
"secondEmailSentDate": STRING (Date reminder email was sent – YYYY-MM-DD, h:ia format),
"firstEmailSentDate STRING (Date initial was sent – YYYY-MM-DD, h:ia format),
"accepted": INT (1 if user has accepted the policy, otherwise 0),
"firstEmailNeeded": STRING (Yes or no),
"secondEmailNeeded": STRING (Yes or no),
"thirdEmailNeeded": STRING (Yes or no),
"fourthEmailNeeded": STRING (Yes or no),
"notificationNeeded": STRING (Yes or no),
"whichNotification": INT (Which notification is needed, 1-4),
"questionScore": STRING (serialized JSON of user scoring details),
"userGroupName": STRING (name of group user is a part of that is assigned to this policy)
"policyName": STRING (Policy name),
"questionEnabled": INT (1 if quiz is enabled, otherwise 0),
"policyType": STRING (Type of training: Video, Policy or Phishing),
"effectiveStart": STRING (Date policy starts),
"effectiveEnd": STRING (Date policy ends),
"firstNotifyDate": STRING (Date initial email is sent),
"secondNotifyDate": STRING (Date reminder email is sent),
"thirdNotifyDate": STRING (Date manager email is sent),
"fourthNotifyDate": STRING (Date HR email is sent)
}

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/users/exposed-users/exposed-users-all.php/ \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

[test@example.com] => ARRAY (
    [userId] => INTEGER (if field is not returned, the email is not attached to a user in the system)
    [name] => STRING
    [firstBreachDate] => INTEGER (Date format:  YYYYMMDD)
    [latestBreachDate] => INTEGER (Date format:  YYYYMMDD)
    [unacknowledgedExposures] => INTEGER
    [breachCount] => INTEGER
)

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

Conditionally Required (Only required if email is not set, used for accounts that are in the CyberHoot system)

Integer

id of the user

Email

Conditionally Required (Only required if user_id is not set, used for domain accounts that are not in the CyberHoot system)

String

Email of the exposed domain account

Example Request:

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

Response Fields:

[userName] => STRING
[userEmail] => STRING
[pwnedBreaches] => ARRAY (
    [1] => ARRAY (
        [breachDate] => INTEGER (Date format:  YYYYMMDD)
        [dateFound] => INTEGER (Date format:  YYYYMMDD)
        [breachId] => INTEGER
        [logoPath] => STRING (URL of logo)
        [title] => STRING
        [description] => STRING
        [affected] => STRING (number of people affected with commas)
        [dataClasses] => STRING (comma-delimited list of affected data)
        [acknowledged] => INTGER (1 = yes, 0 = no)
        [breachJoinId] => INTEGER
    )
)
[dehashedBreaches] => ARRAY (
    [3] => ARRAY (
        [error] => STRING
        [id] => INTEGER
        [dehashed_id] => INTEGER
        [email] => STRING
        [ip_address] => STRING
        [username] => STRING
        [password] => STRING
        [hashed_password] => STRING
        [name] => STRING
        [vin] => STRING
        [address] => STRING
        [phone] => STRING
        [database_name] => STRING
        [acknowledged] => INTEGER (1 = yes, 0 = no)
        [date_found] => INTEGER (Date format:  YYYYMMDD)
        [active] => INTGER (1 = active, 0 = inactive)
)

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 Request:

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

Response Fields:

Returns '1' on success.

Notify A Specific User With Exposures

Sends an email to a SPECIFIC exposed user about their exposures/details, using their email on file.

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

Conditionally Required (Only required if user_email is not set, used for accounts that are in the CyberHoot system)

Integer

id of the user

user_email

Conditionally Required (Only required if user_id is not set, used for accounts that are in the CyberHoot system)

String

Email of exposed domain account

message


Required

String

Message to send to user along with their exposure report (email body)

emails

Optional

String

A comma delimited list of additional emails to send the report to

Example Request:

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

Response Fields:

Returns '1' on success.


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

Response Fields:

[id] => INTEGER (id of administrator)
[first_name] => STRING
[last_name] => STRING
[email_address] => STRING
[phone_number] => STRING
[password] => STRING
[force_pw_change] => INTEGER (1 = force, 0 = no force)
[tos_accept_date] => INTEGER (UNIX timestamp)
[last_login_date] => INTEGER (UNIX timestamp)
[site_admin] => INTEGER (1 = is site admin, 0 = is not site admin)
[customer_id] => INTEGER
[primary_customer_Id] => INTEGER
[date_created] => INTEGER (UNIX timestamp)
[reset_password_hash] => STRING
[reset_password_timestamp] =>  INTEGER (UNIX timestamp)
[verified] => INTEGER
[verify_hash] => STRING
[row_limit] => INTEGER
[browser_version] => STRING
[timezone] => STRING
[2fa_token] => STRING
[2fa_token_expiration_date] =>  INTEGER (UNIX timestamp)
[authentication_method] => STRING
[authenticator_app_secret_key] => STRING
[link_auth] => STRING
[2fa_bypass_token] => STRING
[2fa_bypass_token_expiration] => INTEGER (UNIX timestamp)
[active] => INTEGER (1 = active, 0 = not active)

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/administrators/ \
  -u <API_KEY>: \
  -d id=1000 \
  -G

Response Fields:

Same as the Get Administrators request.


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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/ \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

[overallPolicyCompliance] => INTEGER (Percent compliant for policies)
[overallVideoCompliance] => INTEGER (Percent compliant for videos/training)
[overallSurveyCompliance] => INTEGER (Percent compliant for surveys)
[overallPhishingCompliance] => INTEGER (Percent compliant for phishing training)
[overallZacFoundationalCompliance] => INTEGER (Percent compliant for foundational training. *If using Autopilot)
[activePolicyCount] => INTEGER (Number of active policies)
[activeVideoCount] => INTEGER (Number of active videos/trainings)
[activeSurveyCount] => INTEGER (Number of active surveys)
[activePolicyCount] => INTEGER (Number of active phishing trainings)
[userCount] => INTEGER (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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/training/ \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

[trainings] => ARRAY (
[1] => ARRAY (
[id] => INTEGER (id of training)
[parent_policy_id] => INTEGER
[renewed_policy_id] => INTEGER
[customer_id] => INTEGER
[effective_start] => INTEGER (Date format: YYYYMMDD)
[effective_end] => INTEGER (Date format: YYYYMMDD)
[effective_duration_value] => INTEGER
[effective_duration_type] => STRING
[enable_renew_date] => INTEGER (1 = yes, 0 = no)
[renew_date] => INTEGER (Date format: YYYYMMDD)
[renew_warning_days] => INTEGER
[acceptance_window] => INTEGER
[beginning_of_acceptance_window] => INTEGER (Date format: YYYYMMDD)
[warning_notification_days] => INTEGER
[hr_notification_days] => INTEGER
[policy_name] => STRING
[policy_file_name] => STRING (could be a file name or URL)
[policy_file_type] => STRING
[policy_message] => STRING
[end_user_refusal_message] => STRING
[first_notice_subject] => STRING
[warning_notice_subject] => STRING
[expiration_notice_subject] => STRING
[hr_notice_subject] => STRING
[hr_notice_email] => STRING
[first_notice_email] => STRING
[warning_notice_email] => STRING
[expiration_notice_email] => STRING
[send_first_notice_email] => INTEGER ( 1 = yes, 0 = no)
[send_warning_notice_email] => INTEGER ( 1 = yes, 0 = no)
[send_expiration_notice_email] => INTEGER ( 1 = yes, 0 = no)
[send_hr_notice_email] => INTEGER ( 1 = yes, 0 = no)
[fixed_acceptance_date] => INTEGER ( 1 = yes, 0 = no)
[policy_type] => STRING
[public] => INTEGER ( 1 = yes, 0 = no)
[report_admin_csv] => STRING
[report_email_csv] => STRING
[question_enabled] => INTEGER ( 1 = yes, 0 = no)
[question_passing_score] => DECIMAL
[is_optional] => INTEGER ( 1 = yes, 0 = no)
[archived] => INTEGER ( 1 = yes, 0 = no)
[training_program_id] => INTEGER
[training_program_instance_id] => INTEGER
[library_id] => INTEGER
[library_type] => STRING
[library_version] => INTEGER
[version] => INTEGER
[retake_override] => INTEGER ( 1 = yes, 0 = no)
[phishing_difficulty] => STRING
[overall_compliance] => INTEGER
[deployment] => DEPRECATED
[groupsArr] => STRING
[error] => STRING
[active] => INTEGER ( 1 = active, 0 = inactive)
)

[compliance] => ARRAY (
[1] => ARRAY (
[policyName] => STRING
[policyType] => STRING
[overallCompliance] => INTEGER
)
)

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-training/foundational.php \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

Same as the Get Training Schedule request.

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-training/ \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

Same as the Get Training Schedule request.

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 Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/customers/automated-phishing/ \
  -u <API_KEY>: \
  -d customer_id=1000 \
  -G

Response Fields:

Same as the Get Training Schedule request.


Partner Settings

Get Partner Settings

Returns current partner settings.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/partner/settings/

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/partner/settings/ \
  -u <API_KEY>: \
  -G

Response Fields:

[id] => INTEGER
[full_name] => STRING
[short_name] => STRING
[contact_email] => STRING
[contact_phone] => STRING
[website] => STRING
[service_name] => STRING
[sales_module_report_msg] => STRING
[sales_enabled] => INTEGER (1 = yes, 0 = no)
[whitelabel_certificate_of_completion] => INTEGER (1 = yes, 0 = no)
[primary_color] => HEX Color
[secondary_color] =>HEX Color
[ch_color_override] => INTEGER (1 = yes, 0 = no)
[show_wizard] => INTEGER (1 = yes, 0 = no)
[api_key] => STRING
[timezone] => STRING
[cust_id] => INTEGER

Multi-Language Support Settings

Get Supported Languages

Returns a list of all supported languages in the CyberHoot platform

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/languages/

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/languages/ \
  -u <API_KEY>: \
  -G

Response Fields:

{
"language ID": {
"error": BOOL (True if error, otherwise null),
"id": INT (ID of language),
"language": STRING,
"language_code": STRING,
"active": INT
}
}


Subscription Information

Get Subscription Information

Returns partner subscription information.

Request Method

Endpoint

GET

https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/partner/subscription/

Example Request:

curl https://<DEPLOYMENT_SUBDOMAIN>.cyberhoot.com/api/partner/subscription/ \
  -u <API_KEY>: \
  -G

Response Fields:

[spawCustomerId] => INTEGER
[subscriptionId] => STRING (Stripe subscription ID)
[billingCustomerId] => STRING (Stripe customer ID)
[customerInfoArray] => ARRAY (
    [id] => STRING (Stripe customer ID)
    [object] => STRING
    [account_balance] => INTEGER
    [address] => ARRAY (
        [city] => STRING
        [country] => STRING
        [line1] => STRING
        [line2] => STRING
        [postal_code] => STRING
        [state] => STRING
    )
    [balance] => INTEGER
    [created] => INTEGER (UNIX timestamp)
    [currency] => STRING
    [default_currency] => STRING
    [default_source] => STRING
    [delinquent] => STRING
    [description] => STRING
    [discount] => STRING
    [email] => STRING
    [invoice_prefix] => STRING
    [invoice_settings] => ARRAY (
        [custom_fields] => STRING
        [default_payment_method] => STRING
        [footer] => STRING
        [rendering_options] => STRING
    )
    [livemode] => STRING
    [metadata] => Array
    (
    )
    [name] => STRING
    [next_invoice_sequence] => INTEGER
    [phone] => STRING
    [preferred_locales] => Array
    (
        [0] => STRING
    )
    [shipping] => STRING
    [sources] => ARRAY (
        [object] => STRING
        [data] => ARRAY (
     )
     [has_more] => STRING
     [total_count] => INTEGER
     [url] => STRING
 )
 [subscriptions] => ARRAY (
    [object] => STRING
    [data] => ARRAY (
    )
     [has_more] => STRING
     [total_count] => INTEGER
     [url] => STRING
)
[tax_exempt] => STRING
[tax_ids] => ARRAY (
    [object] => STRING
    [data] => ARRAY (
    )
     [has_more] => STRING
     [total_count] => INTEGER
     [url] => STRING
)
[tax_info] => STRING
[tax_info_verification] => STRING
[test_clock] => STRING
[subscription] => ARRAY (
    [id] => STRING
    [object] => STRING
    [application] => STRING
    [application_fee_percent] => DECIMAL
    [automatic_tax] => ARRAY (
        [enabled] => STRING
        [liability] => STRING
    )
    [billing] => STRING
    [billing_cycle_anchor] => STRING
    [billing_cycle_anchor_config] => STRING
    [billing_thresholds] => STRING
    [cancel_at] => INTEGER (UNIX timestamp)
    [cancel_at_period_end] => INTEGER (UNIX timestamp)
    [canceled_at] => INTEGER (UNIX timestamp)
    [cancellation_details] => ARRAY (
        [comment] => STRING
        [feedback] => STRING
        [reason] => STRING
    )
    [collection_method] => STRING
    [created] => INTEGER (UNIX timestamp)
    [currency] => STRING
    [current_period_end] => INTEGER (UNIX timestamp)
    [current_period_start] => INTEGER (UNIX timestamp)
    [customer] => STRING
    [days_until_due] => INTEGER
    [default_payment_method] => STRING
    [default_source] => STRING
    [default_tax_rates] => ARRAY(
    )
    [description] => STRING
    [discount] => STRING
    [ended_at] => INTEGER (UNIX timestamp)
    [invoice_customer_balance_settings] => ARRAY (
        [consume_applied_balance_on_void] => INTEGER
    )
    [invoice_settings] => ARRAY (
        [account_tax_ids] => STRING
        [issuer] => ARRAY (
            [type] => STRING
        )
    )
    [items] => ARRAY (
        [object] => STRING
        [data] => ARRAY (
            [0] => ARRAY (
                [id] => STRING
                [object] => STRING
                [billing_thresholds] => STRING
                [created] => INTEGER (UNIX timestamp)
                [metadata] => ARRAY (
                )
                [plan] => ARRAY (
                    [id] => STRING
                    [object] => STRING
                    [active] => INTEGER
                    [aggregate_usage] => STRING
                    [amount] => INTEGER
                    [amount_decimal] => DECIMAL
                    [billing_scheme] => STRING
                    [created] => INTEGER (UNIX timestamp)
                    [currency] => STRING
                    [interval] => STRING
                    [interval_count] => INTEGER
                    [livemode] => STRING
                    [metadata] => ARRAY (
                    )
                    [nickname] => STRING
                    [product] => STRING
                    [tiers] => STRING
                    [tiers_mode] => STRING
                    [transform_usage] => STRING
                    [trial_period_days] => INTEGER
                   [usage_type] => STRING
               )
               [price] => ARRAY (
                   [id] => STRING
                   [object] => STRING
                   [active] => INTEGER
                   [billing_scheme] => STRING
                   [created] => INTEGER (UNIX timestamp)
                   [currency] => STRING
                   [custom_unit_amount] => INTEGER
                   [livemode] => STRING
                   [lookup_key] => STRING
                   [metadata] => ARRAY (
                   )
                   [nickname] => STRING
                   [product] => STRING
                   [recurring] => ARRAY (
                       [aggregate_usage] => STRING
                        [interval] => STRING
                        [interval_count] => INTEGER
                        [trial_period_days] => INTEGER
                        [usage_type] => STRING
                   )
                   [tax_behavior] => STRING
                   [tiers_mode] => STRING
                   [transform_quantity] => INTEGER
                   [type] => STRING
                   [unit_amount] => INTEGER
                   [unit_amount_decimal] => DECIMAL
               )
               [quantity] => INTEGER
               [subscription] => STRING
               [tax_rates] => ARRAY (
               )
           )
       )
       [has_more] => STRING
       [total_count] => INTEGER
       [url] => STRING
)
[latest_invoice] => STRING
[livemode] => STRING
[metadata] => ARRAY (
)
[next_pending_invoice_item_invoice] => STRING
[on_behalf_of] => STRING
[pause_collection] => STRING
[payment_settings] => ARRAY (
    [payment_method_options] => STRING
    [payment_method_types] => STRING
    [save_default_payment_method] => STRING
)
[pending_invoice_item_interval] => STRING
[pending_setup_intent] => STRING
[pending_update] => STRING
[plan] => ARRAY (
    [id] => STRING
    [object] => STRING
    [active] => INTEGER
    [aggregate_usage] => STRING
    [amount] => INTEGER
    [amount_decimal] => DECIMAL
    [billing_scheme] => STRING
    [created] => INTEGER (UNIX timestamp)
    [currency] => STRING
    [interval] => STRING
    [interval_count] => INTEGER
    [livemode] => STRING
    [metadata] => ARRAY (
)

[nickname] => STRING
[product] => STRING
[tiers] => STRING
[tiers_mode] => STRING
[transform_usage] => STRING
[trial_period_days] => STRING
[usage_type] => STRING
[quantity] => INTEGER
[schedule] => STRING
[start] => INTEGER (UNIX timestamp)
[start_date] => INTEGER (UNIX timestamp)
[status] => STRING
[tax_percent] => DECIMAL
[test_clock] => STRING
[transfer_data] => STRING
[trial_end] => INTEGER (UNIX timestamp)
[trial_settings] => ARRAY (
    [end_behavior] => ARRAY (
        [missing_payment_method] => STRING
    )
)
[trial_start] => INTEGER
[referral_info] => STRING
[isReseller] => INTEGER
[cancelFeedback] => STRING
[primaryCustomerId] => INTEGER
[nextInvoiceAmount] => DECIMAL


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.


Find out how CyberHoot can secure your business.