Sandbox validation

ServiceTitan sandbox validation protocol.

A no-access test protocol for the API and partner review work PageToJob must complete before claiming ServiceTitan sync, imports, webhooks, or closed-loop attribution.

Protocol summary
7
test cases
5
need sandbox
2
blocked no access
5
blocked claims
This page is a protocol, not evidence. It must not be used to claim live ServiceTitan access, sync, webhooks, or marketplace approval.

Sandbox test protocol

Authorized tenant token exchange

auth
blocked no access

Prove app key handling, tenant authorization, token lifecycle, rotation, and disconnect behavior without exposing secrets.

Setup required
  • - Approved ServiceTitan app or sandbox app
  • - Sandbox tenant or approved customer tenant
  • - Customer/admin authorization path
  • - Encrypted token reference design
Validation steps
  1. 1. Request token through the approved app flow.
  2. 2. Record token metadata without logging secrets.
  3. 3. Refresh or rotate credentials according to the approved lifecycle.
  4. 4. Disconnect the tenant and confirm API-backed flags are disabled.
Expected evidence
App approval referenceSandbox tenant referenceToken metadata onlyDisconnect timestampDisabled API flags
Failure must prove
  • - Token secrets are never logged
  • - Manual website mode remains active
  • - Disconnected tenants cannot run API jobs
PageToJob has validated a secure connection lifecycle only after sandbox evidence exists.

Read-only taxonomy import

import
needs sandbox

Prove job types, business units, campaigns, zones, memberships, and pricebook references can be imported with source labels and review state.

Setup required
  • - Granted read scopes for eligible modules
  • - Known test records in sandbox
  • - Rate-limit expectations
  • - Manual Titan Map comparison baseline
Validation steps
  1. 1. Import each approved taxonomy family separately.
  2. 2. Store source family, external ID, active state, display name, and synced timestamp.
  3. 3. Compare imported rows to the manual Titan Map.
  4. 4. Create review findings instead of changing public pages automatically.
Expected evidence
Imported row samplesScope-to-family mapSynced timestampsReview findingsNo automatic public edits
Failure must prove
  • - Missing scopes block that family only
  • - Stale imports do not overwrite reviewed mappings
  • - Rate limits create operator-visible retry state
Read-only imports can support reviewable mapping coverage after scopes and sandbox behavior are proven.

Booking or lead handoff with idempotent retry

handoff
needs sandbox

Prove queued website requests can create or update approved ServiceTitan records without duplicate writes or lost leads.

Setup required
  • - Durable booking_requests and servicetitan_syncs tables
  • - Approved CRM or booking endpoint
  • - Mapped job type, business unit, campaign, and source context
  • - Notification fallback recipient
Validation steps
  1. 1. Submit a sandbox booking request with source context.
  2. 2. Create a sync queue item with an idempotency key.
  3. 3. Process the handoff asynchronously.
  4. 4. Retry one transient failure.
  5. 5. Record external IDs and final state.
Expected evidence
Local lead IDBooking request IDIdempotency keyAttempt logExternal IDNotification fallback proof
Failure must prove
  • - Duplicate submissions do not create duplicate records
  • - Failed sync leaves manual fallback active
  • - Last error is visible to an operator
Website leads remain safe during ServiceTitan handoff because local capture and fallback notification stay active.

Webhook verification and replay rejection

webhook
blocked no access

Prove unsigned, stale, duplicate, malformed, and unknown webhook events are rejected before processing.

Setup required
  • - ServiceTitan webhook signing specification
  • - Raw body verification implementation
  • - Webhook event persistence
  • - Replay window policy
Validation steps
  1. 1. Send a valid signed sandbox event.
  2. 2. Send unsigned and stale variants.
  3. 3. Replay a duplicate event ID.
  4. 4. Send malformed payload and unknown event type.
  5. 5. Confirm only valid events enter processing.
Expected evidence
Signature verification resultReplay rejection logDuplicate event IDMalformed payload rejectionProcessing state
Failure must prove
  • - Rejected events do not mutate local state
  • - Unknown events are retained only as safe diagnostics
  • - Manual lead/proof paths remain active
Webhook-driven automation is not enabled until rejection behavior is validated in sandbox.

Outcome and revenue match quality

outcome
needs sandbox

Prove website leads can be matched to bookings, jobs, invoices, payments, campaigns, and revenue only where source and confidence are visible.

Setup required
  • - Approved outcome, job, invoice, or payment access
  • - Known sandbox lead-to-job scenarios
  • - Campaign/source bindings
  • - Match-quality labels
Validation steps
  1. 1. Create sandbox leads from mapped campaign pages.
  2. 2. Match candidate booking/job/invoice records.
  3. 3. Label records matched, unmatched, or needs-review.
  4. 4. Exclude uncertain records from revenue totals.
Expected evidence
Source URLUTM fieldsCandidate external IDsMatch-quality labelExcluded revenue list
Failure must prove
  • - Unmatched records are not counted as revenue
  • - Missing invoice IDs create needs-review state
  • - Customer proof shows source and exclusions
Closed-loop revenue is only claimed when match quality and source fields are visible.

Disconnect, deletion, and token cleanup

disconnect
needs sandbox

Prove customer disconnect disables API-backed automation and removes or revokes token references while manual website operation continues.

Setup required
  • - Connected sandbox tenant
  • - Encrypted token reference
  • - Tenant feature flags
  • - Retention and deletion policy
Validation steps
  1. 1. Disconnect the tenant.
  2. 2. Disable API-backed feature flags.
  3. 3. Revoke or remove encrypted token references.
  4. 4. Attempt a blocked API job and confirm it cannot run.
  5. 5. Verify manual website and notification fallback still work.
Expected evidence
Disconnect timestampDisabled flagsToken cleanup recordBlocked API jobManual fallback proof
Failure must prove
  • - Disconnected tenants cannot process API jobs
  • - Public site remains live
  • - Support runbook state is recorded
A disconnect pauses automation without taking down the website or losing lead capture.

Rate limit, timeout, and retry behavior

rate-limit
needs sandbox

Prove ServiceTitan API failures become bounded retries and operator-visible states instead of duplicate writes or blocked visitors.

Setup required
  • - Known ServiceTitan rate-limit behavior
  • - Retry and timeout policy
  • - Durable sync queue
  • - Operator error view
Validation steps
  1. 1. Trigger a rate-limit or simulated transient response.
  2. 2. Record attempt count and next retry time.
  3. 3. Stop retrying when authorization, mapping, or validation is missing.
  4. 4. Expose the last error and next action to the operator.
Expected evidence
Rate-limit responseAttempt countNext retry timestampLast errorOperator action
Failure must prove
  • - Non-deterministic errors do not retry forever
  • - Missing authorization blocks sync
  • - Idempotency keys are preserved across retries
Retries are bounded, idempotent, and visible before API-backed handoff is sold.

Evidence rules

Never capture secrets in evidence

Screenshots, logs, packets, and demos may show token metadata, timestamps, and status, but never app keys, tokens, client secrets, or tenant credentials.

Failure evidence is required

Every sandbox test must prove both the happy path and at least one safe failure path before the feature flag can move out of gated status.

Proof needs source and quality labels

Outcome, revenue, import, and sync evidence must show source family, source timestamp, match quality, and customer review state.

Manual fallback stays active

A passing sandbox test cannot disable the no-API lead capture, notification fallback, Titan Map review, or support runbooks.

Activation gates

Customer authorization

Manual product can run without ServiceTitan authorization.

Customer admin identifiedEligible modules confirmedScopes grantedDisconnect owner assigned

Secure token storage

Offline product stores no ServiceTitan credentials or tokens.

Encrypted token referencesRotation policyDeletion policyAudit logging

Durable queue and operator state

Sync queue is modeled offline.

Database queueIdempotency persistenceRetry windowsLast-error operator view

Customer-facing claim review

Copy uses ServiceTitan-ready and manual-first language.

Approved feature flagSandbox evidenceSupport runbookUpdated disclaimer

Claims still blocked

  • - Live ServiceTitan tenant connection
  • - Automatic lead, booking, job, invoice, payment, or pricebook sync
  • - Webhook-driven Scheduling Pro processing
  • - Closed-loop revenue attribution from live ServiceTitan data
  • - Marketplace or partner approval

Validation disclaimers

  • - This is an offline validation protocol, not sandbox evidence.
  • - No ServiceTitan credentials, tokens, app keys, webhooks, or API calls are used by this plan.
  • - API-backed claims require approved app access, customer authorization, eligible modules, granted scopes, secure token storage, durable persistence, and passing sandbox evidence.
  • - PageToJob is not affiliated with or endorsed by ServiceTitan.