CloudAPI - API Documentation

🏠 Home › BuildingServices / CloudAPI / docs

CloudAPI - API Documentation

Overview

Authentication & Authorization

All endpoints require: 1. A valid JWT Bearer token in the Authorization header 2. Token claims include: PersonId, DisplayName, Account, Persona 3. Persona-based access control via base controller validation

Persona Description
DirectSupplyPartner Internal/partner administrative access
ServiceProvider Service provider access
Customer Customer-level access

Some endpoints require specific roles: - CustomerGlobalAdministrator - Bypass facility-level access checks

Global Response Codes

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

ComplexPriorityScore

Method Path Auth Description
POST /projects/{authorizationNumber}/commands/calculateComplexPriorityScore Partner Calculate complex priority score for a project using Databricks metrics
POST /bidRequests/{authorizationNumber}/commands/calculateComplexPriorityScore Partner Calculate complex priority score for a bid request
GET /projects/{authorizationNumber}/complexPriorityScore Partner Get calculated complex priority score for a project
GET /bidRequests/{authorizationNumber}/complexPriorityScore Partner Get calculated complex priority score for a bid request
POST /complexPriorityScore/commands/renormalizeScores Partner Batch renormalize all complex priority scores to 0-100 range

CalculateComplexPriorityScore returns ComplexProjectPriorityScoreDTO containing: - Normalized score (0-100) - Raw metrics (win rates, spend patterns, provider counts, etc.) - Databricks-sourced analytics

Diagnostics

Method Path Auth Description
GET /cloudapi/diagnostics/flushCache Partner Flush distributed cache by publishing FlushCacheRequest message
GET /cloudapi/health None Health check endpoint
GET /cloudapi/version None Get API version info

DispatchList

Method Path Auth Description
GET /dispatchList/exports/raw Partner, Provider, Customer Export dispatch list in raw format with all fields
GET /dispatchList/exports/dailyDashboard Partner Export dispatch list for daily dashboard view
GET /dispatchList/exports/dispatchListForServiceProvider Partner, Provider Export dispatch list filtered for service provider
GET /dispatchList/exports/dispatchListForCustomer Partner, Customer Export dispatch list filtered for customer
POST /dispatchList/commands/syncDispatchList Partner Trigger dispatch list sync from SQL Server to PostgreSQL

Query Parameters (common across export endpoints): - pageSize (int?) - Number of records per page - pageNumber (int?) - Page number (1-indexed) - workRequestTypes (int[]?) - Filter by work request type IDs - severities (string[]?) - Filter by severity codes - statuses (string[]?) - Filter by status codes - serviceCodes (int[]?) - Filter by service codes - sort (string?) - Sort field and direction (e.g., "priority desc") - Plus additional filters for dates, locations, contacts, etc.

Returns: PagedResponse<DispatchListItem> with pagination metadata

NoteChecker

Method Path Auth Description
GET /noteChecker/configurations Partner Get all note checker configurations
POST /noteChecker/configurations Partner Create new note checker configuration
PATCH /noteChecker/configurations Partner Update existing note checker configuration
POST /noteChecker/checkNote Partner, Provider Validate note content against configured patterns

NoteCheckerRequest: { "note": "string", "organizationId": 123 }

NoteCheckerResponse: Returns list of matched phrases with violation details

Permits

Method Path Auth Description
GET /fulfillments/{authorizationNumber}/permits Partner, Provider, Customer Get permits for a fulfillment
POST /fulfillments/{authorizationNumber}/permits Partner, Provider Create a new permit
PUT /fulfillments/{authorizationNumber}/permits/{permitId} Partner, Provider Update an existing permit
DELETE /fulfillments/{authorizationNumber}/permits/{permitId} Partner, Provider Delete a permit

Query Parameters: - includeInactive (bool) - Include inactive permits in results

Access Control: Requires fulfillment-level access validation in addition to persona check

PropensityToWinScore

Method Path Auth Description
POST /projects/{authorizationNumber}/commands/calculatePropensityToWinScore Partner Trigger ML model prediction for propensity-to-win (async via MQ)
GET /projects/{authorizationNumber}/propensityToWinScore Partner Get stored propensity-to-win score

Query Parameters (GET): - modelVersion (string?) - Specific model version to retrieve (defaults to latest) - backfill (bool) - When POSTing, whether to use backfill endpoint (default false)

Returns: ProjectPropensityToWinScoreDTO containing prediction score and metadata

WorkItemBatch

Note: Hidden from API documentation (IgnoreApi = true)

Method Path Auth Description
POST /workItemBatch/cintasBatch Partner Create a new Cintas batch
POST /workItemBatch/cintasBatch/{batchId}/records Partner Add records to an existing Cintas batch

CintasBatchCreationInfo: { "fileName": "string", "recordVersion": "string" }

WorkItemDescriptions

Method Path Auth Description
GET /bidRequests/{authorizationNumber}/workItemDescriptionsHistory Partner Get work item description history for a bid request
GET /serviceRequests/{authorizationNumber}/workItemDescriptionsHistory Partner Get work item description history for a service request
GET /projects/{authorizationNumber}/workItemDescriptionsHistory Partner Get work item description history for a project
GET /fulfillments/{authorizationNumber}/workItemDescriptionsHistory Partner Get work item description history for a fulfillment
GET /contractedServices/{authorizationNumber}/workItemDescriptionsHistory Partner Get work item description history for a contracted service

Query Parameters: - updateType (string?) - Filter by update type: "InternalNote" or "WorkCompletedOnSite" (case-insensitive)

Validation: - authorizationNumber must be > 0 - updateType if provided must be "InternalNote" or "WorkCompletedOnSite"

Returns: WorkItemDescriptionsHistory with chronological list of updates

WorkItems

Method Path Auth Description
POST /workItems/queries/byCustomerContactPersonId Partner Get open work items for a customer contact person

OpenWorkItemsByContactPersonIdRequest: { "personId": 123, "includeSecondaryContacts": true }

Returns: OpenWorkItemsByContactPersonIdResponse with list of work items

Key Data Contracts

ComplexProjectPriorityScoreDTO

{
  "authorizationNumber": 12345,
  "workRequestTypeId": 1,
  "normalizedScore": 85.5,
  "winRateForSimilarProjectsInMarket": 0.65,
  "numberOfPotentialServiceProvidersInMarket": 12,
  "amountOfContractsInPlaceForBuilding": 5,
  "districtManagerConfiguredForMarket": true,
  "buildingHistoricAnnualSpend": 250000.00,
  "chainHistoricAnnualSpend": 1500000.00,
  "ownerHistoricAnnualSpend": 3000000.00,
  "buildingProjectWinRate": 0.72,
  "chainProjectWinRate": 0.68,
  "ownerProjectWinRate": 0.70,
  "chainPercentSpend": 0.45,
  "ownerPercentSpend": 0.38,
  "isOwnedByWelltowerOrVentas": false,
  "isCoreMarket": true
}

DispatchListItem

Includes: authorization_code, work_order_id, work_request_type, severity, status, facility info, service details, priority scores, propensity-to-win score, dates, contacts, etc.

NoteCheckerConfiguration

{
  "id": 1,
  "organizationId": 123,
  "phrasesToCheck": ["phrase1", "phrase2"],
  "isActive": true,
  "createdDate": "2024-01-01T00:00:00Z"
}

Permit

{
  "permitId": 1,
  "authorizationNumber": 12345,
  "permitNumber": "PERMIT-12345",
  "permitType": "Building",
  "applicationNumber": "APP-67890",
  "applicationDate": "2024-01-01",
  "issuedDate": "2024-01-15",
  "expirationDate": "2025-01-15",
  "isActive": true
}

ProjectPropensityToWinScoreDTO

{
  "authorizationNumber": 12345,
  "predictionScore": 0.78,
  "modelVersion": "v2.1",
  "predictionDate": "2024-01-01T12:00:00Z"
}

Pagination

List endpoints support pagination: - pageSize (int) - Number of results per page - pageNumber (int) - 1-indexed page number

Response includes:

{
  "data": [...],
  "pageNumber": 1,
  "pageSize": 50,
  "totalRecords": 500,
  "totalPages": 10
}

Swagger Tags

Endpoints are grouped by work request type: - BidRequests - Bid request operations - ServiceRequests - Service request operations - Projects - Project operations - Fulfillments - Fulfillment operations - ContractedServices - Contracted service operations - DispatchList - Dispatch list exports and sync - NoteChecker - Note validation - Diagnostics - Health and cache management

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