Risk Scores

📘

Risk Scores sent in via the APIs are NOT the Entity Scores seen in the Dashboard.

When you add a risk score to an entity using our APIs, it must then be used to create an organizational wide Entity Risk score. This organizational wide Entity Risk score is the score you see on an entities page.

Please see this section for more information and head to /risk-scores in your Dashboard.

If provided, the risk_scores section can either be:

  • an Risk Score object of the fields "name" (required), "score" (required), "denominator" (optional)
  • an array consisting of multiple Risk Score objects
curl -X POST \
  https://<API_ENDPOINT>/v1/entities/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "risk_scores": [
        {
          "name": "risk_score1",
          "score": 100
        },
        {
          "name": "risk_score2",
          "score": 5,
          "denominator": 100
        }
      ]
  }'

The denominator is not required but it is better to provide it in order to avoid ambiguity.

For example, if a denominator is not provided and a score of 50 is provided, a denominator of 100 is assumed. If a score of 150 is provided, a denominator of 1000 is assumed.

Note that it is possible for the "score" input to be negative. Upon submitting the entity risk score, two checks will be made:

  • Is the parameter "score" less than or equal to the "denominator" value?
  • Is the absolute value of (score / denominator) <= 1?

The above two checks must pass as part of the input validation.

These risk scores can then be used in the custom Risk Score formula.