Watershed

The Watershed integration connects Nectar to Watershed’s enterprise climate platform. You can push utility data via the Watershed API, or use file download mode to generate an XLSX for manual upload in Watershed — no API credentials required in that mode.

​

Authentication

When you choose an API delivery mode, Nectar supports two authentication methods for connecting to the Watershed API:

​

OAuth 2.0 (recommended)

OAuth 2.0 is Watershed’s enterprise-grade authentication standard. It uses short-lived access tokens instead of a static API key, reducing risk if credentials are compromised. To set up OAuth 2.0:

1. Log in to the Watershed portal and navigate to the API section under Organization settings.
2. Click Create credentials to generate a new Client ID and Client Secret.
3. Give the client a name, assign a role, and set the token expiration. In Nectar’s credentials step, set token expiration to 86400 seconds and grant admin access.
4. Save the Client Secret securely — Watershed will not display it again.
5. In Nectar, go to Data Export > Integrations > Watershed and choose OAuth 2.0 as the authentication mode.
6. Enter the Client ID and Client Secret. Nectar handles token exchange and renewal automatically.

Nectar exchanges credentials for an access token by calling Watershed’s /oauth/token endpoint with grant_type=client_credentials. Tokens are refreshed automatically before expiration — Watershed does not use refresh tokens.

​

Bearer Token (legacy)

Static long-lived API keys. This method is simpler to configure but less secure — if the key is compromised, it remains valid until manually rotated. To set up a Bearer Token:

1. Generate a Bearer Token API key in the Watershed portal under Organization settings > API.
2. In Nectar, choose Bearer Token (API key) as the authentication mode and paste the key.

​

Regional endpoints

Nectar supports both Watershed API regions: Select the region that matches your Watershed organization during setup. The same credentials work regardless of region — only the API endpoint differs.

​

Setup

Navigate to Data Export > Integrations > Watershed and complete setup from Settings > Company > Integrations > Watershed or the setup wizard when prompted. Steps include:

1. Delivery mode — Choose OAuth 2.0, API key (Bearer Token), or File download, and select your Watershed region when using an API mode. File download skips credential and dataset steps and is ready for XLSX exports immediately.
2. Credentials and connection test (API modes) — Enter OAuth or Bearer credentials. Nectar validates them by fetching available datasets from Watershed.
3. Dataset selection (API modes) — Choose which upload schemas to use for electricity, gas, and water when enabled.
4. Site mapping (API modes) — Map Nectar sites to Watershed building identifiers (include or exclude each site).

Once setup is complete, the integration hub shows Connected (API mode) or File export only (file download). API push is available when every site is configured and at least one data source is enabled.

​

Integration hub

The Watershed integration page at Data Export > Integrations > Watershed is a single-page layout:

• Page header — Archive (deactivate the integration) and Settings (credentials, site mapping, datasets)
• Warning banners — Invalid credentials, unconfigured sites, excluded sites, or disabled data sources block API push until resolved in settings
• Status card — Connected, File export only, or setup warnings, with an Export button that opens the export dialog
• Recent syncs & downloads — Latest Watershed exports and API pushes. Click a sync row to open the upload detail page; click a download row for the export detail sheet
• Data comparison — When API push is fully enabled, month-by-month Nectar vs Watershed usage with discrepancy statuses (same scope as the upload detail comparison)

​

Exporting

Click Export to open the export dialog. Configure utility type, date range, and sites, and choose whether to push the data to Watershed via API or download an XLSX for manual upload. A progress dialog shows upload status. The sync process follows Watershed’s Data Ingestion API workflow:

1. Create upload — Registers a new upload with Watershed, specifying the dataset and schema.
2. Load data — Sends usage records in batches (up to 10,000 records per request).
3. Validate — Watershed checks the uploaded data against the schema and reports errors.
4. Submit — Marks the upload as final and associates it with a measurement task.

​

Recent syncs & downloads

The history card lists your latest Watershed exports and API pushes. Click a sync row to open the upload detail page. Click a download row to open the export detail sheet with configuration and a re-download link. Use Data Export > History for the full cross-integration log.

​

Data comparison — find and resolve discrepancies

When API push is fully configured, the Data comparison section on the hub reconciles what Watershed holds against your Nectar data. Unlike Metrio and Sphera, Watershed data cannot be edited once submitted, so this view is for finding discrepancies and deciding what to re-upload — there are no inline Push/Sync buttons. How to use it:

1. Set the scope with the filters:
   • Year (required) — The comparison always covers one calendar year; clearing it resets to the current year.
   • Utility type — Electricity, gas, or water. Only the utility types enabled for your integration appear. Water uploads include potable and reclaimed supply only — sewer and wastewater discharge are not sent to Watershed.
   • Sites — Narrow to specific mapped sites. Only sites actively mapped to a Watershed building participate.
   • Datasets — Choose which Watershed uploads to count. All submitted and validated uploads are selected by default.
2. Read the usage chart — Nectar and Watershed monthly totals are plotted side by side. Click a month to open the aggregation inspector for the selected sites and commodity — this shows exactly which Nectar bills and meters make up that month’s total, so you can see why the two sides differ.
3. Scan the monthly comparison table — Each row shows the month, Nectar value, Watershed value, the percentage difference (red = Watershed lower, amber = Watershed higher), and a status.

Statuses:

• Synced — Watershed matches your data for that month
• Diff — Both sides have data but the values differ
• Not on Watershed — Nectar has data Watershed never received
• Missing in Nectar — Watershed holds a value your data no longer produces

Resolving discrepancies: Because Watershed uploads are immutable, correct the data at the source and re-upload:

1. Use the month click → aggregation inspector to confirm whether the gap is a Nectar data issue (missing or flagged bills) or a stale Watershed upload.
2. If Nectar is wrong, fix the bills in Data Inventory, then run a new export for the affected scope.
3. If Watershed is wrong, delete the affected upload in your Watershed dashboard first, then re-export from Nectar with Upload to Watershed enabled.

New uploads appear as additional datasets in the comparison once Watershed validates them.

​

Upload detail page

Click a sync in the recent history card to open the upload detail page. It includes:

• Upload header — Name, status, and date
• Comparison view — Nectar vs Watershed data for the upload’s scope
• Contributing data — Bills and meters that were included in the upload

​

Data format

Nectar sends aggregated monthly utility usage to Watershed. Electricity and gas records commonly include: When water is enabled for your integration, Nectar also sends water usage to Watershed. Water uploads include potable and reclaimed supply only — sewer and wastewater discharge are not sent.

​

FAQ