Connection lifecycle

For platform users: See the Connections page for dashboard-level guidance, or the Troubleshooting guide for step-by-step resolution instructions.

Overview

A connection represents a link between Nectar and a utility provider. After creation, a connection moves through a series of statuses as Nectar authenticates, discovers accounts, and collects data. Your integration should monitor these statuses and respond appropriately — some require action from you or your end user, while others resolve automatically.

Status flow

Connections follow this general lifecycle:

What each status means for your integration

Healthy statuses — no action needed

Status	API value	What’s happening	What to do
Pending	`PENDING`	Connection was just created and is waiting for the first check.	Wait. The first check typically runs within a few days.
Connected	`CONNECTED`	Nectar can log in and is collecting data on its weekly schedule.	Nothing — data is flowing.
Under Investigation	`UNDER_INVESTIGATION`	Nectar’s team has flagged this connection for review.	Wait for resolution. Email [email protected] for a status update if needed.

Credential errors — user action required

These statuses mean data collection is stopped until the end user provides updated credentials. Your integration should surface these to the user and provide a way to fix them.

Status	API value	Cause	Required action
Password Incorrect	`PASSWORD_INCORRECT`	The utility website rejected the stored credentials. The user likely changed their password.	User must provide the updated password. Create a reconnect invitation or update credentials through the connection edit flow.
MFA Token Expired	`MFA_TOKEN_EXPIRED`	Automated login can’t complete MFA — codes aren’t reaching Nectar or the MFA session expired.	Walk the end customer through the MFA recommendation ladder: upload documents, disable MFA on the portal, or configure one of the forwarding strategies via a reconnect invitation.
New Password Needed	`NEW_PASSWORD_NEEDED`	The utility portal is forcing a password reset (common every 60–90 days on some providers).	User must first reset their password on the utility website directly, then provide the new password to Nectar via a reconnect invitation or credential update.
Additional Credentials Needed	`ADDITIONAL_CREDENTIALS_NEEDED`	The portal is requesting extra verification — security questions, a PIN, or identity confirmation.	User must provide the additional information. Create a reconnect invitation for them to complete the flow.

Reconnect invitations are the recommended way to handle credential errors and MFA forwarding issues. They let the end user complete the hosted reconnect or MFA setup flow without sharing passwords with your application. See Connection invitations. The legacy magic link endpoints still work for backward compatibility.

Provider errors — automatic retry

These statuses are caused by issues on the utility provider’s side. Nectar retries automatically on the next weekly check. No action is required, but you may want to surface them to users for visibility.

Status	API value	Cause	Expected resolution
Website Down	`WEBSITE_DOWN`	The utility provider’s website is temporarily unavailable.	Resolves automatically when the provider comes back online. Usually within a few days.
URL Inaccessible	`URL_INACCESSIBLE`	The provider URL cannot be reached — the site may have moved or changed domains.	If persistent, verify the URL is still valid. Email [email protected] if the provider has changed their website.
No Accounts Found	`NO_ACCOUNTS_FOUND`	Nectar logged in successfully but found no utility accounts.	May resolve on next check. If persistent, the login may be for a different service (payment-only portal) or accounts may have been closed.
Other Error	`OTHER_ERROR`	An unexpected issue not covered by other statuses.	May resolve on retry. If persistent, email [email protected] with the connection ID and company name.

System statuses

Status	API value	What it means
Company Inactive	`COMPANY_INACTIVE`	The parent company has been deactivated. All connections under it stop running. Email [email protected] to reactivate.
Deactivated	`DEACTIVATED`	Data collection has been deactivated for this connection via `isActive: false`. Historical data and documents are preserved. To activate, send `PATCH /connection/{id}/details` with `{"isActive": true}`.

Deactivating and activating a connection

You can deactivate a connection to stop data collection without losing any historical data. Deactivated connections preserve all bills, accounts, and meter usage that were collected before the deactivation.

# Deactivate data collection
curl -X PATCH 'https://external.nectarclimate.com/v2.2/connection/{connectionId}/details' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"isActive": false}'

The connection’s status field will reflect as DEACTIVATED until you activate it.

# Activate data collection
curl -X PATCH 'https://external.nectarclimate.com/v2.2/connection/{connectionId}/details' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"isActive": true}'

When you activate, the connection’s status reverts to its previous operational value (e.g., CONNECTED or whatever scrape outcome it had before the deactivation), and a fresh data collection cycle begins.

Handling status changes in your integration

The most efficient way to track connection status changes is via webhooks. Subscribe to these event types:

Event type	When it fires
`connection.created.v2`	A new connection is created via the API, a connection invitation (or legacy magic link), or the platform.
`connection.updated.v2`	Any connection field changes — status, credentials, accounts, site assignments, or other details. Includes `protectedChanges` and `old` fields so you can see what changed.
`connection.validated.v2`	A connection’s status transitions (e.g., `PENDING` → `CONNECTED`, `CONNECTED` → `PASSWORD_INCORRECT`, or recovery back to `CONNECTED`).

The connection.updated.v2 payload includes a protectedChanges array listing which fields changed, and an old object with the previous values:

{
  "eventType": "connection.updated.v2",
  "protectedChanges": ["status"],
  "old": {
    "status": "PENDING"
  },
  "externalId": "my-conn-001",
  "status": "CONNECTED",
  "id": "a6c70a54-34e7-4277-80b0-412869ce087c",
  ...
}

Poll for status

If webhooks aren’t suitable for your architecture, poll the connection detail endpoint periodically:

curl -X GET 'https://external.nectarclimate.com/v2.2/connection/{connectionId}/details' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

Or list all connections for a company and filter by status:

curl -X GET 'https://external.nectarclimate.com/v2.2/connection/company/{companyId}?status=PASSWORD_INCORRECT' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

Recommended integration pattern

Monitor for credential errors

Subscribe to connection.updated.v2 webhooks. When a status change arrives, check if the new status is one of the four credential errors: PASSWORD_INCORRECT, MFA_TOKEN_EXPIRED, NEW_PASSWORD_NEEDED, or ADDITIONAL_CREDENTIALS_NEEDED.

Notify the end user

Surface the error in your application’s UI. Include the connection’s utility provider name (from the datasource.name field) and a clear description of what’s needed.

Create a reconnect invitation

Use the connection-invitation endpoint to generate a secure URL the user can visit to update their credentials. See Connection invitations for details.For MFA_TOKEN_EXPIRED, also point the customer to document upload as the recommended first option — uploaded bills produce the same downstream data and avoid MFA configuration entirely. See MFA integration.

Confirm resolution

After the user completes the flow, a new connection.updated.v2 webhook fires with status: "CONNECTED". Update your UI accordingly.

Account lifecycle

Each connection contains one or more accounts — individual utility accounts discovered on the provider’s website. Accounts have their own status and tracking lifecycle.

Account statuses

Status	API value	Description
Detected	`DETECTED`	Account discovered but not yet confirmed.
Onboarded	`ONBOARDED`	Account confirmed and actively tracked.
Pull Completed	`PULL_COMPLETED`	Data has been successfully collected and processed.
No Documents Found	`NO_DOCUMENTS_FOUND`	No bills were found for this account.
PDF Download Failed	`PDF_DOWNLOAD_FAILED`	Bills exist but could not be downloaded.
Account Not Found	`ACCOUNT_NOT_FOUND`	Account is no longer visible on the provider’s website.
Workflow Not Accessible	`WORKFLOW_NOT_ACCESSIBLE`	The parent connection has an issue (e.g., password incorrect).
Other Error	`OTHER_ERROR`	Unexpected error during collection.
Old Account	`OLD_ACCOUNT`	Account is closed — no new data expected.
Duplicate	`DUPLICATE`	This account duplicates another tracked account.
Customer Not Tracked	`CUSTOMER_NOT_TRACKED`	You chose not to track this account.
Company Inactive	`COMPANY_INACTIVE`	Parent company is deactivated.

Account tracking

After Nectar discovers accounts on a connection, you can confirm which ones to track using the confirm endpoint:

# Enable tracking for discovered accounts
curl -X PATCH 'https://external.nectarclimate.com/v2.2/connection/{connectionId}/status' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"confirm": true}'

Each account also has a trackingStatus field:

Value	Meaning
`UNSET`	No tracking decision has been made yet.
`ENABLED`	Account is actively tracked.
`DISABLED`	Account tracking has been turned off.

Check frequency

Connections are checked weekly for new data.
Terminal account statuses (OLD_ACCOUNT, DUPLICATE, CUSTOMER_NOT_TRACKED) are not re-checked.
Credential errors (PASSWORD_INCORRECT, MFA_TOKEN_EXPIRED, NEW_PASSWORD_NEEDED, ADDITIONAL_CREDENTIALS_NEEDED) stop collection until the user takes action.
All other statuses (including provider errors like WEBSITE_DOWN) are retried on the next weekly cycle.

Connection API endpoints

Endpoint	Method	Description
`/connection/company/{companyId}`	GET	List all connections for a company. Supports `status` filter.
`/connection/company/{companyId}`	POST	Create a new connection with credentials, site assignments, and optional external ID.
`/connection/{connectionId}/details`	GET	Get full connection details including accounts.
`/connection/{connectionId}/details`	PATCH	Update connection settings (external ID, start date, occupancy multiplier).
`/connection/{connectionId}/status`	PATCH	Confirm or reject discovered accounts.
`/invitation/company/{companyId}`	POST	Create a contributor invitation for a new connection.
`/invitation/connection/{connectionId}`	POST	Create a reconnect invitation for an existing connection.

Connection statuses

Quick reference of all status values

Connection invitations

Let users create or update connections in a secure hosted UI

MFA integration

Decision tree and shareable one-pager for MFA-protected accounts

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

Overview

Status flow

What each status means for your integration

Healthy statuses — no action needed

Credential errors — user action required

Provider errors — automatic retry

System statuses

Deactivating and activating a connection

Handling status changes in your integration

Poll for status

Recommended integration pattern

Account lifecycle

Account statuses

Account tracking

Check frequency

Connection API endpoints

Connection statuses

Connection invitations

MFA integration

​Overview

​Status flow

​What each status means for your integration

​Healthy statuses — no action needed

​Credential errors — user action required

​Provider errors — automatic retry

​System statuses

​Deactivating and activating a connection

​Handling status changes in your integration

​Subscribe to webhooks

​Poll for status

​Recommended integration pattern

​Account lifecycle

​Account statuses

​Account tracking

​Check frequency

​Connection API endpoints

​Related pages

Connection statuses

Connection invitations

MFA integration

Overview

Status flow

What each status means for your integration

Healthy statuses — no action needed

Credential errors — user action required

Provider errors — automatic retry

System statuses

Deactivating and activating a connection

Handling status changes in your integration

Subscribe to webhooks

Poll for status

Recommended integration pattern

Account lifecycle

Account statuses

Account tracking

Check frequency

Connection API endpoints

Related pages