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

List responses support page[size] and page[after]. When more records are available, use meta.nextCursor as the next page[after] value.

GET /api/v1/site-visits?page[size]=25
Authorization: Bearer YOUR_ACCESS_TOKEN

Create requests should include a unique Idempotency-Key. Reuse the same key only when retrying the same request body after a timeout or transient failure.

POST /api/v1/site-visits
Authorization: Bearer YOUR_ACCESS_TOKEN
Idempotency-Key: import-2026-05-14-visits-row-000123
Content-Type: application/json

{
  "clientSiteId": "DEMO-STORE-100",
  "description": "Replace damaged kiosk screen",
  "clientTicketNumber": "CLIENT-TKT-10027",
  "serviceType": "Break / Fix",
  "jobInstructions": "Check in with store manager before opening the equipment.",
  "projectId": 123,
  "itemName": "TEST ITEM",
  "startDate": "2026-04-15T16:00:00Z",
  "dueDate": "2026-04-16T01:00:00Z",
  "arePartsRequired": false,
  "partsReturnRequired": false,
  "schedulingRule": "Date/Time Specific"
}

GET /site-visits/{id} responses include an ETag header. Send that value in If-Match when patching a visit.

PATCH /api/v1/site-visits/visit_123
Authorization: Bearer YOUR_ACCESS_TOKEN
If-Match: "1"
Content-Type: application/json

{
  "clientTicketNumber": "CLIENT-TKT-10027-UPDATED"
}

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.

Bulk import behavior

Site visits are created one record at a time with POST /api/v1/site-visits. The API does not currently accept an array of site visits or an import file.

Client API requests are limited to 100 requests per minute. For imports of 1000 or more site visits, throttle the import below that limit, send a unique Idempotency-Key for each POST, and retry 429 or transient upstream errors with backoff.

See Rate Limits and Bulk Imports for the full import guidance.

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. They are capped lookup lists: use page[size] up to 100 to limit the response, but do not use cursor pagination. These endpoints do not return meta.nextCursor.

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.

See the API Reference for the full site-visit request and response schemas.