SLA API

The SLA (Service Level Agreement) API manages SLA policies, tracks compliance, and monitors response time targets for tickets.

SLA Policy Object

{
  id: string;                    // UUID
  organization_id: string;       // UUID of the organization
  name: string;                  // Policy name
  description?: string;          // Policy description
  conditions: SLACondition[];    // When this policy applies
  first_response_time?: number;  // Minutes until first response required
  next_response_time?: number;   // Minutes between subsequent responses
  resolution_time?: number;      // Minutes until resolution required
  priority: number;              // Policy priority (higher = evaluated first)
  enabled: boolean;              // Whether policy is active
  created_at: string;            // ISO timestamp
  updated_at: string;            // ISO timestamp
}

SLA Condition Schema

{
  field: string;     // Field to check (e.g., 'priority', 'tags', 'channel')
  operator: string;  // Comparison operator
  value: any;        // Value to compare against
}

SLA Tracking Object

{
  id: string;                    // UUID
  ticket_id: string;             // UUID of the tracked ticket
  policy_id: string;             // UUID of the applied SLA policy
  first_response_due: string;    // ISO timestamp when first response is due
  first_response_at?: string;    // ISO timestamp when first response was sent
  next_response_due?: string;    // ISO timestamp for next response
  resolution_due: string;        // ISO timestamp when resolution is due
  resolved_at?: string;          // ISO timestamp when ticket was resolved
  is_paused: boolean;            // Whether SLA timer is paused
  paused_at?: string;            // ISO timestamp when paused
  breach_status: string;         // none, warning, breached
  created_at: string;            // ISO timestamp
}

List SLA Policies

Retrieve all SLA policies for the organization.

Procedure: sla.listPolicies

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/sla.listPolicies" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "uuid",
          "name": "Urgent Priority SLA",
          "description": "SLA for urgent priority tickets",
          "conditions": [
            {"field": "priority", "operator": "equals", "value": "urgent"}
          ],
          "first_response_time": 30,
          "next_response_time": 60,
          "resolution_time": 240,
          "priority": 100,
          "enabled": true,
          "created_at": "2024-01-01T00:00:00.000Z"
        },
        {
          "id": "uuid-2",
          "name": "Standard SLA",
          "description": "Default SLA for all tickets",
          "conditions": [],
          "first_response_time": 480,
          "next_response_time": 1440,
          "resolution_time": 2880,
          "priority": 0,
          "enabled": true,
          "created_at": "2024-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

Notes:

Policies are returned in priority order (highest first)
The first matching policy is applied to a ticket

Create SLA Policy

Create a new SLA policy. Admin only.

Procedure: sla.createPolicy

Authentication: Required (Admin)

Input:

{
  name: string;                  // 1-200 characters
  description?: string;          // Optional description
  conditions?: SLACondition[];   // When policy applies (default: [])
  firstResponseTime?: number;    // Minutes (optional)
  nextResponseTime?: number;     // Minutes (optional)
  resolutionTime?: number;       // Minutes (optional)
  priority?: number;             // Policy priority (default: 0)
  enabled?: boolean;             // Active status (default: true)
}

Example:

curl -X POST "https://your-domain.com/api/trpc/sla.createPolicy" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "name": "VIP Customer SLA",
      "description": "Premium SLA for VIP customers",
      "conditions": [
        {"field": "tags", "operator": "contains", "value": "vip"}
      ],
      "firstResponseTime": 15,
      "nextResponseTime": 30,
      "resolutionTime": 120,
      "priority": 50,
      "enabled": true
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "VIP Customer SLA",
        "conditions": [...],
        "first_response_time": 15,
        "next_response_time": 30,
        "resolution_time": 120,
        "priority": 50,
        "enabled": true,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
}

Update SLA Policy

Update an existing SLA policy. Admin only.

Procedure: sla.updatePolicy

Authentication: Required (Admin)

Input:

{
  id: string;                    // Required, policy UUID
  name?: string;                 // 1-200 characters
  description?: string;
  conditions?: SLACondition[];
  firstResponseTime?: number;
  nextResponseTime?: number;
  resolutionTime?: number;
  priority?: number;
  enabled?: boolean;
}

Example:

curl -X POST "https://your-domain.com/api/trpc/sla.updatePolicy" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "id": "policy-uuid",
      "firstResponseTime": 10,
      "resolutionTime": 90
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "VIP Customer SLA",
        "first_response_time": 10,
        "resolution_time": 90,
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Delete SLA Policy

Delete an SLA policy. Admin only.

Procedure: sla.deletePolicy

Authentication: Required (Admin)

Input:

{
  id: string;  // Policy UUID
}

Example:

curl -X POST "https://your-domain.com/api/trpc/sla.deletePolicy" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"id":"policy-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Notes:

Existing SLA tracking records are not deleted
Tickets with this policy retain their historical tracking data

Get SLA Tracking

Get SLA tracking information for a specific ticket.

Procedure: sla.getTracking

Authentication: Required

Input:

{
  ticketId: string;  // Ticket UUID
}

Example:

curl -X GET "https://your-domain.com/api/trpc/sla.getTracking?input=%7B%22ticketId%22:%22ticket-uuid%22%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "tracking-uuid",
        "ticket_id": "ticket-uuid",
        "policy_id": "policy-uuid",
        "first_response_due": "2024-01-15T11:00:00.000Z",
        "first_response_at": "2024-01-15T10:45:00.000Z",
        "next_response_due": "2024-01-15T12:00:00.000Z",
        "resolution_due": "2024-01-15T14:30:00.000Z",
        "resolved_at": null,
        "is_paused": false,
        "breach_status": "none",
        "policy": {
          "name": "Urgent Priority SLA",
          "first_response_time": 30,
          "next_response_time": 60,
          "resolution_time": 240
        },
        "timeRemaining": {
          "firstResponse": null,
          "nextResponse": 3420000,
          "resolution": 12300000
        }
      }
    }
  }
}

Response Fields

Field	Description
`first_response_due`	When first response must be sent
`first_response_at`	When first response was actually sent (null if not yet)
`next_response_due`	When next response is due (resets after each response)
`resolution_due`	When ticket must be resolved
`is_paused`	Whether SLA timer is currently paused
`breach_status`	`none`, `warning`, or `breached`
`timeRemaining`	Milliseconds remaining for each target (null if met)

Get Breached Tickets

List tickets that have breached or are about to breach their SLA.

Procedure: sla.getBreached

Authentication: Required

Input:

{
  includeWarnings?: boolean;  // Include tickets approaching breach (default: true)
  policyId?: string;          // Filter by specific policy
  limit?: number;             // 1-100, default: 50
}

Example:

curl -X GET "https://your-domain.com/api/trpc/sla.getBreached?input=%7B%22includeWarnings%22:true%7D" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "breached": [
          {
            "tracking": {
              "id": "tracking-uuid",
              "breach_status": "breached",
              "first_response_due": "2024-01-15T10:00:00.000Z",
              "first_response_at": null
            },
            "ticket": {
              "id": "ticket-uuid",
              "subject": "Urgent: System Down",
              "priority": "urgent",
              "status": "open"
            },
            "policy": {
              "name": "Urgent Priority SLA"
            },
            "breachType": "first_response",
            "breachDuration": 3600000
          }
        ],
        "warnings": [
          {
            "tracking": {
              "id": "tracking-uuid-2",
              "breach_status": "warning",
              "resolution_due": "2024-01-15T14:00:00.000Z"
            },
            "ticket": {
              "id": "ticket-uuid-2",
              "subject": "API Integration Issue",
              "priority": "high",
              "status": "pending"
            },
            "policy": {
              "name": "High Priority SLA"
            },
            "warningType": "resolution",
            "timeRemaining": 900000
          }
        ],
        "totals": {
          "breached": 1,
          "warnings": 1
        }
      }
    }
  }
}

Breach Types

Type	Description
`first_response`	First response time exceeded
`next_response`	Time between responses exceeded
`resolution`	Resolution time exceeded

Pause SLA Tracking

Pause the SLA timer for a ticket (e.g., waiting for customer).

Procedure: sla.pauseTracking

Authentication: Required

Input:

{
  ticketId: string;  // Ticket UUID
  reason?: string;   // Optional reason for pausing
}

Example:

curl -X POST "https://your-domain.com/api/trpc/sla.pauseTracking" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "ticketId": "ticket-uuid",
      "reason": "Waiting for customer to provide additional information"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "tracking-uuid",
        "is_paused": true,
        "paused_at": "2024-01-15T11:00:00.000Z",
        "pause_reason": "Waiting for customer to provide additional information"
      }
    }
  }
}

Notes:

SLA timers stop counting while paused
Pause duration is tracked and excluded from SLA calculations

Resume SLA Tracking

Resume a paused SLA timer.

Procedure: sla.resumeTracking

Authentication: Required

Input:

{
  ticketId: string;  // Ticket UUID
}

Example:

curl -X POST "https://your-domain.com/api/trpc/sla.resumeTracking" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"ticketId":"ticket-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "tracking-uuid",
        "is_paused": false,
        "paused_at": null,
        "total_paused_duration": 1800000,
        "first_response_due": "2024-01-15T11:30:00.000Z",
        "resolution_due": "2024-01-15T15:00:00.000Z"
      }
    }
  }
}

Notes:

Due times are adjusted by the pause duration
total_paused_duration shows cumulative pause time in milliseconds

SLA Condition Operators

Operator	Description	Example
`equals`	Exact match	`{"field": "priority", "operator": "equals", "value": "urgent"}`
`not_equals`	Not equal	`{"field": "status", "operator": "not_equals", "value": "closed"}`
`contains`	Array contains	`{"field": "tags", "operator": "contains", "value": "vip"}`
`in`	Value in list	`{"field": "priority", "operator": "in", "value": ["urgent", "high"]}`
`is_empty`	Field is null/empty	`{"field": "assignee_id", "operator": "is_empty", "value": true}`

Example SLA Policies

Urgent Priority

{
  "name": "Urgent Priority SLA",
  "conditions": [
    {"field": "priority", "operator": "equals", "value": "urgent"}
  ],
  "firstResponseTime": 30,
  "nextResponseTime": 60,
  "resolutionTime": 240,
  "priority": 100
}

VIP Customer

{
  "name": "VIP Customer SLA",
  "conditions": [
    {"field": "tags", "operator": "contains", "value": "vip"}
  ],
  "firstResponseTime": 15,
  "nextResponseTime": 30,
  "resolutionTime": 120,
  "priority": 90
}

Default/Catch-all

{
  "name": "Standard SLA",
  "conditions": [],
  "firstResponseTime": 480,
  "nextResponseTime": 1440,
  "resolutionTime": 2880,
  "priority": 0
}

SLA Breach Workflow

Ticket Created: System applies highest-priority matching SLA policy
Timer Starts: SLA clock begins counting
Warning Phase: At 80% of target time, breach_status changes to warning
Breach: If target exceeded, breach_status changes to breached
Response Sent: First response timer stops, next response timer starts
Ticket Resolved: Resolution timer stops

Automatic Pause Triggers

SLA timers can be automatically paused when:

Ticket status changes to pending (waiting for customer)
Business hours end (if configured)

Error Codes

Code	Description
`NOT_FOUND`	Policy or ticket not found
`FORBIDDEN`	Only admins can create/update/delete policies
`BAD_REQUEST`	Invalid policy configuration