You can go from no account to a delivered report in one sitting. Everything after the order happens on our side: a technician measures the roof, and we call your webhook when the files are ready. This guide walks the path once in sandbox, where nothing is charged, and then once live.
What do I need before the first call?
An account and a sandbox key. Create an account,
open API keys in the dashboard, and generate a sandbox key. Sandbox keys
start with rq_test_sk_, live keys with rq_live_sk_. They are
separated on purpose: a test key can never place a real order, and a live key can never
hit the test timelines. Send the key as a bearer token on every request.
Where do results arrive?
On a webhook you register in the dashboard. Reports take hours, not seconds, so the API never asks you to poll. We POST to your URL on every status change with the full order in the body. For a first test any request bin or local tunnel works. The status endpoint is there if you want to check on demand, but production integrations should learn a report is ready from the webhook.
What does the order request look like?
One POST with the address, coordinates, a scope and a report type. In sandbox, the address you send is what picks the scenario, so use one of the published test addresses. This one runs the happy path and completes in about twenty seconds:
curl -X POST "https://api.roofquery.com/api/v1/reports/orders" \
-H "Authorization: Bearer rq_test_sk_..." \
-H "Content-Type: application/json" \
-d '{
"country": "US",
"street": "6515 Turnbridge Pl",
"city": "Prospect",
"state": "KY",
"postalCode": "40059",
"latitude": 38.3526391,
"longitude": -85.6208045,
"scope": "all_structures",
"reportType": "residential"
}'
You get a 201 straight back with the order in its first state,
processing. Then the webhooks arrive: in-progress, and finally
completed with the file links attached. The full field list is in the
order endpoint reference.
Scope has no default. Send primary_only,
primary_and_garage or all_structures every time. A wrong default
would be a report that misses the garage your customer wanted priced.
How do I get the files?
One GET each, and none of them needs an API key. The completed webhook already carries the measurements on the order itself, so totals, pitch breakdown and edge lengths are in your hands before you download anything.
/orders/:id/pdf: the white-labeled PDF, rendered at download time./orders/:id/xml: the raw measurement document./orders/:id/esx: the Xactimate file./orders/:id/diagrams: outline, area, pitch and length drawings as SVG or PNG.
The order id is the credential for the file routes, which is what lets you paste a report link into an estimate or email it to a homeowner without proxying the download through your own server.
How do I go live?
Top up your balance, generate a live key, and send the same request with a real address.
The cost is deducted at order time: $13 residential, $35 commercial. Residential reports are
typically ready in about two hours and commercial in about eight. If a property turns out
to be unmeasurable, the order comes back cancelled with a reason and the cost is
refunded as account credit. Auto-recharge in the dashboard keeps the
balance from running dry.
What should I build next?
Set up branding so the PDF carries your company, walk the failure scenarios in sandbox, and read the order lifecycle so redeliveries and revisions are handled before your first correction arrives.
Frequently asked questions
Do I need a credit card to test?
No. Sandbox orders never draw balance, and you can create an account and a sandbox key without topping up.
How long does a live roof measurement report take?
Residential reports are typically ready in about two hours and commercial in about eight. A webhook fires the moment the report is complete.
Can I order without coordinates?
No. Latitude and longitude are required alongside the address so the report is produced on the property you mean, not the one a geocoder guesses.
Is there a subscription or minimum?
No. You prepay a balance and each report is deducted from it. There is no plan, no seat cost and no minimum volume.