Organizations API — Data Retrieval API

Organization addresses

Use /api/organizations/v2/current or /api/organizations/v2/{organizationId} to include data.organization.addresses. The v2 data-model collection and item routes also include attributes.addresses on site rows.

Addresses are ordered by ID. An organization with no active addresses returns an empty array. Archived addresses are excluded. Address fields use the same format as site addresses.

curl --digest --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v2/current"

Authentication, scopes, organization access, filters, and pagination are unchanged. Follow the returned links: v2 discovery links stay on v2; unchanged resource APIs continue to use v1.

Start every integration here

An API token belongs to one organization. Call /current during setup to verify its assigned organization, token username, and granted scopes. Then call GET /api/organizations/v1 to discover the organizations your token can access. Use a discovered organization ID in organization-specific retrieval requests.

Organization access — Discovery requires organization:read and returns the organizations accessible to your token. Waterly checks access on every retrieval request. /current identifies the token's assigned organization.

Discover accessible organizations

This collection returns the existing v1 organization fields: id, name, and fiscal_year_start_date. Results are ordered by organization ID. Use the v2 organization-by-ID route when you also need addresses.

GET/api/organizations/v1List this token's accessible catalog

Example request

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v1?name=water&limit=50"

Example response

{
  "data": [
    { "id": 123, "name": "Clearwater Utilities", "fiscal_year_start_date": "1901-01-01" }
  ],
  "links": {
    "self": "https://connect.waterly.com/api/organizations/v1?name=water&limit=50",
    "next": null,
    "prev": null
  },
  "meta": { "limit": 50, "has_next": false, "has_prev": false }
}

Query parameter	Behavior
`name`	Optional case-insensitive partial-name search, 1–255 characters after trimming surrounding whitespace. Wildcard characters are treated literally. Only authorized organizations are searched.
`limit`	Optional integer from 1 to 200; defaults to 50.
`cursor`	Opaque page cursor. Follow `links.next` or `links.prev` with the same token, name filter, and limit.

If no accessible organization matches the name filter, data is an empty array. Each request returns one page. Invalid query inputs and cursors return 400; missing or rejected credentials return 401; insufficient scope returns 403.

Select an organization for retrieval

After discovery, use the returned organization ID in retrieval requests. For example, the organization 123 in the response above has these systems, metrics, and data-point routes:

# Systems in the selected organization's data model
curl --digest --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v2/123/data-model?kind=system&limit=50"

# Metrics in the selected organization
curl --digest --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v1/123/metrics?limit=50"

# Data points in the selected organization
curl --digest --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/data-points/v1?organization_id=123&start=2026-10-01T00:00:00Z&end=2026-10-02T00:00:00Z&limit=50"

Data-model and metric retrieval require data-model:read; data-point retrieval requires data-points:read. Each request also verifies that the token can access the selected organization.

Resource list routes such as /api/systems/v1 remain scoped to the token's assigned organization. Use the explicit organization routes above to select an organization. Follow the returned pagination links to preserve the selected organization and filters.

Get the current organization

GET/api/organizations/v2/currentIdentify this token's assigned organization

Example request

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v2/current"

Example response

{
  "data": {
    "organization": {
      "id": 123,
      "name": "Clearwater Utilities",
      "fiscal_year_start_date": "1901-01-01",
      "addresses": []
    },
    "token": {
      "username": "clearwater-reporting",
      "scopes": ["organization:read", "data-model:read", "data-points:read"]
    }
  },
  "links": {
    "self": "https://connect.waterly.com/api/organizations/v2/current",
    "data_model": "https://connect.waterly.com/api/organizations/v2/123/data-model",
    "docs": "https://connect.waterly.com/docs",
    "openapi": "https://connect.waterly.com/openapi.json"
  }
}

Get the organization by ID

After discovering ID 123, the canonical ID route returns the same organization envelope.

GET/api/organizations/v2/{organizationId}

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v2/123"

Discover the organization data model

This cursor-paginated endpoint can return the complete flattened hierarchy or a filtered slice. Use kind for one resource type. To list children, supply both parent_kind and parent_id.

GET/api/organizations/v2/{organizationId}/data-model

Example: list sites in system 40

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v2/123/data-model?kind=site&parent_kind=system&parent_id=40"

Example response

{
  "organization": { "id": 123, "name": "Clearwater Utilities" },
  "data": [{
    "kind": "site",
    "id": 55,
    "name": "North Treatment Plant",
    "parent": { "kind": "system", "id": 40 },
    "order": 1,
    "attributes": { "site_type": "treatment_plant", "addresses": [] }
  }],
  "links": { "self": "...", "next": null, "prev": null },
  "meta": { "limit": 50, "has_next": false, "has_prev": false }
}

Get one data-model item

Use a kind and ID from discovery to retrieve one item. The children link is present when the resource can contain other resources; metrics return null.

GET/api/organizations/v2/{organizationId}/data-model/{kind}/{id}

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v2/123/data-model/site/55"

{
  "data": {
    "kind": "site", "id": 55, "name": "North Treatment Plant",
    "parent": { "kind": "system", "id": 40 },
    "order": 1, "attributes": { "site_type": "treatment_plant", "addresses": [] }
  },
  "links": {
    "self": "https://connect.waterly.com/api/organizations/v2/123/data-model/site/55",
    "children": "https://connect.waterly.com/api/organizations/v2/123/data-model?parent_id=55&parent_kind=site"
  }
}