Sandbox — RoofQuery API reference

API reference

Base URL: https://api.roofquery.com. Authenticate with Authorization: Bearer <your key> — except the file routes (report and storm report files), which take no key.

Copies this whole page as Markdown, so you can paste it into an assistant and have it write the integration. Nothing secret goes on the clipboard — your keys aren't included.

GET /api/v1/reports/sandbox/scenarios

Lists the sandbox test addresses for every report type: residential, commercial, Rapid Squares and Storm Reports. Order one with an rq_test_sk_* key and it runs that address's scenario, so you can test every outcome your code has to handle before a live order.

How the sandbox works

Free. A sandbox order never draws balance, and needs no card. Adding an ESX to a sandbox order is free too.
The key decides. A sandbox order is the same request as a live one, with an rq_test_sk_* key instead of rq_live_sk_*. No header or body field forces a scenario, and no address turns a sandbox order into a real one.
The address picks the scenario, case-insensitive, or by coordinates within about 110 m. The table below lists every address and what it does for each report type.
Real webhooks. Every status change of a roof report is sent to your webhook endpoints, the same body a live order sends. Storm Reports answer in the response, as they do live.

Test addresses

Report type	Scenario	Address	What happens
Residential, Rapid Squares	`happy_path`	6515 Turnbridge Pl, Prospect, KY 40059	`processing` at 0 s, `in-progress` at 10 s, `completed` at 20 s. One structure: a 33-facet hip roof with dormers, hips, valleys and a pitch change.
Residential	`happy_path_2_structures`	725 Pleasant Ave, St Paul Park, MN 55071	Same timeline. Two structures: a house with an attached wing, and a detached shed.
Residential, Rapid Squares	`happy_path_4_structures`	401 Garrison St, Bulpitt, IL 62517	Same timeline. Four structures: a house and three outbuildings.
Commercial	`happy_path_commercial`	6101 E Lombard St, Baltimore, MD 21224	Same timeline. A low-slope commercial roof with parapet walls.
Residential, Rapid Squares	`on_hold`	12440 S Nimitz Dr, Galveston, IN 46932	`processing` at 0 s, `in-progress` at 10 s, `on-hold` at 20 s, `in-progress` again at 50 s, `completed` at 60 s. A gable roof at three pitches, on a house and a detached shed.
Residential, Commercial, Rapid Squares	`cancelled`	600 N Michigan Ave, Chicago, IL 60611, and any other address	`processing` at 0 s, `in-progress` at 10 s, `cancelled` at 20 s. Nothing is delivered.
Residential, Commercial, Rapid Squares	`payment_failed`	400 5th Ave, New York, NY 10018	The order call itself returns `402 INSUFFICIENT_CREDITS`. No order is created and no webhook fires.
Residential, Commercial, Rapid Squares	`order_failed`	500 Hollywood Blvd, Los Angeles, CA 90028	The order call itself returns `502 ORDER_FAILED`. No order is created and no webhook fires.
Storm	`storm_busy`	3208 Riviera Dr, Norman, OK 73072, and any other address	A busy history: large hail, 75–130 mph wind, tornadoes. Try `dateOfLoss: "2025-05-25"`. Any other address returns this report, with your address on it.
Storm	`storm_hail`	1816 Copper Creek Dr, Plano, TX 75075	Hail-led: 3" hail within 1 mile
Storm	`storm_wind`	112 Regency Pkwy, Omaha, NE 68114	Wind-led: severe wind on 12 days; the owner is a company
Storm	`storm_canada`	237 8 Ave SE, Calgary, AB T2G 5C3	Canada: radar hail and stations only, with the coverage note
Storm	`storm_none`	157151 US-101, Forks, WA 98331 (Kalaloch Lodge)	Nothing recorded: the free report (`billing.reason: "no_storm_data"`, `amount: 0`)
Storm	`payment_failed`	400 5th Ave, New York, NY 10018	`402 INSUFFICIENT_CREDITS`, no order
Storm	`service_unavailable`	500 Hollywood Blvd, Los Angeles, CA 90028	`503 service_unavailable`, no order

Roof reports (residential, commercial, Rapid Squares). Any address not in the table runs cancelled. Times are seconds after the order is placed, and can run a second or two late. Webhooks are held back about 5 seconds after each change, so the HTTP response to the call that caused a change always arrives before the webhook announcing it.

Real reports. Each delivering address returns a different roof, recorded from a real property and run through the same parser and PDF path as a live order. The dashboard's Sandbox page has the PDF, XML and ESX for each, without ordering. The XML is the one to read if you're writing a parser.

ESX as live. A sandbox order includes the Xactimate ESX exactly when a live one would: when it sends "esx": true, or leaves esx out on an account whose default is on. Without it, report.esx is missing from files[] and the download returns 403 ESX_NOT_PURCHASED, so you can test both paths.

Rapid Squares delivers a recorded sample at three addresses (happy_path, happy_path_4_structures and on_hold): the one-page PDF, the XML and the photo the outlines were drawn on. It never comes with an ESX. At the other delivering addresses a Rapid Squares order completes with no document.

Storm Reports in sandbox are free and return recorded reports that never change, in the response that orders them. Every PDF template, rendered from the Norman address, is under Storm report PDFs, and signed in, the dashboard's Sandbox page opens all five PDFs for every test address.

Revisions

Any roof sandbox order that reaches completed can be revised; there is no special address for it. Request a revision and you get a revisions_requested webhook straight away, then revision_completed about 15 seconds later: the same two webhooks, in the same order, that a live revision sends. Storm Reports aren't revised.

Parameters

Field	Required	Description
`reportType`	No	Query parameter: `residential`, `commercial`, `rapid_squares` or `storm` lists only that type's addresses. Without it, every address. Anything else is `400 validation`.

Request

curl -H "Authorization: Bearer rq_test_sk_..." \
  "https://api.roofquery.com/api/v1/reports/sandbox/scenarios?reportType=residential"

Response

Every address in the table, each with the reportTypes it's for, in this shape (one roof and one storm entry shown). Roof entries carry their timeline; storm entries carry a description and, where there is one, a suggestedDateOfLoss.

{
  "note": "Sandbox keys (rq_test_sk_*) only, never charged. The address you order picks the scenario — exactly, or by coordinates within ~110m. Roof reports: any address not listed here runs the `cancelled` timeline. Storm Reports: any other address gets storm_busy with your address on it.",
  "revisions": "Any roof sandbox order that reaches `completed` can be revised. The request emits `revisions_requested`, then the report is re-delivered and `revision_completed` fires about 15s later.",
  "reportType": null,
  "scenarios": [
    {
      "scenario": "happy_path",
      "reportTypes": ["residential", "rapid_squares"],
      "address": "6515 Turnbridge Pl, Prospect, KY 40059, USA",
      "latitude": 38.3526391,
      "longitude": -85.6208045,
      "timeline": [
        { "status": "processing",  "atSeconds": 0 },
        { "status": "in-progress", "atSeconds": 10 },
        { "status": "completed",   "atSeconds": 20 }
      ],
      "synchronousFailure": false
    },
    {
      "scenario": "storm_busy",
      "reportTypes": ["storm"],
      "description": "Busy history: large hail, 75–130 mph wind, tornadoes, FEMA declarations",
      "address": "3208 Riviera Dr, Norman, OK 73072, USA",
      "latitude": 35.182884,
      "longitude": -97.458908,
      "suggestedDateOfLoss": "2025-05-25",
      "damageChance": "high"
    }
  ]
}

synchronousFailure: true means the order call fails before an order exists, as it would live. With ?reportType=storm there is no revisions.