Getting Started

Start with one sandbox flow: obtain a token, discover approved references, create a site and visit, read their returned IDs, and update the site using its returned ETag. A downloadable Node example performs those steps. By default it only discovers references; creating records requires an explicit flag.

Before you begin

You need:

• Node.js 24 or later and a private local working directory outside your source repository. The example has no package dependencies.
• A sandbox client_id and client_secret issued by SSN. Keep the secret in your secret manager or local process environment, never browser code or a committed file. Request credentials or missing scopes from your SSN integration contact.
• site-visits:read for reference discovery. The complete example additionally requires sites:read, sites:write, and site-visits:write.
• An active project and an item approved for your client, a new unused site code and ticket number, and explicit UTC start/due dates for the validation.

If onboarding already created a site or visit, read the existing IDs in your handoff packet first. Do not use their site code or ticket number to create them again. Coordinate a separate validation record with SSN before opting into this example's creates.

Sandbox uses separate credentials and API state from production, but its writes create retained business records and can trigger configured workflows. This example does not delete them. Agree on validation and cleanup with SSN.

Environment	Base URL
Sandbox	https://sandbox-api.siteservicesnow.com/api/v1
Production	https://api.siteservicesnow.com/api/v1

The downloadable example is fixed to sandbox and has no production override. See Environments before planning production access.

1. Download and discover references

Download quickstart.mjs into your private working directory. These commands use PowerShell 7; other shells can set the same environment variables before running Node.

Invoke-WebRequest "https://developers.siteservicesnow.com/examples/quickstart.mjs" -OutFile "quickstart.mjs"
$env:SSN_CLIENT_ID = Read-Host "Sandbox client ID"
$env:SSN_CLIENT_SECRET = Read-Host "Sandbox client secret" -MaskInput
node ./quickstart.mjs

The script requests a token using POST /api/v1/oauth/token, form-encoding grant_type=client_credentials, client_id, and client_secret. It then sends Authorization: Bearer ... to:

• GET /api/v1/projects?page[size]=100
• GET /api/v1/items?page[size]=100

Output lists the returned project IDs/names and item names. No business records are created in this mode. The token and secret are not printed or saved.

Both reference endpoints return at most 100 rows and do not offer cursor pagination. Project results are active and scoped to your client. An empty or truncated list does not authorize guessed IDs; ask SSN to confirm a reference that is not shown. The example stops if your chosen reference is absent.

2. Choose the validation inputs

Set these values from the discovery output and your agreed validation plan. Replace every YOUR_... value and both date placeholders. Do not copy another client's IDs or use Quickbase record IDs as API resource IDs.

$env:SSN_PROJECT_ID = "YOUR_PROJECT_ID_FROM_DISCOVERY"
$env:SSN_ITEM_NAME = "YOUR_EXACT_ITEM_NAME_FROM_DISCOVERY"
$env:SSN_SITE_CODE = "YOUR_NEW_UNUSED_SITE_CODE"
$env:SSN_TICKET_NUMBER = "YOUR_NEW_UNUSED_TICKET_NUMBER"
$env:SSN_START_DATE = "YYYY-MM-DDTHH:mm:ssZ"
$env:SSN_DUE_DATE = "YYYY-MM-DDTHH:mm:ssZ"
$env:SSN_JOURNAL = Join-Path $PWD "ssn-quickstart-run.json"

Use real UTC timestamps, with the due date on or after the start date. The example creates a clearly named validation site at its documented sample address, a Break / Fix validation visit, and sets the site's friendlyLocationName to Quickstart validation complete. Review the downloadable source before running it if your integration needs different business data.

The journal is a private local record of exact request bodies, idempotency keys, returned IDs, ETags, and progress. It contains no token or client secret, but may contain business information. Do not commit or share it publicly. Use a new path only for an independently agreed new run, never to bypass an uncertain result.

3. Run the create/read/update flow once

node ./quickstart.mjs --create-records

The example checks inputs and token scopes, confirms the selected references, and creates the journal without overwriting an existing file. Then it:

1. Saves a site payload and its Idempotency-Key, then calls POST /sites.
2. Captures the returned data.id and reads GET /sites/{id} to obtain data.meta.etag.
3. Creates a visit using your site's siteCode as clientSiteId, with a different persisted Idempotency-Key.
4. Captures the returned visit data.id and reads GET /site-visits/{id}.
5. Reads the site again for its latest ETag, patches it with that exact quoted If-Match value, then reads it once more to confirm the update.

Success output contains siteId, siteVisitId, the updated siteEtag, and the journal path. Use those returned values in your integration; do not substitute sample IDs or invent an ETag. The records remain in sandbox after success.

Value	Use
Your siteCode	The visit's clientSiteId; unique within your client account.
Site response data.id	API site URL /sites/{id}.
Visit response data.id	API visit URL /site-visits/{id} and a message's siteVisitId.
Project data.id / item data.id	Visit projectId / itemName, respectively.
Resource data.meta.etag	Preserve its quotation marks when sending If-Match.
Your clientTicketNumber	Your visit reference; keep it unique for your client.

If the example stops

The example makes no automatic retries. It records write intent before each business request; a lost response, timeout, or crash leaves the outcome uncertain. Even an error status is not permission to submit a new create.

• Keep the journal and known IDs. Ask SSN to reconcile the original operation. Do not rerun with new keys, codes, tickets, or a different journal to get past the failure. Completed-key replay protection is not permanent.
• A 409 from PATCH stops the flow. Read the current resource and reconcile the desired change before another update. If-Match currently checks a version separately from the upstream write; it does not safely serialize simultaneous writers. Avoid concurrent updates to the same resource.
• For 401/403, check credentials and granted scopes. For validation or reference failures, correct the inputs before any business write. If records were already created, recover that run instead of starting another.

See operation-specific retry guidance for pending/expired create keys, version conflicts, uploads, and subscriptions. After finishing, remove SSN_CLIENT_SECRET from the shell environment when it is no longer needed:

Remove-Item Env:SSN_CLIENT_SECRET

Rate Limits and Bulk Imports

This example creates one site and one visit; it is not a bulk importer. Review Rate Limits and Bulk Imports before adding concurrency or loading many records. Persist one exact body and idempotency key per create operation, and honor the operation-specific retry rules.

Continue with your integration

Use End-to-End Examples to extend existing records. Separate guides cover Sites, Site Visits, Messages, File Uploads, and Webhooks. Asset assignment, messages, files, and webhook setup are optional and are intentionally outside the first-success script.