Skip to main content

End-to-End Examples

For a complete runnable first flow, use Getting Started and its Node quickstart.mjs example. It carries actual returned IDs and ETags through authentication, reference discovery, site/visit creation, reads, and a conditional site update.

The workflows below extend existing records. They are request templates, not a second sequence to run blindly. Use your environment's base URL ending in /api/v1, a fresh bearer token, and the exact IDs from earlier responses. These operations can change retained business records.

Assign assets to an existing visit​

Prerequisites:

  • site-visits:read and site-visits:write scopes; no separate asset scope exists.
  • An API visit ID returned as data.id by a prior visit create/read.
  • Site Asset IDs confirmed by SSN to belong to that visit's site. They are not interchangeable with the API visit ID or the returned Site Visit Asset child IDs.

Read the visit first:

GET /api/v1/site-visits/YOUR_RETURNED_VISIT_ID
Authorization: Bearer YOUR_ACCESS_TOKEN

Save its data.meta.etag, including the quotation marks, and inspect its current siteVisitAssets. Send the complete desired assignment list with that ETag. Replace the illustrative asset ID 457 with your confirmed Site Asset ID:

PATCH /api/v1/site-visits/YOUR_RETURNED_VISIT_ID
Authorization: Bearer YOUR_ACCESS_TOKEN
If-Match: YOUR_RETURNED_QUOTED_ETAG
Content-Type: application/json

{"siteAssetIds":[457]}

Read the same API visit ID again and inspect assetsToService and siteVisitAssets to confirm the result. Omitting siteAssetIds leaves assignments unchanged; an empty list clears them. A cross-site assignment is rejected with 409. On any failed or uncertain update, reconcile before retrying. The current If-Match implementation does not serialize simultaneous writers.

See Site Visits for the assignment contract and retry guidance for conflict handling.

Add a message to that visit​

Use messages:write and the API visit ID from data.id as siteVisitId. Choose and persist a new unique idempotency key and the exact request body before sending. This example's enum values are valid, but replace the visit placeholder and write the message appropriate to your workflow:

POST /api/v1/messages
Authorization: Bearer YOUR_ACCESS_TOKEN
Idempotency-Key: YOUR_NEW_PERSISTED_MESSAGE_KEY
Content-Type: application/json

{
  "siteVisitId":"YOUR_RETURNED_VISIT_ID",
  "type":"Support",
  "messageThread":"Integration validation message agreed with SSN.",
  "status":"Open",
  "urgency":"Normal – Standard priority / routine handling"
}

Capture the returned message data.id. With messages:read, use it in GET /api/v1/messages/{id}. A lost create response requires the same-key/body reconciliation rules; never change the key simply to bypass a pending result. See Messages for writable fields and behavior.

Add files or event notifications​

  • File Uploads explains multipart field file, supported resource IDs/types, and limits. Uploads do not share resource-create idempotency.
  • Webhooks explains registration scopes, allowed receiver URLs, signature verification, durable acknowledgment, and delivery recovery.
  • API Reference lists the full endpoint contract.