Scores API

The Scores API provides access to employee security scores, organizational score aggregates, and score distribution data.

Get Organization Scores

GET /v1/scores/summary

Response:
{
  "average_score": 74.2,
  "median_score": 78,
  "total_employees": 1250,
  "band_distribution": {
    "green": { "count": 650, "percentage": 52.0 },
    "yellow": { "count": 320, "percentage": 25.6 },
    "orange": { "count": 180, "percentage": 14.4 },
    "red": { "count": 75, "percentage": 6.0 },
    "critical": { "count": 25, "percentage": 2.0 }
  },
  "trend": {
    "direction": "improving",
    "change": +2.3,
    "period": "30d"
  }
}

Get Department Scores

GET /v1/scores/departments

Response:
{
  "data": [
    {
      "department": "Engineering",
      "average_score": 78.5,
      "employee_count": 280,
      "band_distribution": { ... }
    },
    {
      "department": "Sales",
      "average_score": 69.2,
      "employee_count": 150,
      "band_distribution": { ... }
    }
  ]
}

Get Score Distribution

GET /v1/scores/distribution

Query Parameters:
  department  string    Filter by department
  bucket_size integer   Score bucket size (default: 5)

Response:
{
  "buckets": [
    { "range": "0-4", "count": 5 },
    { "range": "5-9", "count": 8 },
    ...
    { "range": "95-100", "count": 120 }
  ]
}

Get Score Trends

GET /v1/scores/trends

Query Parameters:
  from        string    Start date (ISO 8601)
  to          string    End date (ISO 8601)
  interval    string    Data interval (daily, weekly, monthly)
  department  string    Filter by department

Response:
{
  "data": [
    {
      "date": "2025-01-01",
      "average_score": 72.1,
      "median_score": 76,
      "employee_count": 1240
    },
    {
      "date": "2025-01-08",
      "average_score": 73.4,
      "median_score": 77,
      "employee_count": 1245
    }
  ]
}

Get Top Risks

GET /v1/scores/top-risks

Query Parameters:
  limit       integer   Number of results (default: 10)
  sort        string    Sort by: lowest_score, biggest_drop

Response:
{
  "data": [
    {
      "employee_id": "emp_abc123",
      "email": "user@company.com",
      "score": 22,
      "band": "red",
      "score_change_30d": -45,
      "top_risk_factor": "phishing_click"
    }
  ]
}

Rate Limits

Next Steps

• Employees API
• Events API
• Rules API