v1
latestOpenAPI 3.1.02026-08-041911887.3 KBRisk Events Scores
Our risk scoring methodology provides an indication of how exposed a company may be to a specific risk. It does this by looking at the frequency of particular types of events, and how prominent this type of event is in the news media.
Scoring query criteria
Scoring is based on selecting events for a date range and a "cohort" of entities with a where clause, then applying scoring options with a score-by clause.
The where clause is a subset of what is available in Risk Events Search. It requires entities and a date range. The entities that make up this cohort represent a benchmark for scoring against.
The score-by clause has two optional properties:
- the entities to score, which should be a subset of the entities that made up the cohort defined in the where
- the risk "pillars" which group different event definitions into arbitrary buckets
The default behaviour without either of these options is to return a score for every available Risk Event Definition. This tells you the overall risk score for the cohort.
With the entities option set, a score is returned for every combination of Event Definition and the entities provided. This tells you the risk score for each entity.
With the pillars option set, rather than getting a score for each event definition you will get a score for that group of event definitions. This allows organising the event definitions into arbitrary buckets to support different kinds of risk framework. When combined with the entities option a score is returned for each combination of entity and pillar.
Score data returned
The score data will include:
- a name for each data point, which is either the pillar name provided, or the event definition name if pillars were not used
- a list of the relevant event definitions, either from the pillar, or a list of one event definition if pillars were not used
- optionally an entity, if entities were provided
- the count of documents
- the count of event instances
- a number from 1 to 5 which represents the "likelihood" of the event based on previous frequency
- a number from 1 to 5 which represents the "impact" of the event based on media prominence both absolutely and relatively to the cohort
- the score, which is likelihood multiplied by impact, so always a number from 1 to 25
Request body
Example request
{
"where": {
"first-reported-at": {
"gte": "2023-01-01",
"lte": "2023-01-01"
},
"entities": {
"id": {
"any": [
"bcd2d868-ed38-4382-b94a-622a30fc3215"
]
}
}
},
"score-by": {
"entity-ids": [
"bcd2d868-ed38-4382-b94a-622a30fc3215"
],
"pillars": [
{
"event-definition-ids": [
"bcd2d868-ed38-4382-b94a-622a30fc3215"
]
}
]
}
}Response
Returns a list of events matching the query
Example response
{
"scores": [
{
"entity": {
"id": "bcd2d868-ed38-4382-b94a-622a30fc3215"
}
}
]
}