# How to order a storm report by API

> A storm report is ordered with POST /api/v1/storm/orders, using the same API key and balance as roof reports. The response is the whole report, about two seconds later, with links to five branded PDFs. It costs $3, or nothing when no storm was recorded within 5 miles in five years. The date of loss and notes can be changed on every read, and five recorded sandbox addresses let you build the integration without spending anything.

Category: Getting started. Last updated 2026-10-17.
Canonical: https://roofquery.com/guides/how-to-order-a-storm-report-by-api

One POST with the address and coordinates returns the finished storm report in the response body. There is no order to poll and no webhook to wait for. Use the same API key and balance you use for roof reports.

> 

## What does the request look like?

The address rules are the same as for roof orders: street, city, two-letter state or province, postal code, country `US` or `CA`, and decimal coordinates. The date of loss, claim number, insured name and notes are optional.

```
curl -X POST "https://api.roofquery.com/api/v1/storm/orders" \
  -H "Authorization: Bearer rq_live_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: claim-20419-storm" \
  -d '{
    "street": "3208 Riviera Dr", "city": "Norman", "state": "OK",
    "postalCode": "73072", "country": "US",
    "latitude": 35.182884, "longitude": -97.458908,
    "dateOfLoss": "2025-05-25",
    "claim": "CLM-20419"
  }'
```

The `Idempotency-Key` header makes retries safe: sending the same key again returns the same report and never charges twice. Every field is in the [reference](https://roofquery.com/docs/order-a-storm-report).

## What comes back?

A `201` with the report: the headline, damage chance, summary, hail and wind tables, the date-of-loss analysis, the parcel and owner of record, the map, and a `documents` list with one link per PDF. `billing` says what was charged; `billing.charged` is `false` and `billing.reason` is `"no_storm_data"` when the report was free. [What's in a storm report](https://roofquery.com/guides/whats-in-a-storm-report) walks through the contents.

## How do I get the PDFs?

Each entry in `documents` has a `url`. The links need no API key, so you can hand them straight to a customer, and they take the same branding parameters as roof report PDFs, including `?brand=` for a customer's brand profile. The Date of Loss PDF is listed as unavailable until the report has a date of loss.

```
https://api.roofquery.com/api/v1/storm/orders/rq_ord_7f3c2a91d04be615/pdf?template=hail_verification&brand=rq_brand_3f9c0a7e21b45d68
```

## Can I change the date of loss later?

Yes, without ordering again. The weather data is stored when you order and never changes, but the date of loss, claim number, insured name and notes are read from each request. Pass them on `GET /api/v1/storm/orders/:id` or on a PDF link, and that read uses them:

```
curl -H "Authorization: Bearer rq_live_sk_..." \
  "https://api.roofquery.com/api/v1/storm/orders/rq_ord_7f3c2a91d04be615?dateOfLoss=2024-11-02"
```

## How do I test without spending anything?

Use a `rq_test_sk_*` key. Storm orders in sandbox are free and return recorded reports that never change: a busy history in Norman, Oklahoma, a hail-led property in Texas, a wind-led one in Nebraska, a Canadian address, and an address where nothing was recorded, which shows the free report. Two more addresses return the payment and outage errors. The list is at [storm report sandbox](https://roofquery.com/docs/storm-sandbox), and [testing in sandbox](https://roofquery.com/guides/testing-in-sandbox-before-you-spend) covers the rest of the sandbox.

## What can go wrong?

| Response | Meaning |
| --- | --- |
| `402 INSUFFICIENT_CREDITS` | Less than $3 available, even if the report would have been free. Nothing was looked up. |
| `400 validation` | A field is missing or malformed, such as a date of loss in the future. |
| `503 service_unavailable` | Weather data didn't answer in time. No order was created and nothing was charged; retry. |

## Frequently asked questions

### Do storm reports use webhooks?

No. The report is in the response to the order, about two seconds after you send it, so there is nothing to wait for.

### Is a storm report charged again when I change the date of loss?

No. The date of loss, claim number, insured name and notes can change on every read and download of the same report at no extra cost.

### Can I use my existing API key?

Yes. One key and one prepaid balance cover roof reports and storm reports.