Skip to main content
Verify storm impact at a property and order a hail-history PDF onto the project.

​
Enable and use the HailTrace connector

This article explains how to connect XBuild to HailTrace, run a free storm-impact check at a project’s address, and order a hail-history PDF report that files directly into the project’s Documents and the proposal itself. HailTrace is XBuild’s weather-and-storm data source — hail size, wind speed, and tornado activity by date and location — and pairs naturally with roofing, siding, and any other storm-restoration workflow that starts with the question “was this property actually hit?” You must be logged into XBuild as an Administrator to connect HailTrace, and you must have an active HailTrace account (the connector uses your HailTrace credits and permissions to run checks and place orders). HailTrace is a Pro Plan Benefit — it’s available on Pro and higher.

​
Why connect HailTrace to XBuild?

Storm-restoration contractors live and die by storm verification. Without a connector, that means switching to HailTrace, re-typing the address, checking impact history, downloading a PDF, and re-uploading it into XBuild. HailTrace in XBuild collapses all of that into a couple of clicks in the project you’re already working in.
  • Verify the storm before you chase the job. Run a free impact-history check at the project address to see which dates brought hail or damaging wind, plus a max-hail-size and top-wind readout for the location. No report ordered, no charge.
  • Order a hail-history PDF in one click. Once you’ve confirmed the storm, order the report from the same modal. XBuild waits for HailTrace to generate the PDF and files it into the project.
  • Reports auto-file to Documents and drop straight into the proposal. Ordered hail-history PDFs land in the project’s Documents section, tagged storm-report, the moment they’re ready — and they’re automatically inserted into the Weather Report section of the project’s Proposal Layout, so the report is in the customer-facing proposal without any extra step from you.
  • A widget and AI announcement in chat. When the report finishes, a HailTrace widget posts to the project chat with a FILED badge and a link to the PDF. The AI acknowledges the delivery so you can pick right up on the estimate.
  • Matches your HailTrace access level. The XBuild connector acts on behalf of your HailTrace user, so it never returns reports outside your HailTrace plan. HailTrace plans are scoped by geographic coverage — if a property isn’t in a region your HailTrace plan covers, XBuild returns the same “not covered” result HailTrace itself would show, and no credit is spent.

​
1. Connect Your HailTrace Account

HailTrace authenticates with an API key you generate from your HailTrace account — there’s no OAuth flow and XBuild never sees your HailTrace login.
Generate Your HailTrace API Key
  1. In a new tab, sign in to your HailTrace account at app.hailtrace.com.
  2. Open Settings → API Keys.
  3. Click Generate API key (or copy an existing one you already have).
  4. Copy the key. HailTrace shows it in full on generation — store it somewhere secure or head straight into XBuild to paste it.
Add the Connection in XBuild
  1. In XBuild, navigate to Settings → Connectors.
  2. Under Measurement & weather reports, click HailTrace.
  3. On the HailTrace connector detail page, click + Add connection.
  4. (Optional) Give the connection a Display name — for example, “Heritage Roofing — HailTrace Account”. This is only used inside XBuild to identify the connection.
  5. Paste your HailTrace API key into the HailTrace API key field. XBuild stores it securely and sends it as the X-API-Key header on your behalf.
  6. Click Connect.
The connection appears in the Connections section with a green ● Connected indicator and the key masked. You can remove it at any time by clicking the × on the connection row. Only one HailTrace connection per workspace is supported in v1.
Multiple XBuild Locations
HailTrace is connected at the Location level, following the same pattern as XBuild’s other connectors. Each Location can map to its own dedicated HailTrace account, or multiple Locations can share a single HailTrace account — whichever matches how your business bills.
  • Separate accounts per Location. Switch into each Location and run through the connection steps above using that Location’s HailTrace API key.
  • One shared account across Locations. Use the same HailTrace API key when connecting each Location. All Locations bill against the same HailTrace account.
New Locations don’t inherit HailTrace connections from other Locations — remember to connect HailTrace for each one that needs storm data.

​
2. Check Storm Impact at a Property

Impact checks are free. They tell you whether a storm actually hit the property, on what dates, and how bad — so you know whether to spend the credit ordering a full PDF report.
Open the HailTrace Picker
  1. Open a project (or start a new chat bound to a project) in XBuild.
  2. From the chat prompt, click the + button.
  3. Select HailTrace from the menu (subtitle: “Check storm impact or order a report”).
The Storm report from HailTrace modal opens, breadcrumb Connectors / HailTrace / Impact check. The subtitle reads “Check this property’s storm history, then order a hail-history report.”
Enter the Property Address
  1. Use the Search address… field for Google Places autocomplete. Selecting an address fills the property-address fields and centers the map pin.
  2. (Optional) Drag the pin on the map preview until it sits on the correct rooftop. Toggle Map / Satellite as helpful. The lat/long readout updates live.
  3. Confirm the address in the field below the map.
  4. Click Check impact.
XBuild queries HailTrace’s impact history for that location and returns the results inline.
Read the Storm History
Below the address, a Storm history panel appears with the summary of what HailTrace found at that address:
  • Event count at the top (for example, “57 events on record”).
  • Summary chips on the right — the biggest event by size: Max hail and Top wind (for example, “Max hail 3” / “Top wind 92 mph”).
  • Event list grouped by year, showing each storm’s type (hail, damaging wind, tornado), date, and severity metric (hail size in inches, wind speed in mph, tornado EF rank).
Use this to decide whether the storm history justifies ordering a full PDF report for the claim. If nothing shows up (or the events don’t line up with your date of loss), you can close the modal without spending a credit.

​
3. Order a Hail History Report

Once you’ve confirmed the storm at the address, order the full hail-history PDF report. This is what you’ll attach to the insurance claim.
  1. From the impact-check view, click + Order report in the bottom right.
  2. The breadcrumb updates to Connectors / HailTrace / Impact check / Order report and the modal switches to the Generating your storm report… state with a message: “This takes a moment — keep this open. We’ll file the PDF in this project’s Documents when it’s ready.”
  3. Keep the modal open while XBuild polls HailTrace for report completion. Reports typically take under a minute; complex or wider-geography reports can take longer.
  4. When the report is ready, the modal switches to a Storm report filed confirmation with a green checkmark and the message: “The hail-history PDF for [address] is now in this project’s Documents.”
  5. Click View in project chat to jump back to the chat where the report was filed, or close the modal — the PDF is already in Documents either way.
Ordering a report bills to your connected HailTrace account. XBuild doesn’t process HailTrace payments.

​
4. Track and Access Your Report

When HailTrace delivers the report, four things happen automatically in the project:
  • The PDF is saved to the project’s Documents section. Look for it in the project’s Documents tab, tagged storm-report, using a filename that includes the property address.
  • The report is inserted into the project’s Proposal Layout — Weather Report section. If the project’s active Proposal Layout includes a Weather Report section, the newly delivered PDF is automatically placed there. That means the report shows up in the customer-facing proposal without you having to attach it manually.
  • A HailTrace widget posts to the project chat with a green ● FILED badge. The widget shows the property address, the report status, and a Hail-history PDF filed to Documents row you can click to open the PDF directly.
  • The AI acknowledges the delivery in chat — for example, “Your HailTrace storm report for 1915 Classen Boulevard, Norman, OK 73071 is ready — I’ve filed the PDF in this project’s Documents.” From there you can continue the conversation to build the estimate or claim supplement.
The widget stays in the chat thread as a permanent record of the report. If you order a second report on the same project later, you’ll get a fresh widget for that one — earlier widgets don’t retroactively update. If your project’s Proposal Layout doesn’t include a Weather Report section, the PDF still files to Documents and posts in chat — it just won’t auto-appear inside the proposal. Add a Weather Report section to your layout (see the Proposal Layouts article) if you want future storm reports to drop into proposals automatically.

​
5. Troubleshooting Common Issues

  • HailTrace is missing from the chat + menu. The connector isn’t connected for the active Location. Open Settings → Connectors → HailTrace and click + Add connection. HailTrace must be active in the Location you’re working from before it appears in the chat picker.
  • HailTrace is greyed out or says “No project selected.” The chat isn’t bound to a project yet. Attach a project to the chat, or start typing a prompt — XBuild will create a project from the address on your first check or order.
  • “Invalid API key” or auth errors on Connect. The API key was typo’d, expired, or revoked in HailTrace. Regenerate it at app.hailtrace.com/settings/api-keys and paste the new value into XBuild.
  • An address returned no results or “not covered by your plan.” The XBuild HailTrace connector matches your HailTrace access level exactly — it won’t return reports outside your HailTrace plan. HailTrace plans are based on geographic coverage, so if a property falls outside the regions your plan covers, XBuild returns the same “not covered” state HailTrace would show (and no credit is spent). Upgrade or expand your HailTrace plan at app.hailtrace.com to add coverage for new regions, then re-run the check in XBuild.
  • My storm history came back empty for an address I know was hit. First, confirm the pin is on the right rooftop — dragging the pin to the correct location often changes the result for properties on parcel boundaries. If the address is in a region your HailTrace plan covers but still returns no events, confirm the storm date falls within the weather types your plan supports (hail, damaging wind, tornado).
  • The report has been “generating” for a long time. Most reports finish in under a minute. HailTrace occasionally queues large or complex reports for longer processing. Keep the modal open — XBuild will file the PDF the moment it’s ready. If it stalls beyond a few minutes, close the modal and reopen; the order still processes in the background and the PDF will land in Documents on completion.
  • I closed the modal before the report finished. No problem. The order continues on HailTrace’s side, and the PDF still lands in the project’s Documents when ready. You’ll see the HailTrace widget in the project chat when it does.
  • The report isn’t showing up in my proposal. The auto-insert requires a Weather Report section in the project’s active Proposal Layout. Open Settings → Proposal Layouts, edit the layout you’re using for this project, and add a Weather Report section. Future storm reports on projects using that layout will drop in automatically. The PDF is still in the project’s Documents in the meantime.
  • I need to change my HailTrace account. Open Settings → Connectors → HailTrace, remove the existing connection with the ×, then click + Add connection and paste a new API key.
  • I don’t have a HailTrace account — can I still use this connector? No. Impact checks and reports run against your own HailTrace subscription. Sign up with HailTrace first, then come back to Settings → Connectors → HailTrace to connect.
  • I’m on the Standard plan and don’t see HailTrace as a connector. HailTrace is a Pro Plan Benefit. Upgrade to Pro or higher from Settings → Billing to unlock it.
For further assistance, contact HailTrace via the HailTrace Help Center or email their team at support@hailtrace.com. For XBuild-side issues, contact XBuild Support at support@x.build.