Ready to spend right now.

Charges your default card and adds the amount to your balance immediately.

Keeps your balance topped up so orders never fail for want of credit. If an order takes you below the threshold, your card is charged and the credit lands straight away.

If the balance has gone negative, the charge covers the shortfall as well as the amount above — one top-up always clears the threshold. A declined card switches auto-recharge off rather than retrying on every order.

• Sandbox and live are strictly separate. A rq_test_sk_* key can never place a real order, and a rq_live_sk_* key can never run a sandbox timeline. The environment comes from the key prefix, not from anything in your request, and an order is refused outright if the two ever disagree.
• An unlisted address stays in sandbox. Order any address you like — out of coverage, made up, malformed. It runs the unrecognized timeline. There is no address that turns a sandbox order into a real one.
• Sandbox never draws credit. Your balance is untouched and no card is charged, however many orders you place. The response still shows the real price so you can see what a live order would cost.
• Completed sandbox orders carry genuine XML — same parser and same PDF path as live.
• Any sandbox order that completes can be revised. Not just the scenario named revision — that one is named for the roof it carries, not for a behaviour. Request a revision against any completed sandbox order and you'll get revisions_requested, then revision_completed about 15 seconds later.
• Webhooks fire for real against your configured endpoints.
• payment_failed and order_failed return a 402/502 from the order call itself, because that's what happens in production. They never arrive as a webhook.

An instant roof-size estimate returned in the API response, with no measuring turnaround — for triage and quoting where a full measured report is more than you need.

Your existing API keys and webhook endpoints will cover it — those are account-wide, not per product, so there'll be nothing new to set up. It'll draw against the same balance too.

One API key and one set of webhook endpoints cover every product, and every product draws on the same balance. These don't change as products are added.

A completed order exposes two files. Each is fetched with the same key you ordered with, and each appears in the order payload's files[] array so you can hand the URLs straight to your own code.

curl -H "Authorization: Bearer rq_live_sk_..." \
  "https://api.roofquery.com/api/v1/reports/orders/rq_ord_abc123/pdf?download=1" \
  -o report.pdf

All three return 409 not_ready until the order reaches completed. Wait for the webhook rather than polling.

Reports are white-labeled — they carry your brand. Set a company name and the header, footer, cover-page attribution and legal contact block all become yours; a small RoofQuery watermark remains in the footer. Leave it blank and the report falls back to full RoofQuery branding.

Two ways to supply it. Account-wide — set it once under Report branding and every report uses it. Per request — pass query params on the PDF URL to override the saved values for a single download, which is how you brand a report for one of your customers without touching your account settings.

curl -H "Authorization: Bearer rq_live_sk_..." \
  "https://api.roofquery.com/api/v1/reports/orders/rq_ord_abc123/pdf\
?companyName=Acme%20Roofing\
&brandColor=%231668B8\
&logoUrl=https://acme.example.com/logo.png" \
  -o acme-report.pdf

Nothing is cached — the PDF is rendered at the moment you request it. Change your branding and every report you've already ordered comes back re-skinned on its next download. The XML file carries no branding at all.

Insufficient balance and upstream rejections are not statuses — they come back as a 402/502 from the order call before an order exists, so there's nothing to webhook about.

GET /api/v1/reports/orders/:id/status returns the entire order — property, report settings, billing, revisions, measurements and file links — plus a statusDetail block that answers the two questions you'd otherwise write a switch statement for.

{
  "orderId": "rq_ord_abc123",
  "status": "in-progress",
  "statusDetail": {
    "code": "in-progress",
    "label": "In progress",
    "description": "A technician is measuring the property.",
    "terminal": false,          // is anything further expected?
    "filesReady": false,        // can I download yet?
    "known": true,              // false if we add a status your code hasn't seen
    "changedAt": "2026-07-31T14:02:11.000Z",
    "estimatedDeliveryHours": 2,
    "estimatedReadyAt": "2026-07-31T15:47:00.000Z",
    "openRevisionId": null
  },
  "totals": null,               // populated once measured
  "files": []                   // populated once measured
}

status stays the same plain string it is in the webhook payload, so a handler written against webhooks works here unchanged. Turnaround is an estimate from the product's typical time — around 2 hours residential and 8 commercial — not a commitment, and it's only meaningful while the order is still moving.

Measurements arrive on the order itself, so the webhook body, GET /orders/:id and GET /orders/:id/status all carry the same numbers — you never need a second call to get them. totals covers the whole property; each entry in structures[] is one building (house, detached garage, shed) with the identical shape.

"totals": {
  "structureCount": 1,
  "totalAreaSqFt": 5597.29,
  "totalSquares": 55.97,
  "facetCount": 33,
  "predominantPitch": "12/12",
  "pitchAreas": { "12/12": 5204.08, "5/12": 257.97, "11/12": 66.42 },
  "edgeTotals": {
    "EAVE":  { "lengthFt": 276.31, "count": 27 },
    "RAKE":  { "lengthFt": 169.20, "count": 13 },
    "RIDGE": { "lengthFt": 114.58, "count": 12 },
    "HIP":   { "lengthFt": 304.25, "count": 20 },
    "VALLEY":{ "lengthFt": 237.30, "count": 17 }
  },
  "totalEdgeLengthFt": 1234.58,
  "hipsAndRidgesLengthFt": 418.83,
  "complexity": "complex",
  "estimatedAtticSqFt": 4023.89
},
"structures": [ { "index": 1, "...": "every field above, for this building",
                  "faces": [ { "id": "F1", "areaSqFt": 338.51, "pitch": "12/12",
                               "edges": [ { "type": "EAVE", "lengthFt": 24.5 } ] } ] } ]

Edges shared between adjacent faces are counted once per structure, so adding up faces[].edges[] yourself will overcount — use edgeTotals. Pitches are snapped to a reporting ladder (0, ¼, ½, then whole numbers): measured slopes arrive as values like 10.31, and the PDF and these fields round through the same function so they can't disagree.

Revisions are only available on a report that has been delivered. An order has to be completed (or updated) before there is anything to correct — asking earlier comes back 409 NOT_REVISABLE. Revisions are free: a correction to work you already paid for draws no further balance.

One open revision per report. While a revision is open the order sits in revisions_requested and a second request is refused. The previously delivered files stay downloadable the whole time — the correction replaces them when it lands, and the order returns to completed with a revision_completed webhook.

curl -X POST "https://api.roofquery.com/api/v1/reports/orders/rq_ord_abc123/revisions" \
  -H "Authorization: Bearer rq_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"topic":"Roof Has Wrong Pitch","notes":"Front elevation reads 12/12, closer to 6/12."}'

topic must be one of the values from GET /api/v1/reports/revision-options. It is a fixed list, and the same list in sandbox and live:

notes is required and capped at 2000 characters. Be specific about which structure and which facet — it's read by the person making the correction.

Sandbox runs the whole cycle, on any completed order. Every sandbox test address that reaches completed can be revised — there is no special address for it. Request a revision and you'll get revisions_requested immediately and revision_completed about 15 seconds later: the same two webhooks, in the same order, that a live revision sends. Once it closes the order is revisable again.