WaterTDS Partner API

Implementation vs Specification

This implementation differs from the original API Specification (private):

Authentication

All API requests require an API Key in the Authorization header:

Authorization: Api-Key <your-api-key>

Internal: How to create API keys (private)

API Endpoints

Customer Service

Product Service

Filters

Customers

Contacts

Devices

Alerts

Alert Types

Webhooks (Push Alerts)

Instead of polling the alerts endpoint, you can receive alerts as push notifications. When an alert triggers for one of your devices, WaterTDS sends an HTTP POST to an HTTPS endpoint you configure. It is the same set of alert events you get by email — the event toggles decide what is sent, the webhook switch decides whether it is also pushed to your endpoint.

Configuration

Set up in the WaterTDS B2B admin (Company → Notifications):

• Enable webhook delivery — master switch.
• Endpoint URL — must be HTTPS and publicly reachable.
• Secret — auto-generated, shown once at generation time. Copy it then; afterwards only a masked hint is displayed. Use it to authenticate incoming requests.
• Event toggles — only enabled alert types are delivered.

Request

POST <your endpoint>
Content-Type: application/json
Authorization: Bearer <your secret>
X-WTDS-Event-Id: <uuid>     # unique per event; use for idempotency

Body

{
  "event_types": ["daily_thresholds_alerts"],
  "event_id": "63679b4d-1ac3-426d-8d9e-e3f95888998e",
  "company_id": 94,
  "device_id": 315,
  "timestamp": "2026-06-29T14:35:49.825388+00:00",
  "data": {
    "device_id": 315,
    "user": "Acme Water Co",
    "label": "Kitchen RO",
    "model": "RO-500",
    "manufacturer": "Acme",
    "install_date": "2022-11-02",
    "address_1": "...", "city": "...", "state": "...", "zip_code": "...",
    "alert_messages": [
      "The TDS level of the output is greater than 51 ppm. You had set up this alert."
    ]
  }
}

event_types values: monthly_quality_report, calculation_based_alerts, manufacturer_suggested_alerts, daily_thresholds_alerts, hourly_thresholds_alerts.

Response & Retries

• Return any 2xx to acknowledge (body ignored). Respond within 10s.
• 5xx / timeout → retried up to 2 more times with a short random delay (~30–120s).
• 4xx → permanent failure, no retry.
• If all attempts fail, your company email is notified to check the webhook settings.

Example receiver (Flask)

import hmac
from flask import Flask, request, abort

SECRET = "your-secret-from-the-admin"
seen = set()
app = Flask(__name__)

@app.post("/wtds-webhook")
def hook():
    if not hmac.compare_digest(request.headers.get("Authorization", ""), f"Bearer {SECRET}"):
        abort(401)
    event = request.get_json()
    if event["event_id"] in seen:      # idempotency
        return "", 200
    seen.add(event["event_id"])
    for msg in event["data"].get("alert_messages", []):
        print(event["device_id"], event["event_types"], msg)
    return "", 200

Pagination

All list endpoints support pagination:

Response format:

{
  "count": 50,
  "next": "https://api.watertds.com/.../devices/?page=2",
  "previous": null,
  "results": [...]
}

Example Requests

List Customers

curl -X GET "https://api.watertds.com/customer/external/v1/customers/" \
  -H "Authorization: Api-Key <your-api-key>"

List Devices for Customer

curl -X GET "https://api.watertds.com/product/external/v1/devices/?customer_id=123" \
  -H "Authorization: Api-Key <your-api-key>"

Get Alerts for Today

curl -X GET "https://api.watertds.com/product/external/v1/alerts/?date=2024-01-15" \
  -H "Authorization: Api-Key <your-api-key>"

Data Access

Your API key is linked to a customer account. You can only access:

• Your linked customer
• All customers in your hierarchy (children, grandchildren, etc.)
• Contacts belonging to those customers
• Devices assigned to those customers
• Alerts for those devices