TicketExceptions - API Documentation

🏠 Home › BuildingServices / TicketExceptions / docs

TicketExceptions - API Documentation

Overview

Authentication & Authorization

Standard Endpoints: - JWT Bearer token required - Persona: DirectSupplyPartner (most endpoints) - Claims extracted: PersonId, DisplayName, Account, Persona

Public Integration Endpoints: - JWT Bearer token required (Zendesk integration account) - No persona restriction

Global Response Codes

Code Meaning
200 Success
201 Created
204 No Content (successful update)
400 Bad Request (validation error)
401 Unauthorized (missing/invalid token)
403 Forbidden (persona mismatch)
404 Not Found

Diagnostics

Route Prefix: ticketExceptions/v1/diagnostics

Method Path Auth Description
GET /unhandledErrorTest Partner Throw exception for testing error reporting
GET /pendingTriggers/{authorizationNumber} Partner Get pending Quartz triggers by authorization number. Query: messageTypeContains (filter by message type)
POST /pendingTriggers/commands/fireNow Partner Fire trigger immediately (non-production only). Query: triggerName

Returns (GET pendingTriggers):

{
  "triggers": [
    {
      "triggerName": "string",
      "nextFireTime": "2024-01-01T12:00:00Z",
      "messageType": "string"
    }
  ]
}

Integrations (Public)

Route Prefix: ticketExceptions/public/v1

Method Path Auth Description
PATCH /ticketExceptions/commands/updateStatus JWT Required Update ticket exception status from Zendesk webhook

TicketExceptionStatusUpdateRequest:

{
  "externalSystemIdentifier": "zendesk",
  "externalReferenceId": "12345",
  "status": "solved",
  "comment": "Customer issue resolved"
}

Response Codes: 204 (Success), 400 (Validation), 403 (Forbidden), 404 (Not Found)

Ticket Exception Rules

Route Prefix: ticketExceptions/v1/rules

Method Path Auth Description
GET /rules/{ruleId} Partner Get single exception rule by ID
GET /rules Partner List exception rules with pagination. Query: pageKey, includeInactive (bool)
PATCH /rules/{ruleId} Partner Update exception rule

TicketExceptionRule (GET response):

{
  "id": 1,
  "isActive": true,
  "exceptionTypeId": 5,
  "exceptionTypeName": "ETA_MISSING",
  "description": "Service provider has not provided ETA"
}

TicketExceptionRuleUpdateRequest (PATCH body):

{
  "isActive": false,
  "description": "Updated description"
}

GetTicketExceptionRulesResponse (paginated list):

{
  "ticketExceptionRules": [...],
  "pageKey": "next-page-token"
}

Ticket Exceptions

Route Prefix: ticketExceptions/v1/ticketExceptions

Method Path Auth Description
GET /ticketExceptions/{ticketExceptionId} Partner Get single ticket exception by ID
GET /ticketExceptions Partner List ticket exceptions with filtering

Query Parameters (GET list): - pageKey (string) - Pagination cursor - authorizationNumber (int?) - Filter by work item authorization number - requestType (int?) - Filter by work request type - serviceProviderId (int?) - Filter by service provider - includeClosedExceptions (bool, default false) - Include solved exceptions - externalReferences (string[]?) - Filter by external reference IDs (Zendesk ticket IDs)

TicketException (response):

{
  "id": 123,
  "subject": "Missing ETA for Work Item #45678",
  "comment": "Service provider has not provided ETA as of [timestamp]",
  "tbsWorkItemAuthorizationNumber": "45678",
  "tbsWorkItemRequestType": 1,
  "ticketExceptionTypeId": 5,
  "ticketExceptionTypeName": "ETA_MISSING",
  "ticketExceptionCreated": true,
  "isConsideredSolvedByTbs": false,
  "serviceProviderId": 9876,
  "externalReferences": [
    {
      "domain": "zendesk",
      "type": "ticket",
      "identifier": "ZDTICKET-12345"
    }
  ]
}

GetTicketExceptionsResponse (paginated list):

{
  "ticketExceptions": [...],
  "pageKey": "next-page-token"
}

Call-to-Actions

Route Prefix: ticketExceptions/v1/callToActions

Method Path Auth Description
GET /callToActions Partner List all call-to-actions
GET /callToActions/{callToActionId} Partner Get single call-to-action by ID
POST /callToActions Partner Create new call-to-action
PATCH /callToActions/{callToActionId} Partner Update call-to-action

CallToAction (response):

{
  "id": 1,
  "exceptionTypeIdentifier": "ETA_MISSING",
  "templateForDayside": "Please provide ETA within 2 hours",
  "templateForAfterHours": "Please provide ETA by next business day",
  "templateForWestpark": "Westpark team - follow standard escalation",
  "tbsWorkItemRequestType": 1,
  "priority": 5
}

CallToActionCreateRequest (POST body):

{
  "exceptionTypeIdentifier": "NEW_EXCEPTION_TYPE",
  "templateForDayside": "Template text for dayside",
  "templateForAfterHours": "Template text for after hours",
  "templateForWestpark": "Template text for westpark",
  "tbsWorkItemRequestType": 1,
  "priority": 10
}

CallToActionUpdateRequest (PATCH body):

{
  "templateForDayside": "Updated template",
  "templateForAfterHours": "Updated after hours template",
  "templateForWestpark": "Updated westpark template",
  "priority": 8
}

CallToActionsResponse (list all):

{
  "callToActions": [...]
}

Service Provider Escalation

Route Prefix: ticketExceptions/v1/serviceProviderEscalationCandidates

Method Path Auth Description
GET /serviceProviderEscalationCandidates Partner Get service providers eligible for escalation notifications

ServiceProviderEscalationCandidatesResponse:

[
  {
    "serviceProviderId": 123,
    "serviceProviderName": "Example SP Inc",
    "openExceptionCount": 5,
    "oldestExceptionDate": "2024-01-01T00:00:00Z"
  }
]

Error Responses

All error responses follow the pattern:

{
  "errorCode": "string",
  "message": "string",
  "errors": {
    "field": ["error1", "error2"]
  }
}

Common error codes: - ValidationFailed - Request validation error - Unauthorized - Authentication required - Forbidden - Insufficient permissions - NotFound - Resource not found - InternalServerError - Unexpected error

Notes