Sandbox & testing

Sandbox workspaces#

A sandbox is a separate TruTec workspace for your company, set up for building and testing an integration. It comes with sample data so every endpoint returns something real-shaped on day one:

• customers and sites,
• jobs at different stages, with photos,
• estimates with line items, versions and proposal status,
• job costs and invoices,
• at least one measured parking lot.

The sandbox uses the same base URL and the same API as production. Its keys can only see sandbox data, so test code can never read or change your real records, and your team's day-to-day work never shows up in your tests.

To get one, email [email protected] or ask your TruTec contact. Tell us who should be an owner of the sandbox (owners create its keys) and what you're building, and we'll load data that fits.

Live mirror of your workspace#

We can also set your sandbox to keep copying your real workspace, so you build against the same setup and the same kind of records your team works with every day. Ask your TruTec contact to turn it on.

• What's copied: your setup (job types, pick lists, job-creation rules and requirement questions, custom fields, proposal content, request forms and lead routing) and your live records: companies, contacts, sites and jobs, including each job's company, site, contacts, value, source and stage. Stage changes and archived records follow.
• Estimates: every estimate on a copied job, with its areas, line items, cost lines and every issued version. The numbers are exactly the ones your real workspace priced, so GET /v1/estimates/{id} (and ?version=N, /versions, line items) reads the same totals and lines your team sees. A new version, a status change, an award or an archive follows; a line deleted in your real workspace is removed from the copy too. Opening a copied estimate in the sandbox app re-prices it with the sandbox's catalog until the real one changes again.
• Estimating catalog: copied once, the first time the mirror runs, and only added to: nothing already in the sandbox changes, and a service the sandbox already has by name stays the sandbox's own. Services you add to your real catalog later are not copied (their estimate lines still are).
• How often: about every 10 minutes. The first copy of a large workspace arrives over the first few runs.
• One way only: nothing you do in the sandbox ever flows back to your real workspace. A change you make to a copied record stays until the same record changes in your real workspace, and then the real values win.
• Your sandbox design stays: the sandbox keeps its own pipeline columns, pipeline automation and lead inbox setting. Copied jobs land in the matching column, or the sandbox's first column of the same kind (a real "Lead" job lands in the first deal column).
• Masked contact details: copied emails end in @mirror.invalid (an address that can never be delivered) and phone numbers are fictional +1 555-555-01xx numbers, so a test can never reach a real customer. Email addresses and phone numbers inside notes are masked the same way.
• Copied jobs belong to the sandbox owner. No user logins are copied.
• IDs differ. Each copied company, site and job has the external reference mirror:<id in your real workspace>, and every copied record (contacts too) carries _mirror_source_id in its custom fields. Match on those, or set your own external reference on a copied record and match on that: the copy keeps finding the record either way. A copied estimate keeps its document number when the sandbox isn't already using it.
• Webhooks: the first copy is history and sends no events. After that, copied jobs send the same events as jobs created or moved in the sandbox (job_created, job_status_changed, job_won, ...), and copied estimates send estimate_created, estimate_issued (first version), estimate_revised (each later version), estimate_approved and estimate_declined. Point the sandbox's webhooks at a test HubSpot portal, never your real one: the copies are your real deals.
• Not copied: proposals (so no proposal_* events for copied estimates), an estimate's edit history (/revisions is empty on a copy) and its takeoff links, notes and activity, files, photos and takeoffs. Records deleted in your real workspace stay in the sandbox.

Going to production#

1. Build and test with a sandbox key.
2. Create a key in your production workspace (Settings › API keys) (ask us to make it read-only if your integration only reads).
3. Swap the key in your production config. Nothing else changes.

IDs differ between the sandbox and production, so don't copy IDs between them. Match records by your own reference instead: jobs, customers and sites accept an external reference for exactly this (Jobs).

Testing tips#

• Each measurement runs a real AI takeoff, in the sandbox too. Measure a few sites once and reuse their job_id: reading a finished result again is free (Measure a site).
• Test webhooks against a request inspector first, then your own endpoint. The delivery log and replay endpoints let you resend anything you missed (Webhooks & events).
• Prefix test records you create (for example an external reference starting test-) so they are easy to find and remove.
• Point your AI assistant at the sandbox first. The MCP server uses the same keys, so a sandbox key gives the assistant sandbox data only.

Partner dev keys#

Software platforms using the Partner API can also get a partner dev key, which is limited to partner sandbox flows. See Partner API for what it can and can't do.