OpenWater is one of the integrations where Rhythm stores a connection record without showing it in Console. If your organization uses OpenWater, you create, change, remove, and read that connection through the API. This article also explains how to change several connection records for any integration in one API request. If you want a broader introduction before using these endpoints, Rhythm's public API documentation site includes a quick-start guide, task-based guides, a product-area reference, AI-powered search, a "Try It" mode for testing calls, and sample code in several client languages.
Prerequisites
- Your Rhythm account must be entitled to the OpenWater integration before you can create or change an OpenWater account record. You do not need this entitlement to read or remove one.
- The API caller must be signed in within your Rhythm account. Member-portal sign-ins are refused. You can use a machine-to-machine API access token instead of a person's login, so the integration can request data directly without each end user's credentials, as long as the request is authorized for your account and the requested data exists.
- Your API client ID and client secret are tied to a single Rhythm account. Your sandbox is a different account from your live account, so a client credential issued for your live account can still receive a token but cannot access your sandbox records, and the same applies in reverse.
- Each request also needs your Rhythm account's own identifier in the request, not only in the sign-in credential. This is easy to miss if you are looking only at the general API reference page instead of the request examples for these endpoints.
Recording an OpenWater Account
OpenWater has no Console screen, so you record your organization’s OpenWater account by calling the API directly. The record stores only a name and, if you use them, your Rhythm account’s custom field values for this record type. It does not store an OpenWater credential or identifier.
| Operation | What it does |
|---|---|
| Create | Records a new OpenWater account for your organization, with a name and optional custom field values |
| Change | Updates the name or custom field values on an existing OpenWater account |
| Read or list | Returns one or all OpenWater accounts for your organization |
| Remove | Deletes an OpenWater account your organization no longer needs |
When you create or change an OpenWater account record, Rhythm checks your Rhythm account’s OpenWater entitlement before saving. If your Rhythm account has no permission profile at all, Rhythm treats it as entitled. If your entitlement is later withdrawn, you can still read and remove existing OpenWater account records, but you can no longer change them.
Warning
Removing an OpenWater account does not check your entitlement, so you can delete a record even after your Rhythm account’s access to OpenWater has ended. The API does not include a confirmation step, so the delete takes effect as soon as the request sends it.
If you store your own custom field values on an OpenWater account, those custom fields must already exist for this record type in Platform before you can save them.
Changing Several Connections in One Request
Separately from OpenWater, the API includes a batch route that lets you create, change, or delete several connection records in one request. You can use it across any integration that Integrations supports instead of calling the API once for each change. This batch route is only for connection records. There is no single endpoint that exports all of your Rhythm account's data at once; to retrieve other data, call the API for each resource you need, in batches, the same way.
Each operation in the batch is evaluated on its own. If one operation fails because it references a connection that does not exist, or because your Rhythm account is not entitled to that integration, the other operations in the same batch do not automatically fail with it.
Warning
A batch request is still checked against your Rhythm account like any single request. It must be sent by a caller signed in within your Rhythm account, and a request that names a different account is refused. The available documentation does not confirm whether each operation inside the batch runs every check that the same operation would run on its own, or whether a partial failure leaves your connections partly changed. Review the response for each operation instead of assuming the whole batch succeeded or failed together.
Permissions
These operations need an API caller signed in within your Rhythm account. This article does not name a more specific permission because the available documentation does not declare one for reading, writing, or removing an OpenWater account, or for the batch route, beyond that basic account membership. Member-portal sign-ins are refused for OpenWater read and write operations.
Validation and Errors
| What you see | Cause | Fix |
|---|---|---|
| The save is refused with a message about your account not having access to enable this integration | Your Rhythm account is not entitled to OpenWater | Confirm entitlement with your Customer Success Manager before retrying |
| A date custom field value is refused on save | The value sent is not a valid date | Correct the value and resend |
| One operation in a batch request fails while others succeed | Each operation in a batch is evaluated independently | Check the response for each operation instead of assuming the whole batch succeeded or failed as a unit |