# How to order your first roof measurement report by API

> A RoofQuery order is one POST with an address, coordinates and a scope. Sandbox keys run the full lifecycle in about twenty seconds against published test addresses, with nothing charged. Live residential reports are typically ready in about two hours and commercial in about eight, at $13 per residential report and $35 per commercial report. The completed webhook carries the measurements and links to the PDF, XML, ESX and diagrams.

Category: Getting started. Last updated 2026-09-09.
Canonical: https://roofquery.com/guides/how-to-order-your-first-roof-report

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](https://dashboard.roofquery.com/signup), 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](https://roofquery.com/docs/get-an-order) is there if you want to check on demand, but production integrations should learn a report is ready from the [webhook](https://roofquery.com/docs/webhooks).

## 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](https://roofquery.com/docs/place-an-order).

> **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](https://roofquery.com/docs/pdf): the white-labeled PDF, rendered at download time.
- [/orders/:id/xml](https://roofquery.com/docs/xml): the raw measurement document.
- [/orders/:id/esx](https://roofquery.com/docs/esx): the Xactimate file.
- [/orders/:id/diagrams](https://roofquery.com/docs/diagrams): outline, area, pitch and length drawings as SVG or PNG.

The order id is the credential for the [file routes](https://roofquery.com/docs/sharing-a-report), 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](https://roofquery.com/docs/balance) from running dry.

## What should I build next?

Set up [branding](https://roofquery.com/guides/how-white-label-branding-works) so the PDF carries your company, walk the failure scenarios in [sandbox](https://roofquery.com/guides/testing-in-sandbox-before-you-spend), and read the [order lifecycle](https://roofquery.com/docs/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.