Detect Compliance Risks

POST /api/v1/detect-risks

Identifies classification errors, time structure issues, and award coverage gaps before running the pay calculation.

Request body

Same as Calculate Pay. Same fields, same validation.

Response

Field	Type	Description
risks	array	List of detected risk items
overall_risk_level	string	Aggregate level: low, moderate, elevated, high
requires_manual_review	boolean	Whether a human should review before finalising
total_risks_detected	integer	Total count of risks found
risk_counts_by_severity	object	Count per severity: {"high": 0, "warning": 1, "info": 0}
risk_text	string	Plain-English summary of all risks
detection_mode	string	Always pre_calc for this endpoint
deterministic	boolean	Always true — no AI involved

Risk item fields

Field	Type	Description
risk_code	string	Machine-readable risk identifier (e.g. SHIFT_EXCEEDS_DAILY_MAX)
risk_label	string	Human-readable label
category	string	Risk category (e.g. classification_mapping, time_structure)
severity	string	high, warning, or info
confidence	string	high, medium, or low
description	string	Detailed explanation of the risk
review_action	string	Suggested review action
impact_area	string	What the risk affects (e.g. base_pay, overtime)

Common risk codes

Code	Severity	Description
CLASSIFICATION_NOT_FOUND	high	Classification code not recognised for this award
NO_BASE_PAY_RATE	high	No pay rate found for this classification/employment type
SHIFT_EXCEEDS_DAILY_MAX	warning	Shift exceeds the award’s daily maximum hours
WEEKLY_HOURS_EXCEEDED	warning	Weekly hours exceed ordinary hours threshold
NO_BREAK_DEDUCTED	warning	Long shift without break deduction
MINIMUM_ENGAGEMENT_NOT_MET	warning	Casual shift below minimum engagement hours
CLASSIFICATION_AMBIGUOUS	warning	Multiple classifications at the same level
AWARD_NOT_ENGINE_ENABLED	high	Award code is not supported for calculations

Example request

curl -X POST /api/v1/detect-risks \
  -H "Authorization: Bearer ak_KEY:sk_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "award_code": "MA000009",
    "classification_code": "INVALID_CODE",
    "employment_type": "full_time",
    "work_date": "2026-03-16",
    "total_hours_worked": 12
  }'