API Documentation

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header of every request.

API Key Authentication

Get your API key from your account dashboard under Settings > API Keys. Keep your API keys secure and never commit them to version control.

Authorization: Bearer your_api_key_here

curl -H "Authorization: Bearer your_api_key" \
  https://api.aquaintel.com/v1/leads

const response = await fetch(
  'https://api.aquaintel.com/v1/leads',
  {
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

Base URL

All API endpoints are relative to the following base URL:

https://api.aquaintel.com/v1

Leads API

Access and manage leads in your territories.

{
  "data": [
    {
      "id": "lead_123abc",
      "address": "123 Main St, Springfield, IL 62701",
      "owner_name": "John Smith",
      "score": 87,
      "water_hardness": "hard",
      "pipe_age": 35,
      "property_value": 250000,
      "territory_id": "terr_456def",
      "created_at": "2026-03-31T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5432,
    "pages": 272
  }
}

{
  "id": "lead_123abc",
  "address": "123 Main St, Springfield, IL 62701",
  "owner_name": "John Smith",
  "score": 87,
  "scoring_factors": {
    "water_hardness": 25,
    "property_age": 20,
    "income_level": 18,
    "hardness_trend": 15,
    "system_status": 9
  },
  "water_hardness": "hard",
  "water_hardness_value": 320,
  "pipe_age": 35,
  "pipe_material": "galvanized",
  "property_value": 250000,
  "territory_id": "terr_456def",
  "created_at": "2026-03-31T10:30:00Z",
  "updated_at": "2026-03-31T15:45:00Z"
}

Territories API

Create and manage sales territories.

{
  "data": [
    {
      "id": "terr_456def",
      "name": "Downtown Springfield",
      "description": "Downtown and central areas",
      "lead_count": 1243,
      "average_score": 75,
      "created_at": "2026-01-15T08:00:00Z"
    }
  ],
  "total": 5
}

curl -X POST https://api.aquaintel.com/v1/territories \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Territory",
    "description": "North side expansion",
    "polygon": {
      "type": "Polygon",
      "coordinates": [[[-88.25, 39.75], [-88.20, 39.75],
                       [-88.20, 39.80], [-88.25, 39.80],
                       [-88.25, 39.75]]]
    }
  }'

Scoring API

Access lead scoring data and historical trends.

Rate Limiting

The Aqua Intel API implements rate limiting to ensure fair access and service stability. Rate limits depend on your subscription plan.

When you exceed rate limits, the API returns a 429 (Too Many Requests) status code. Headers indicate when you can retry:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1680787200

Webhooks

Subscribe to real-time events and trigger custom workflows when data changes in Aqua Intel.

Webhook Events

Common webhook events you can subscribe to:

Webhook Payload

{
  "id": "webhook_evt_123",
  "timestamp": "2026-03-31T15:30:00Z",
  "event": "lead.created",
  "data": {
    "lead_id": "lead_123abc",
    "territory_id": "terr_456def",
    "score": 87,
    "address": "123 Main St, Springfield, IL 62701"
  }
}

Error Handling

The API returns standard HTTP status codes and detailed error messages.

Best Practices

• Secure your API keys: Never expose your API keys in client-side code. Store them securely on your server.
• Use pagination: For large datasets, always use pagination parameters to avoid timeout issues.
• Implement webhooks: Use webhooks instead of polling for real-time updates and better performance.
• Handle rate limits: Implement exponential backoff when rate limits are hit.
• Cache responses: Cache API responses where appropriate to reduce requests and improve performance.