The sandbox is not a mock. Every test address delivers a real roof, recorded from a real property and run through the same parser and PDF renderer a live order uses. What is scripted is the timing, so you can watch a complete order lifecycle in seconds instead of hours. The reference is the sandbox scenarios endpoint.
How is a scenario chosen?
By the address you order. With a sandbox key, matching a published test address exactly, or
by coordinates within about 110 metres, runs that scenario's timeline. Any address not on
the list runs the cancelled timeline. There is no address that turns a sandbox
order into a real one, and no header or body field that forces a scenario. A sandbox
request and a live request are the same request; only the key differs.
The list is published in-band, so your code can discover it without leaving the API:
curl -H "Authorization: Bearer rq_test_sk_..." \
"https://api.roofquery.com/api/v1/reports/sandbox/scenarios"What do the scenarios cover?
| Scenario | What happens | What it tests |
|---|---|---|
| Happy path | processing, in-progress, completed over about 20 seconds. A residential roof with files. | The normal flow, file downloads, parsing |
| Happy path, commercial | Same timeline on a recorded flat roof. | Parapet walls, a commercial PDF and XML |
| Payment failed | The order call itself fails. No order row, no webhook. | Your handling of a rejected order call |
| Cancelled | Any unlisted address. Accepted, then ended without delivery, with a reason and a credit refund. | The unmeasurable-property path |
When do webhooks arrive?
About five seconds after each transition, held back on purpose so the HTTP response to the call that caused a change always arrives before the webhook announcing it. Code that stores the order id from the response and then looks it up when the webhook lands will never see the webhook first. Live orders follow the same rule.
Can I test revisions?
Yes, on any sandbox order that reaches completed. Open a revision and you get
revisions_requested immediately and revision_completed about
fifteen seconds later, the same two webhooks a live revision sends. The previously
delivered files stay downloadable throughout. See the
revisions reference for the rules.
Can I see the files without ordering?
Yes. The Sandbox page in the dashboard lists every scenario with its PDF, XML and ESX. If you are writing a parser, pull the XML from there first; it is the same document a live order delivers.
Keep the sandbox key in your staging environment after launch. Sandbox orders never draw balance, so every deploy can be smoke-tested end to end without spending anything.
Next: order your first report, then read the order lifecycle.
Frequently asked questions
Is the RoofQuery sandbox free?
Yes. Sandbox orders never draw balance, and there is no limit on how many you place while building.
Are sandbox reports real roofs?
Yes. Each test address delivers a roof recorded from a real property, through the same parser and PDF renderer a live order uses. Only the timing is scripted.
Can a sandbox key place a live order by mistake?
No. Sandbox and live keys are strictly separated. No address and no field turns a sandbox order into a real one.