Watershed

The Watershed integration connects Nectar to Watershed’s enterprise climate platform. Nectar pushes utility data directly via the Watershed API — no manual file import required.

​

Authentication

Nectar supports two authentication methods for connecting to the Watershed API:

​

OAuth 2.0 Client Credentials (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 time (in minutes).
4. Save the Client Secret securely — Watershed will not display it again.
5. In Nectar, go to Data Export > Integrations > Watershed and choose OAuth Client Credentials 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 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. Authentication — Choose OAuth or Bearer Token and enter credentials.
2. Connection test — Nectar validates the credentials by fetching available datasets from Watershed.
3. Dataset selection — Choose which upload schemas to use for electricity and gas.
4. Site mapping — Map Nectar sites to Watershed building identifiers (include or exclude each site).

Once setup is complete, the integration hub shows Connected and 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.
   • 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. Each record includes:

​

FAQ