External User Directory API

A contract API for organizations that maintain their own user directory and want Waterly to synchronize user accounts and role assignments automatically. Your system implements these endpoints — Waterly calls into them to search, look up users, and deliver role-change notifications.

This is an early stage API. If your organization is interested in integrating with the External User Directory API, contact the Waterly Support Team to discuss availability and onboarding requirements before building an implementation.

Contact Waterly Support OpenAPI YAML

Overview

The External User Directory API defines a contract that your system must implement to enable Waterly's user directory sync feature. Unlike most Waterly APIs — where you POST data to Waterly — this contract works in reverse: Waterly calls your endpoints.

Three endpoints are defined. The two query endpoints let Waterly search your directory and look up specific users by their external ID. The one callback endpoint is called by Waterly whenever a user's role is granted or revoked inside the Waterly platform, allowing your system to stay in sync.

POST /search — Waterly sends a search term; you return a list of matching users.
POST /lookupById — Waterly sends a user's external id; you return the full user record.
POST /roleUpdated — Waterly notifies your system when a user's role changes within Waterly.

Query Endpoints

POST /search Search the external user directory

Request Body — application/json

Body must be a UserSearchRequest object.

{
  "searchInput": "Joe",
  "maxResults": 10,
  "inactiveFrom": "2023-09-12"
}

Response — application/json

Return a JSON array of User objects.

[
  {
    "id": "abc123",
    "firstName": "Joe",
    "lastName": "Schmoe",
    "email": "joe@example.com"
  }
]

Response Codes

200OK — Returns a list of matching users (may be empty).

400Bad Request — Malformed input.

500Internal Server Error.

POST /lookupById Look up a single user by their external id

Request Body — application/json

Body must be a UserLookupRequest object.

{
  "id": "abc123"
}

Response Codes

200OK — Returns a single User object.

400Bad Request — Malformed input.

404Not Found — No user with the given id exists in your directory.

500Internal Server Error.

Callback Endpoint

POST /roleUpdated Waterly calls this when a user's role changes

Waterly calls this endpoint on your system whenever a user's role is granted or revoked within the Waterly platform. Implement this to keep your local access control state in sync with what Waterly knows about the user.

Request Body Waterly Will Send — application/json

Waterly will POST a RoleUpdatedCallbackRequest to this endpoint.

{
  "userId": "abc123",
  "action": "Grant",
  "role": "Operator",
  "systemName": "Lake Zebra, IL",
  "systemId": 10,
  "systemURL": "https://app.waterlyapp.com/accounts/10"
}

Expected Response Codes

200OK — Callback acknowledged with a response body.

204No Content — Callback acknowledged, no body returned. Both 200 and 204 are accepted.

400Bad Request — Malformed input.

500Internal Server Error.

Schemas

User

A user record from your external directory. Returned by /search (as an array) and /lookupById (as a single object).

Field	Type	Required	Description
id	string	Yes	Unique, stable, opaque identifier. Waterly uses this for synchronization only and does not display or interpret it.e.g. "abc123"
firstName	string	Yes	User's first name.e.g. "Joe"
lastName	string	Yes	User's last name.e.g. "Schmoe"
email	string (email)	Yes	User's email address.e.g. "joe@example.com"
metadataJSON	string	Optional	Arbitrary metadata as a string-encoded JSON value. Waterly passes this through without interpretation.e.g. "{\"dept\":\"ops\"}"

UserSearchRequest

Request body for POST /search. Waterly sends a search term and optional filters.

Field	Type	Required	Description
searchInput	string	Yes	Search term. May be a partial name, email substring, or other fuzzy-match input.e.g. "Joe"
maxResults	integer	Optional	Hint from Waterly for the maximum number of results desired. Your implementation may return fewer.e.g. 10
inactiveFrom	string (date)	Optional	ISO 8601 date. Filter results to exclude users inactive before this date.e.g. "2023-09-12"

UserLookupRequest

Request body for POST /lookupById.

Field	Type	Required	Description
id	string	Yes	The external id of the user to retrieve.e.g. "abc123"

RoleUpdatedCallbackRequest

Body that Waterly sends to POST /roleUpdated when a user's role changes within the Waterly platform.

Field	Type	Required	Description
userId	string	Yes	External id of the user whose role was modified.e.g. "abc123"
action	RoleChangeAction	Yes	Whether the role was granted or revoked. GrantRevoke
role	Role	Yes	The role that was granted or revoked. ReadOnlyOperatorSupervisor
systemName	string	Yes	Display name of the water or wastewater system where access changed.e.g. "Lake Zebra, IL"
systemId	integer	Yes	Waterly's internal identifier for the system.e.g. 10
systemURL	string (uri)	Yes	Waterly URL for the system.e.g. "https://app.waterlyapp.com/accounts/10"

Enums

RoleChangeAction
Grant	Access to the role was granted to this user.
Revoke	Access to the role was revoked from this user.

Role
ReadOnly	Read-only access to data within the system.
Operator	Standard operator access with data entry capabilities.
Supervisor	Elevated access with administrative capabilities.