> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nectarclimate.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connections
> Connect utility accounts to automatically collect bills and usage data on an ongoing basis.
Need help in this area? See [Data Input FAQ](/platform/data-input/faq).
## What is a connection?
Think of a [connection](/platform/glossary#connection) like setting up automatic bill pay at your bank — except instead of paying bills, Nectar is downloading and reading them for you. You give Nectar the login credentials for a utility website (like ConEdison, PG\&E, or Duke Energy), and Nectar logs in on your behalf every week to grab new bills and extract the data.
Once a connection is set up, you never have to visit that utility website again. Nectar handles it all: finding new bills, downloading the PDFs, reading them with AI, and filing the data in the right place. It's the core of how Nectar works, and it's what saves most customers dozens of hours every month.
## How to create a connection
Go to **Data Input > Connections** and click **Online Accounts** (or **Connect account**). Search for your utility company by name or URL — Nectar supports thousands of providers. For example, type "ConEdison" or "Pacific Gas" and select the right one from the list. If your provider isn't listed, choose **Custom provider**, enter the utility name and website URL, then **Continue with custom provider** so Nectar can set up the connection to that portal.
Enter the username and password for the utility website — the same login you'd use if you were downloading a bill yourself. If someone else manages that account, use their credentials with permission. If the utility requires a text message code or authenticator app, you'll complete that step here too.
Tell Nectar how to handle the data: which sites the account covers, what type of utility it is, and how far back to collect bills. See the detailed breakdown of each setting below.
Once you submit, Nectar gets to work. The first data pull typically completes within a few days. After that, Nectar checks the utility portal weekly for new bills — automatically, with no effort from you.
## Configuration settings explained
When you create a connection, the configuration step has several settings that control how Nectar collects and processes data. Here's what each one means in plain terms:
### Sites
**Which of your buildings does this utility account serve?**
For example, if your ConEdison login covers both your Manhattan and Brooklyn offices, select both sites. This tells Nectar where to file the bills and usage data. If you're not sure which sites an account covers, it's fine to select your best guess — you can always reassign data later.
### Datasource types
**What types of utility service does this account cover?**
Most utility accounts are straightforward — just electricity, or just natural gas. But some combined accounts cover multiple services (like electricity and gas on the same bill). Select all the types that apply: **Electricity**, **Gas**, **Water**, **Waste**, **Fuel**, **Solar**, or **District** (steam, chilled water, hot water). Nectar will only process bills that match your selections.
### Data collection start date
**How far back should Nectar look for bills?**
You have three choices:
| Mode | When to use it | Example |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Company default** | Use whatever start date your company is configured with. Good for keeping all your connections consistent. | Your company default is set to January 2023, so every new connection pulls bills back to that date. |
| **Current month** | Only collect bills from this month forward. Good if you only care about future data and don't need historical bills. | It's March 2026 — Nectar will only grab bills from March onward. |
| **Custom date** | Pick a specific date. Useful when you need historical data going back to a particular point. | You're preparing a 2024 emissions report, so you set the start date to January 1, 2024. |
If a specific account within the connection has its own start date set (in the account's
settings), that account-level setting takes priority over the connection-level one.
### Multiply by occupancy
**For shared buildings where you only lease a portion of the space.**
This setting appears whenever your company has the occupancy adjustment feature enabled (configured in **Settings > Company**).
When a site's occupancy adjustment mode is set to **Per connection**, this checkbox controls whether this connection's usage data is multiplied by the site's occupancy percentage. For example, if the site's occupancy is 40% and this box is checked, a bill showing 10,000 kWh becomes 4,000 kWh in your reports. Leave this off if the utility account already reflects only your space, or if the site uses **All data** mode (which applies occupancy regardless of this checkbox).
This checkbox has no effect when the site's adjustment mode is **Disabled** or **All data** — it is only consulted in **Per connection** mode. See [Occupancy adjustment](/platform/methodology/occupancy) for the full picture.
### Custom container
**For waste and fuel accounts only.**
If your waste hauler picks up a specific dumpster, or a fuel company delivers to a specific tank, enter the container details (name, size, and units) here. Nectar uses this information to calculate total consumption from delivery records. For example, if you have a 500-gallon propane tank and receive deliveries of 250 gallons at a time, Nectar can track your total fuel consumption accurately.
### Owner email
**Who should receive notifications about this connection?**
Enter the email address of the person who manages this utility account. They'll get notified if the connection encounters an error (like a changed password) or when new data is collected. Usually this is you, but for accounts you manage for someone else it might be a facility manager or site contact.
### MFA requirement
**Does this utility website require a security code to log in?**
Some utility portals send a text message code, use an authenticator app, or ask security questions during login. If yours does, check this box. During setup you may complete a one-time login in the browser (including MFA), then Nectar walks you through **MFA forwarding** — how SMS or email codes are delivered so Nectar can complete automated logins on the weekly schedule. If forwarding stops working or the portal rotates MFA, you may need to **Reconnect** and refresh that setup later.
**Need utility-specific instructions?** See the [MFA overview](/platform/data-input/mfa) for
detailed setup guides per utility provider and a triage flow for fixing MFA issues.
## What to expect after connecting
* **First data**: Nectar typically completes the first collection within a few hours; allow up to 48 hours in some cases. How many bills you get depends on the start date setting and how much history the utility portal makes available (most keep 12 to 24 months).
* **Weekly checks**: After the initial pull, Nectar checks the utility portal every week for new bills. You don't need to do anything — new bills are downloaded and processed automatically.
* **Notifications**: The owner email receives updates when new data arrives or when an issue needs attention.
### What to share with the account holder
If you're an energy consultant connecting someone else's utility account, here's a simple explanation you can pass along:
> "We use a platform called Nectar to automatically collect your utility data. We'll need the login credentials for your utility website — the same username and password you'd use to view your bills online. Nectar logs in weekly to download new bills and extract the data. Your credentials are encrypted and stored securely. You can also connect the account yourself through a secure link we'll send you."
If the account holder is uncomfortable sharing credentials directly, consider sending them an [invitation](/platform/data-input/invitations) instead — they enter their own login without you seeing it.
## Connection status
After you create a connection, its **status** tells you whether data is flowing smoothly or something needs your attention. Plain-language definitions for every status — what it means and what to do — live in one place: **[Glossary — Connection status](/platform/glossary#connection-status)**.
For API field names and programmatic handling, see [Connection statuses](/developer-guide/connection-statuses) in the Developer guide.
## Managing connections
**Deactivate and activate** — Need to temporarily stop data collection? Open the actions menu on the connection and click **Deactivate connection**. The status changes to **Deactivated**, weekly checks stop, and no new bills are collected — but every bill, account, and meter that was already collected stays in place. Click **Activate connection** when you're ready and the next weekly check picks up from where it left off. Deactivation is reversible at any time, so prefer it over deleting whenever you might come back to the connection.
If you manage connections via the API, deactivate and activate map to `PATCH /connection/{id}/details` with `{"isActive": false}` and `{"isActive": true}` — see the [Connection lifecycle](/developer-guide/connection-lifecycle#deactivating-and-activating-a-connection) developer guide.
**Delete** — Permanently remove a connection you no longer need. Deletion is the right choice when the utility account itself is closed or you've moved to a different provider. If you might come back to the connection later, **deactivate it instead** — deactivation keeps everything in place and you can activate in one click.
**Reconnect** — If a connection enters an error state (password changed, MFA expired, etc.), use the **Reconnect** action. For most credential errors you re-enter username and password in the browser; for **MFA token expired**, Nectar opens **MFA forwarding** setup instead — configure how codes reach Nectar for automated logins. Reconnecting preserves the link to all existing accounts, meters, and historical data. Don't create a new connection for the same utility account — always reconnect instead.
**Send an invitation** — Need the account holder to connect their own account? Open **Data Input > Invitations**. You can pre-fill the utility URL, sites, and utility types so they have less to fill in. See [Invitations](/platform/data-input/invitations) for details.
## Bulk import connections
Create dozens of connections in a single upload — both **online** (utility portal logins) and **email** (forwarded bills) connection types are supported in the same template. The platform parses your file in your browser, lets you match columns, and shows validation errors inline so you can fix them without re-uploading.
### Steps
1. Go to **Data Input > Connections** and click **Bulk import**.
2. Click **Download template** in the upload area and choose either **Excel (.xlsx)** or **CSV (.csv)** — both files have the same columns and example rows, so pick whichever your tooling prefers.
3. Drop your filled file. Required columns are auto-mapped by header name; review the mapping in step 2.
4. Review and fix rows inline. Cells with errors show a red border — click a cell to edit it.
5. Click **Import N connections** when there are zero errors.
**This file contains credentials.** Online rows include plaintext usernames and passwords.
Avoid sharing the file by email; prefer encrypted file shares, and delete the local copy after a
successful import.
### Always-required columns
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connection type** | `ONLINE` (portal login + scrape) or `EMAIL` (vendor forwards bills to your nectar inbox). |
| **Utility provider** | Datasource brand name, e.g. `Duke Energy`. The platform resolves this to an existing datasource by name + URL similarity, or auto-creates a new one for review by Nectar. |
| **Utility login URL** | The portal entry URL for the provider. Required even when the platform already knows the datasource — it confirms you mean the same brand at the same portal. |
| **Sites** | Comma-separated site names. Must match exactly to existing sites in this company (case-insensitive). |
| **Owner email** | Workflow owner — receives reconnection requests if the connection enters an error state. |
### Required for `ONLINE` rows
| Field | Description |
| ------------ | --------------------------------------------------------------- |
| **Username** | Utility portal username. |
| **Password** | Utility portal password. Encrypted on the server using AES-128. |
### Required for `EMAIL` rows
| Field | Description |
| ------------------- | ----------------------------------------------------------------- |
| **Sender emails** | Comma-separated `From:` addresses your vendor uses to send bills. |
| **Email frequency** | `MONTHLY`, `QUARTERLY`, `ANNUALLY`, or `IRREGULARLY`. |
### Optional columns (any row)
| Field | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Country** | ISO-2 country code (default `US`) — controls which proxy region is used for online portals. |
| **Datasource types** | Comma-separated commodity codes (e.g. `ELECTRICITY, GAS`). Defaults to the datasource's own list when blank. |
| **Data collection start date** | `YYYY-MM-DD` — when data collection should begin. Defaults to your company default. |
| **Multiply by occupancy** | `true` for commercial leased buildings where billed usage is the whole-floor total. |
| **Requires MFA** | `true` for portals that require an MFA code. See callout below. |
| **Custom container name / size / units** | For waste and fuel accounts that bill by container delivery. |
| **Notes** | Free text. |
**MFA-required connections need a follow-up step.** Rows with `Requires MFA = true` will be
created but cannot sync until you open each connection and finish MFA forwarding setup. The
completion toast tells you how many follow-ups are needed; the connections page surfaces the same
state via the connection status.
### Limits
* Up to 200 connections per import.
* Sites must already exist in your sites — bulk-create sites first if needed (see [Sites — Bulk import](/platform/sites/overview#bulk-import-sites)).
* Security questions (Q\&A pairs) are not supported in bulk. Set those up via the per-connection edit screen after import.
### What happens after import
The same things that happen for any individual [connection](/platform/glossary#connection) — Nectar starts collecting bills on the next weekly cycle, the owner email receives status notifications, and connections that fail will surface as `Password Incorrect`, `MFA Token Expired`, or similar in the [Connection status](/platform/glossary#connection-status) list.
## FAQ
Yes, but it's encrypted. Nectar stores credentials using AES-128 encryption so it can log in to the utility portal on your behalf. The encrypted credentials are never visible to other users and cannot be retrieved in plain text — not even by Nectar staff. Nectar holds SOC 2 Type 1 and Type 2 certifications for security.
The connection will show a **Password Incorrect** status at the next weekly check. You'll receive
an email notification. Use the **Reconnect** action to enter the new password. This is the most
common connection issue and takes about 30 seconds to fix.
If you go through setup again with the same utility provider and username for your company, Nectar
treats it as the same [connection](/platform/glossary#connection) and updates that record—for
example, new credentials or site selections—instead of creating a second connection. You should
still use **Reconnect** when you mean to fix a failed connection, but an accidental duplicate submit
will not leave you with two separate connections for that login.
You should not try to maintain two separate connections for the same utility login—that can cause
duplicate data and confusion. Nectar matches on the same provider and username for your company and
keeps a single connection, updating it if you submit again. To change credentials or fix errors,
edit the existing connection or use **Reconnect** rather than starting over as if it were new.
There's no hard limit on the number of connections. Nectar customers range from a handful of
connections to thousands. If you're planning a large rollout, contact
[support@nectarclimate.com](mailto:support@nectarclimate.com) to discuss the best onboarding
approach.
Utility websites occasionally update their portals, which can temporarily disrupt connections.
Nectar's engineering team monitors for these changes and typically updates support within days. If
your connection breaks after a utility portal redesign, it will show **Under Investigation** while
the team works on it.
Connections are checked on a **weekly** cycle. After each check, any new bills found are
downloaded and processed. Most utility companies post new bills monthly, so a weekly check ensures
Nectar grabs them promptly.
The most common causes are a changed password, an expired MFA token, or a temporary utility
website outage. Check the connection status for the specific error and follow the guidance in the
[Glossary — Connection status](/platform/glossary#connection-status). If the status says **Under
Investigation**, the Nectar team is already on it.
Yes. Nectar supports utility providers globally, including across Europe, Asia-Pacific, and other
international markets. The platform handles different date formats, currencies, and units of
measure. If your provider isn't listed, contact
[support@nectarclimate.com](mailto:support@nectarclimate.com) to request it.
Deactivating stops the weekly collection check and sets the connection's status to **Deactivated** — but
every bill, meter, and account that's already been collected stays exactly where it is. Deactivation is
fully reversible: open the actions menu and click **Activate connection** whenever you're ready, and
the next weekly check picks up from there. Think of it as putting a subscription on hold rather
than canceling it. If you're done with the connection for good (the utility account itself is
closed, for example), use **Delete** instead.
Go to **Data Input > Connections**, open the connection, and click **Reconnect**. For **Password incorrect**, **New password needed**, or **Additional credentials needed**, enter updated credentials in the embedded browser and submit. For **MFA token expired**, Nectar opens **MFA forwarding** setup (not the password screen) — you configure or refresh how login codes reach Nectar, confirm, or disable MFA if the portal no longer requires it. Nectar will retry collection after you finish. All existing data is preserved.