Employees API

The Employees API lets you programmatically manage employee records, retrieve scores, and query employee data.

Authentication
All API requests require a valid API key. See the Authentication guide for details.

List Employees

GET /v1/employees

Query Parameters:
  page        integer   Page number (default: 1)
  per_page    integer   Results per page (default: 25, max: 100)
  department  string    Filter by department
  band        string    Filter by score band (green, yellow, orange, red, critical)
  status      string    Filter by status (active, inactive)
  sort        string    Sort field (score, name, last_event)
  order       string    Sort order (asc, desc)

Response

{
  "data": [
    {
      "id": "emp_abc123",
      "email": "john.doe@company.com",
      "first_name": "John",
      "last_name": "Doe",
      "department": "Engineering",
      "manager_email": "jane.smith@company.com",
      "score": 72,
      "band": "yellow",
      "status": "active",
      "last_event_at": "2025-01-15T10:30:00Z",
      "created_at": "2024-06-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1250,
    "total_pages": 50
  }
}

Get Employee

GET /v1/employees/:id

Response:
{
  "id": "emp_abc123",
  "email": "john.doe@company.com",
  "first_name": "John",
  "last_name": "Doe",
  "department": "Engineering",
  "title": "Senior Developer",
  "location": "San Francisco",
  "manager_email": "jane.smith@company.com",
  "score": 72,
  "band": "yellow",
  "score_history": [...],
  "status": "active",
  "integrations": ["okta", "crowdstrike"],
  "last_event_at": "2025-01-15T10:30:00Z",
  "created_at": "2024-06-01T00:00:00Z"
}

Get Employee by Email

GET /v1/employees/by-email/:email

Update Employee

PATCH /v1/employees/:id

Body:
{
  "department": "Security",
  "title": "Security Engineer",
  "status": "active"
}

Note: Score cannot be modified via API. Use manual
adjustment in the admin dashboard instead.

Get Employee Events

GET /v1/employees/:id/events

Query Parameters:
  page        integer   Page number
  per_page    integer   Results per page
  type        string    Filter by event type
  from        string    Start date (ISO 8601)
  to          string    End date (ISO 8601)

Get Employee Score History

GET /v1/employees/:id/score-history

Query Parameters:
  from        string    Start date (ISO 8601)
  to          string    End date (ISO 8601)
  interval    string    Data point interval (hourly, daily, weekly)

Next Steps