Adherence API

Endpoints for real-time agent states and adherence alerts.

Agent States

Get Current States

GET/api/adherence/statesAuth: Session

Get current agent states with adherence info.

Query Parameters:

Parameter	Type	Required	Description
`teamId`	string	Optional	Filter by team

Response (200):

json

{
  "states": [
    {
      "employeeId": "uuid",
      "employeeName": "John Doe",
      "employeeNumber": "EMP001",
      "state": "available",
      "stateStartedAt": "2026-01-29T08:00:00Z",
      "queue": "sales",
      "scheduledState": "available",
      "isAdherent": true,
      "shift": {
        "startTime": "08:00",
        "endTime": "16:00"
      }
    }
  ],
  "summary": {
    "totalAgents": 25,
    "adherentCount": 23,
    "adherencePercentage": 92
  }
}

Update Agent State

POST/api/adherence/statesAuth: Session

Update an agent's state (usually via integration).

Request Body:

json

{
  "employeeId": "uuid",
  "state": "on_call",
  "queue": "sales",
  "reason": "Customer call"
}

Parameter	Type	Required	Description
`employeeId`	string	Required	Employee UUID
`state`	string	Required	New state (see values below)
`queue`	string	Optional	Queue or skill name
`reason`	string	Optional	Reason for state change

Valid States:

| State | Description | |-------|-------------| | available | Ready to take contacts | | on_call | Handling a contact | | after_call_work | Post-call tasks | | break | On break | | lunch | On lunch | | meeting | In a meeting | | training | In training | | offline | Not logged in | | unavailable | Logged in but not available |

Adherence Alerts

List Alerts

GET/api/adherence/alertsAuth: Session

Get adherence alerts.

Query Parameters:

Parameter	Type	Required	Description
`status`	string	Optional	Filter: "active", "acknowledged", "resolved"
`limit`	number	Optional	Max results (default 50)

Response (200):

json

{
  "alerts": [
    {
      "id": "uuid",
      "employeeId": "uuid",
      "employeeName": "John Doe",
      "type": "late_start",
      "message": "Agent logged in 15 minutes late",
      "status": "active",
      "createdAt": "2026-01-29T08:15:00Z",
      "acknowledgedAt": null,
      "resolvedAt": null
    }
  ]
}

Get Alert Details

GET/api/adherence/alerts/:idAuth: Session

Get alert details.

Update Alert

PATCH/api/adherence/alerts/:idAuth: Session

Acknowledge or resolve an alert.

Request Body:

json

{
  "action": "acknowledge",
  "notes": "Agent was on approved break extension"
}

Parameter	Type	Required	Description
`action`	string	Required	"acknowledge" or "resolve"
`notes`	string	Optional	Notes about the alert

Response (200):

json

{
  "success": true,
  "alert": {
    "id": "uuid",
    "status": "acknowledged",
    "acknowledgedAt": "2026-01-29T08:20:00Z",
    "notes": "Agent was on approved break extension"
  }
}

Alert Types

| Type | Description | Trigger | |------|-------------|---------| | late_start | Agent logged in late | After grace period from shift start | | early_leave | Agent logged off early | Before shift end | | extended_break | Break exceeded duration | Break over configured limit | | unscheduled_break | Break during work time | Break not during scheduled break | | wrong_state | State mismatch | Actual differs from scheduled |