Object
Model
Securely Store,
Share and Retrieve Your CyberFacts

SurfWatch API Object Model

All API endpoints accept and return data in JSON format.

Collections of objects are not paginated, unless its explicitly stated in the resource section.

Resources that accept data (via POST) often have a simplified version of the object, and the full object can be retrieved by the corresponding GET request.

Cyber Data Group object

Key Value Type Value Description
id string The unique identifier for the Cyber Data Group.
name string The name of the Cyber Data Group.
discoverable boolean When true, the Cyber Data Group is able to be discovered by other Cyber Risk Cloud users. Those users may then request to join the Cyber Data Group, and the Cyber Data Group admin(s) may then choose to allow or reject that request.
description string A description of the Cyber Data Group.

Cyber Tag object

Key Value Type Value Description
tag_id long integer The unique identifier for the Cyber Tag.
tag string The textual description of the Cyber Tag. For example: ".htaccess basic authorization attempts".
tag_polarity integer, Polarity ID The polarity of the Cyber Tag.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.

Cyber Tag Macro Tag object

Key Value Type Value Description
macro_tag_id integer The unique identifier for the Macro Tag.
macro_tag string The textual description of the Macro Tag.
macro_tag_polarity integer, Polarity ID The polarity of the Macro Tag.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Macro Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Macro Tag belongs to.

Cyber Tag Search Result object

Key Value Type Value Description
result_rank integer The search result match ranking.
tag_id long integer The unique identifier for the Cyber Tag.
tag string The textual description of the Cyber Tag. For example: ".htaccess basic authorization attempts".
tag_polarity integer, Polarity ID The polarity of the Cyber Tag.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
canonical_tag_id long integer The unique identifier for the Canonical Cyber Tag. If the Cyber Tag represents the canonical form, then it will be the same as the Cyber Tag ID.
canonical_tag string The textual description of the Canonical Cyber Tag. This value may be different than the Cyber Tag, for example 'distributed denial-of-service' is the canonical form of 'ddos'.
canonical_tag_polarity integer, Polarity ID The polarity of the Canonical Cyber Tag.
canonical_macro_tag_id integer, Macro Tag ID The Macro Tag the Canonical Cyber Tag belongs to.
canonical_macro_tag string, Macro Tag The Macro Tag the Canonical Cyber Tag belongs to.
canonical_tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Canonical Cyber Tag belongs to.
canonical_tag_super_type string, Tag Super Type ID The Tag Super Type the Canonical Cyber Tag belongs to.

Cyber Tag Super Type object

Key Value Type Value Description
tag_super_type_id integer The unique identifier for the Tag Super Type.
tag_super_type string The textual description of the Tag Super Type.

CyberFact object

Key Value Type Value Description
cyberfact_id long integer The unique identifier for the CyberFact.
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
cyberfact_score integer A scoring of a CyberFact based upon the impact/threat level of the data involved in the CyberFact. It is based on a 1-100 scale, with a higher value representing a higher threat level.
cyberfact_source string A URI representing the source of the CyberFact.
cyberfact_source_type_id integer, CyberFact Source Type ID The source type of the CyberFact.
cyberfact_source_type String, CyberFact Source Type The source type of the CyberFact.
cyberfact_type_id integer, CyberFact Type ID The type of the CyberFact.
cyberfact_type String, CyberFact Type The type of the CyberFact.
data_feed_ids array of Feed IDs All Feed IDs the CyberFact is found in.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
publication_date Date Time The date the CyberFact entered the SurfWatch Labs Data Warehouse. Date parameters must be formatted according to Joda's ISODateTimeFormat
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

CyberFact Polarity object

Key Value Type Value Description
polarity integer The unique identifier for the CyberFact Polarity.
cyberfact_polarity string The description of the CyberFact Polarity.

CyberFact Source Type object

Key Value Type Value Description
cyberfact_source_type_id integer The unique identifier for the CyberFact Source Type.
cyberfact_source_type string The description of the CyberFact Source Type.

CyberFact Type object

Key Value Type Value Description
cyberfact_type_id integer The unique identifier for the CyberFact Type.
cyberfact_type string The short description of the CyberFact Type.
cyberfact_type_description string The description of the CyberFact Type.
polarity string, Polarity The CyberFact Polarity the CyberFact Type is associated with.

Error Code object

Key Value Type Value Description
error_code string The unique URI identifier for the Error Code.
error_instance_id string The UUID of the Error Code response instance.
documentation_uri string The URI for a more descriptive explanation of the Error Code.
user_message string The short description of the Error Code.
other_info map of string key/values Additional information regarding the error.

Feed object

Key Value Type Value Description
feed_id integer The unique identifier for the Feed.
feed_description string The description of the Feed.

Feed Risk Score object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
feed_risk float The numeric ranking of the total risk or threats that exists in a Feed. It is based on a 1-100 scale, with a higher value representing a higher risk.
feed_social_activity_percentile float The Feeds social activity percentile.
feed_social_activity_score float The amount of social and/or media scrutiny that a particular Feed receives. It is based on a 1-10 scale, with a higher value representing a higher volume.
feed_incident_volume_percentile float The Feeds incident volume percentile.
feed_incident_volume_score float The level of unique reported cyber events that occur within an Feed. It is based on a 1-10 scale, with a higher value representing a higher volume.
feed_actor_threat_percentile float The Feeds actor threat percentile.
feed_actor_threat_score float The threat of the Actors active within a Feed. It is based on a 1-10 scale, with a higher value representing a more impactful set of Actors.
feed_targeted_asset_percentile float The Feeds targeted asset percentile.
feed_targeted_asset_score float The level of risk the impacted Targets experience within a Feed. It is based on a 1-10 scale, with a higher value representing more impactful Targets.
feed_effect_impact_percentile float The Feeds effect impact percentile.
feed_effect_impact_score float The severity of Effects that are results from cyber events that occur within a Feed. It is based on a 1-10 scale, with a higher value representing a more drastic Effect.
feed_practice_percentile float The Feeds practice percentile
feed_practice_impact_score float The level of the Practices typically employed on successful cyber event seen on entities grouped within the Feed. It is based on a 1-10 scale, with a higher value representing more nefarious methods.

Feed Social Significance object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
feed_significance_score integer The social significance score of a Feed. It is based on a 1-100 scale, with a higher value representing a greater level of social 'chatter'.
feed_trend float The trend of the significance score. It is based on a 1-100 scale, with a higher value representing a greater trend.
feed_momentum float The momentum of the significance score. It is based on a 1-100 scale, with a higher value representing greater momentum.

Industry object

Key Value Type Value Description
industry_id integer The unique identifier for the Industry.
industry_description string The description of the Industry.

Industry Group object

Key Value Type Value Description
industry_group_id integer The unique identifier for the Industry Group.
industry_group_description string The description of the Industry Group.
industry_id integer, Industry ID The Industry the Industry Group belongs to.
industry_description string, Industry The Industry the Industry Group belongs to.

Industry Target object

Key Value Type Value Description
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry Group that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry Group, which is a subcategory of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.

Industry Target related to Cyber Tag object

Key Value Type Value Description
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.
tag_id long integer The unique identifier for the Cyber Tag.
tag string The textual description of the Cyber Tag. For example: ".htaccess basic authorization attempts".
tag_polarity integer, Polarity ID The polarity of the Cyber Tag.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
weight integer Weight is the confidence that exists between the relationship between the Industry Target and the Cyber Tag in the system.
ranking integer Ranking represents the position on a scale. The lower value represents a higher position on the scale.
first_seen string DateTime the association was first seen.

Industry Target Headline object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
cyber_facts array of Cyber Fact objects The Cyber Facts that occured for the analytic day.

Industry Target Search Result object

Key Value Type Value Description
result_rank integer The search result match ranking.
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.
industry_target_synonym string The textual description of the Industry Target Synonym. This value may be different than the Industry Target, for example 'Sony Corporation' is a synonym of 'Sony Corp Ord'.

Industry Target Summary object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.
average_cyberfact_score float The average Cyber Fact score for the Industry Target for the analytic_day.
std_cyberfact_score float The statistical standard deviation of the Cyber Fact score for the Industry Target for the analytic_day.
max_cyberfact_score float The statistical maximum of the Cyber Fact score for the Industry Target for the analytic_day.

Market object

Key Value Type Value Description
market string The common abbreviation for the Market.
market_description string The description of the Market.

Macro Percentage object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
macro_ranking float The ranking of the Macro Tag within the Feed and Tag Super Type within the analytic time range.
macro_percentage float The percentage occurance of the Macro Tag within the Feed and Tag Super Type within the analytic time range.

Macro Delta object

Key Value Type Value Description
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
trend_delta_mean float The statistical mean of the trend delta across the last 120 days.
trend_delta_standard_dev float The statistical standard deviation of the trend delta across the last 120 days.
trend_delta_max float The statistical maximum of the trend delta across the last 120 days.
trend_delta_min float The statistical minimum of the trend delta across the last 120 days.
trend_delta_threshold float The statistical threshold of the trend delta across the last 120 days.
deltas array of Macro Trend Delta objects Array of trend delta objects for each analytic_day for given time range.

Macro Trend Delta object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
macro_trend float A measure of how much the trend of a Macro Tag changes for the analytic_day.
macro_trend_delta float The statistical mean and standard deviation of the trend delta across the last 120 days.

Phishing Industry Target object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
phishing_total_count long integer The total count of phishing events for the analytic day.
phishing_industry_target_count long integer The total count of phishing events for the Industry Target for the analytic day.
phishing_industry_target_percentage float The percentage of phishing events for the Industry Target for the analytic day.
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry Group that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry Group, which is a subcategory of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.

Practice Tag Headline object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
tag_id long integer The Practice Cyber Tag the headline is about.
tag string The Practice Cyber Tag the headline is about.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
cyber_facts array of Cyber Fact objects The Cyber Facts that occured for the analytic day.

Submitted Cyber Data Permissions object

Key Value Type Value Description
cyberfact_ids array of CyberFact Ids The CyberFact Id(s) for this operation to modify.
cyber_data_group_ids_to_include array of Cyber Data Group Ids The Cyber Data Group Id(s) to add to the provided CyberFacts.
cyber_data_group_ids_to_exclude array of Cyber Data Group Ids The Cyber Data Group Id(s) to remove from the provided CyberFacts.

Submitted Cyber Tag object (GET)

Key Value Type Value Description
tag_id long integer The unique identifier for the Cyber Tag.
tag string The textual description of the Cyber Tag. For example: ".htaccess basic authorization attempts".
computed_tag_id long integer, Cyber Tag ID The best matching Cyber Tag ID.
tag_polarity integer, Polarity ID The polarity of the Cyber Tag.
macro_tag_id integer, Macro Tag ID The Macro Tag the Cyber Tag belongs to.
macro_tag string, Macro Tag The Macro Tag the Cyber Tag belongs to.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.

Submitted CyberFact object (POST)

Key Value Type Value Description
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
tags array of Cyber Tag objects The Cyber Tags that describe the CyberFact.

Submitted CyberFact object (GET)

Key Value Type Value Description
cyberfact_id long integer The unique identifier for Submitted CyberFact.
event_date Date Time The date the CyberFact took place. Date parameters must be formatted according to Joda's ISODateTimeFormat
publication_date Date Time The date the CyberFact was submitted to the SurfWatch Labs Submitted Data Store. Date parameters must be formatted according to Joda's ISODateTimeFormat
cyberfact_polarity integer, CyberFact Polarity ID The polarity of the CyberFact.
sanitized boolean Marking a CyberFact as sanitized means they are to be sanitized before being saved in the SurfWatch Labs Data Warehouse. An unmolested copy of the CyberFact is stored in the SurfWatch Labs Submitted Data Store. Sanitization removes sensitive information from SurfWatch Labs analytics. By not sanitizing a CyberFact, SurfWatch Labs will use all data fields in the CyberFact for analytical purposes.
submitting_user_id string The ID of the user responsible for submitting the CyberFact.
submitting_license_id String, Cyber Risk Cloud License Information ID The Cyber Risk Cloud license ID responsible for submitting the CyberFact.
cyber_data_group_ids array of Cyber Data Group Ids The Cyber Data Group Id(s) that have access to the CyberFact.
industry_targets array of Industry Target objects The Industry Targets that describe the CyberFact.
tags array of Submitted Cyber Tag objects The Submitted Cyber Tags that describe the CyberFact.

Submitted CyberFact Note object (POST)

Key Value Type Value Description
note_value string The content of the note.
note_type_id integer, Submitted Note Type Id The unique identifier for the note type.
note_parent_id integer, Submitted Note Type Id The unique identifier for the note that is the parent to this note.

Submitted CyberFact Note object (GET)

Key Value Type Value Description
note_id long integer The unique identifier for the note.
note_value string The content of the note.
cyberfact_id long integer, Submitted CyberFact Id The unique identifier for the Submitted CyberFact that the note pertains to.
note_type_id integer, Submitted Note Type Id The unique identifier for the note type.
note_type String, Submitted Note Type The short textual description of the note type.
submitting_user_id string The ID of the user responsible for submitting the CyberFact.
submitting_license_id String, Cyber Risk Cloud License Information ID The Cyber Risk Cloud license ID responsible for submitting the CyberFact.
note_parent_id integer, Submitted Note Type Id The unique identifier for the note that is the parent to this note. The note_parent_id is used for note structures like comment chains.

Submitted Industry Target object (GET)

Key Value Type Value Description
industry_target_id long integer The unique identifier for the Industry Target.
industry_target_description string The textual description of the Industry Target. For example: "SurfWatch Labs".
computed_industry_target_id long integer, Industry Target ID The best matching Industry Target ID.
industry_id integer, Industry ID The Industry that the Industry Target belongs to.
industry_description string, Industry description The textual description of the Industry.
industry_group_id integer, Industry Group ID The Industry that the Industry Target belongs to.
industry_group_description string, Industry Group description The textual description of the Industry.
industry_target_parent_id integer, Industry Target ID The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
industry_group_description string, Industry Target description The Industry Target that the Industry Target belongs to (ex: conglomerates, multinational corps, etc).
market string, Market The market the Industry Target belongs to.

Submitted Note Type object

Key Value Type Value Description
note_type_id short integer The unique identifier for the note type.
note_type string The short textual description of the note type.
note_description string The textual description of the note type.

Cyber Risk Cloud License Information object

Key Value Type Value Description
id string The unique identifier for the Cyber Risk Cloud license.
description string A description of the Cyber Risk Cloud license.
license_users array An array of all of the users who occupy a seat for the license.
license_users.id string The unique identifier for the Cyber Risk Cloud user.
license_users.email string The email of the Cyber Risk Cloud user.

Tag Trend object

Key Value Type Value Description
analytic_day Date Time The date the analytic was run. Date parameters must be formatted according to Joda's ISODateTimeFormat
analytic_day Interval The datetime interval over which the analytic was run.
feed_id integer, Feed ID The Feed the analytic was run against.
feed_description string, Feed The Feed the analytic was run against.
macro_tag_id integer, Macro Tag ID The Macro Tag analytic is about.
macro_tag string, Macro Tag The Macro Tag analytic is about.
tag_super_type_id integer, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_super_type string, Tag Super Type ID The Tag Super Type the Cyber Tag belongs to.
tag_trend float The percentage of activity of a Cyber Tag within a Macro Tag category for a particular Feed.
tag_trend_rank float Indicates the rank of a Cyber Tag's activity within a Macro Tag category for a particular Feed.
tag_momentum float Indicates decreased, unchanged, or increased (-1, 0, 1) Cyber Tag activity within a Macro Tag category for a particular Feed.