# WaterFilterHelp.ca — Agent instructions

WaterFilterHelp.ca connects Canadian homeowners with water filtration contractors (softeners, reverse osmosis, well treatment, UV, PFAS/lead reduction). This document is for AI assistants helping users request **free quotes** without opening the website UI.

## Discovery

| Resource | URL |
|----------|-----|
| Site overview (llms.txt) | `https://waterfilterhelp.ca/llms.txt` |
| Robots / Content Signals | `https://waterfilterhelp.ca/robots.txt` |
| Sitemap | `https://waterfilterhelp.ca/sitemap.xml` |
| Capability manifest | `https://waterfilterhelp.ca/.well-known/quote.json` |
| OpenAPI | `https://waterfilterhelp.ca/openapi.json` |
| API catalog | `https://waterfilterhelp.ca/.well-known/api-catalog.json` |
| Agent skills | `https://waterfilterhelp.ca/.well-known/agent-skills/index.json` |

## Capabilities

| Capability | Endpoint | Method |
|------------|----------|--------|
| Submit quote request | `https://waterfilterhelp.ca/api/v1/quotes` | `POST` |
| Nearby businesses | `https://waterfilterhelp.ca/api/v1/businesses/nearby?lat=&lng=` | `GET` |
| Health | `https://waterfilterhelp.ca/api/v1/health` | `GET` |

## Workflow for agents

1. **Discover** — Read `/.well-known/quote.json` or this file for field names and allowed values.
2. **Interview** — Ask about water source, service needed, urgency, contact, and property location.
3. **Consent** — Before submitting, confirm: *"I'll send your name, phone, email, and property address to WaterFilterHelp.ca so a local water treatment contractor can contact you. OK?"*
4. **Submit** — `POST /api/v1/quotes` with `"consent": true` and all required fields. Leave `"website"` empty (honeypot).
5. **Confirm** — Tell the user they should hear back within ~24 hours.

Human fallback: `https://waterfilterhelp.ca/quote`

## Required JSON fields

| Field | Description |
|-------|-------------|
| `consent` | Must be `true` after explicit user agreement |
| `issue_type` | `whole_home`, `reverse_osmosis`, `softener`, `well_treatment`, `carbon_sediment`, `pfas_lead`, `service_repair`, `water_testing`, `advice`, `other` |
| `urgency` | `asap`, `1_3_months`, `researching` |
| `name`, `email`, `phone` | Contact information |
| `address`, `city`, `province` | Property location (Canada) |

Optional: `system_type` (`municipal` \| `well` \| `cottage`), `postal_code`, `details`, `agent_source` (e.g. `chatgpt`).

**Do not** set `website` — it is a spam honeypot.

## Example request

```http
POST /api/v1/quotes HTTP/1.1
Host: waterfilterhelp.ca
Content-Type: application/json

{
  "consent": true,
  "issue_type": "softener",
  "system_type": "municipal",
  "urgency": "1_3_months",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "(416) 555-0100",
  "address": "123 King St W",
  "city": "Toronto",
  "province": "ON",
  "postal_code": "M5H 1A1",
  "agent_source": "chatgpt"
}
```

## Human-readable pages

- Guides hub: `https://waterfilterhelp.ca/guides`
- City hubs: `https://waterfilterhelp.ca/{province}/{city}` (e.g. `/on/toronto`)
- Service landers: `https://waterfilterhelp.ca/services/{slug}` (e.g. `/services/water-softeners`)
- Service × city: `https://waterfilterhelp.ca/on/toronto/water-softener-installation`

## Privacy

Contact data is used only to match and notify a water treatment contractor. See https://waterfilterhelp.ca for site terms.