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. Contact support for a status update if needed.

Credential errors — user action required

These statuses mean data collection is paused 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. Generate a magic link or update credentials through the connection edit flow.
MFA Token Expired	`MFA_TOKEN_EXPIRED`	The utility portal requires a multi-factor authentication challenge (SMS code, authenticator app, etc.).	User must complete the MFA challenge. This requires an interactive session — generate a magic link so the user can complete it directly.
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 magic link 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. Generate a magic link for them to complete the flow.

Magic links are the recommended way to handle credential errors. They let the end user update credentials directly in a secure Nectar-hosted UI without sharing passwords with your application. See Magic link integration.

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. Contact support 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, contact support 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. Contact support to reactivate.

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.
`connection.updated.v2`	A connection’s details or status change. Includes `protectedChanges` and `old` fields so you can see what changed.
`connection.validated.v2`	A connection has been validated by Nectar after initial setup.

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"
  },
  "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.

Generate a magic link

Use the magic link endpoint to generate a secure URL the user can visit to update their credentials. See Magic link integration for details.

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) pause 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 and site assignments.
`/connection/{connectionId}/details`	GET	Get full connection details including accounts.
`/connection/{connectionId}/details`	PATCH	Update connection settings (start date, occupancy multiplier).
`/connection/{connectionId}/status`	PATCH	Confirm or reject discovered accounts.
`/connection/company/{companyId}/link`	GET, POST	Generate a magic link for creating a new connection.
`/connection/{connectionId}`	GET	Generate a magic link for editing an existing connection.

Connection statuses

Quick reference of all status values

Magic link integration

Let users update credentials in a secure hosted UI

Webhooks

Subscribe to connection status change events

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

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

Magic link integration

Webhooks

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

​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

Magic link integration

Webhooks

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

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