> ## 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.
# Connection lifecycle
> How connections move through statuses, what each status means for your integration, and what actions to take.
**For platform users**: See the [Connections page](/platform/data-input/connections) for
dashboard-level guidance, or the [Troubleshooting guide](/platform/data-input/troubleshooting) for
step-by-step resolution instructions.
## Overview
A [connection](/developer-guide/connection-statuses) 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:
```mermaid theme={null}
stateDiagram-v2
[*] --> PENDING: Connection created
PENDING --> CONNECTED: Authentication successful
PENDING --> PASSWORD_INCORRECT: Bad credentials
PENDING --> MFA_TOKEN_EXPIRED: MFA required
PENDING --> WEBSITE_DOWN: Provider unavailable
PENDING --> OTHER_ERROR: Unexpected failure
CONNECTED --> CONNECTED: Weekly check passes
CONNECTED --> PASSWORD_INCORRECT: Password changed
CONNECTED --> MFA_TOKEN_EXPIRED: MFA session expired
CONNECTED --> NEW_PASSWORD_NEEDED: Provider requires reset
CONNECTED --> WEBSITE_DOWN: Provider unavailable
CONNECTED --> NO_ACCOUNTS_FOUND: Accounts removed
CONNECTED --> UNDER_INVESTIGATION: Nectar reviewing
CONNECTED --> OTHER_ERROR: Unexpected failure
PASSWORD_INCORRECT --> CONNECTED: Credentials updated
MFA_TOKEN_EXPIRED --> CONNECTED: MFA completed
NEW_PASSWORD_NEEDED --> CONNECTED: Password reset
ADDITIONAL_CREDENTIALS_NEEDED --> CONNECTED: Info provided
WEBSITE_DOWN --> CONNECTED: Provider back online
NO_ACCOUNTS_FOUND --> CONNECTED: Accounts found
UNDER_INVESTIGATION --> CONNECTED: Issue resolved
OTHER_ERROR --> CONNECTED: Issue resolved
OTHER_ERROR --> UNDER_INVESTIGATION: Escalated
```
## 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 [support@nectarclimate.com](mailto:support@nectarclimate.com) 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](/developer-guide/connection-invitations) 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](/developer-guide/mfa-integration#recommendation-ladder): upload documents, disable MFA on the portal, or configure one of the forwarding strategies via a reconnect [invitation](/developer-guide/connection-invitations). |
| 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](/developer-guide/connection-invitations). The legacy [magic
link](/developer-guide/magic-link-integration) 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 [support@nectarclimate.com](mailto:support@nectarclimate.com) 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 [support@nectarclimate.com](mailto:support@nectarclimate.com) 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 [support@nectarclimate.com](mailto:support@nectarclimate.com) 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.
```bash theme={null}
# 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.
```bash theme={null}
# 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
### Subscribe to webhooks
The most efficient way to track connection status changes is via [webhooks](/developer-guide/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:
```json theme={null}
{
"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:
```bash theme={null}
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:
```bash theme={null}
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
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`.
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.
Use the connection-invitation endpoint to generate a secure URL the user can visit to update their
credentials. See [Connection invitations](/developer-guide/connection-invitations) for details.
For `MFA_TOKEN_EXPIRED`, also point the customer to [document upload](/developer-guide/document-upload) as the recommended first option — uploaded bills produce the same downstream data and avoid MFA configuration entirely. See [MFA integration](/developer-guide/mfa-integration).
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:
```bash theme={null}
# 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. |
## Related pages
Quick reference of all status values
Let users create or update connections in a secure hosted UI
Decision tree and shareable one-pager for MFA-protected accounts