Skip to main content

Site Visits

Site visits represent work orders or jobs at a site.

Create site visits with clientSiteId, which should match the site siteCode.

Important fields:

  • clientSiteId
  • description
  • clientTicketNumber
  • projectId
  • itemName
  • serviceType
  • startDate
  • dueDate
  • schedulingRule
  • optional siteAssetIds

Assigned site assets are returned in two forms:

  • assetsToService: human-readable summary of the assigned assets
  • siteVisitAssets: detailed child rows for each assigned site asset

Site asset assignment is governed by Site Visits scopes. Use site-visits:write to submit siteAssetIds, and site-visits:read to read assetsToService and siteVisitAssets. Site assets and site visit assets do not have separate client-facing scopes.

Project and item discovery​

Use the reference-data endpoints before creating a site visit when you need the current valid projectId or itemName values for your client account.

Both endpoints require the site-visits:read scope.

GET /api/v1/projects
GET /api/v1/items

GET /api/v1/projects returns active projects that can be used as the projectId value on a site visit.

{
  "data": [
    {
      "id": "123",
      "type": "projects",
      "attributes": {
        "projectId": 123,
        "projectName": "TEST PROJECT",
        "status": "Active"
      },
      "meta": {
        "quickbaseRecordId": "123"
      }
    }
  ],
  "meta": {
    "pageSize": 100
  }
}

GET /api/v1/items returns items that can be used as the itemName value on a site visit.

{
  "data": [
    {
      "id": "TEST ITEM",
      "type": "items",
      "attributes": {
        "itemName": "TEST ITEM",
        "itemId": 98
      },
      "meta": {
        "quickbaseRecordId": "98"
      }
    }
  ],
  "meta": {
    "pageSize": 100
  }
}

Example asset payload:

{
  "assetsToService": "TestUnit0002 - Entry Vestibule; TestUnit0001 - Backroom",
  "siteVisitAssets": [
    {
      "siteVisitAssetId": 123,
      "siteAssetId": 457,
      "uniqueId": "TestUnit0002",
      "friendlyLocation": "Entry Vestibule",
      "assetStatus": "Active",
      "assetDisplay": "TestUnit0002 - Entry Vestibule"
    },
    {
      "siteVisitAssetId": 124,
      "siteAssetId": 456,
      "uniqueId": "TestUnit0001",
      "friendlyLocation": "Backroom",
      "assetStatus": "Active",
      "assetDisplay": "TestUnit0001 - Backroom"
    }
  ]
}

Business rules:

  • clientSiteId must resolve to one of your sites.
  • projectId must belong to your client account and be active.
  • itemName must belong to your client account.
  • use GET /api/v1/projects and GET /api/v1/items with site-visits:read to discover current valid values.
  • clientTicketNumber should be unique for your client account.
  • each siteAssetId must belong to the same site as the site visit
  • omitting siteAssetIds on patch leaves assignments unchanged
  • sending siteAssetIds: [] clears assigned assets

Legacy site-level fields such as uniqueID, uniqueID2, friendlyLocationName, and friendlyLocationName2 remain on Sites for backward compatibility, but they are not the source of truth for asset assignment on site visits.