Connection and account statuses

For platform users: See the Connections page to understand how to manage connections in the dashboard, or the Troubleshooting guide for resolution steps.

Connection statuses

The status field on a connection object uses the following values. API responses return the exact string values shown in the API value column.

Standard statuses

Display name	API value	Description
Pending	`PENDING`	The connection is new but has not been onboarded yet.
Under Investigation	`UNDER_INVESTIGATION`	Something has gone wrong and the Nectar team is investigating.
Connected	`CONNECTED`	Nectar can log in and access the connection.

Error statuses — website issues

Display name	API value	Description
Website Down	`WEBSITE_DOWN`	The connection’s website is inaccessible.
URL Inaccessible	`URL_INACCESSIBLE`	The provider URL cannot be reached.
No Accounts Found	`NO_ACCOUNTS_FOUND`	Nectar can log in to the website, but no accounts were available.
Other Error	`OTHER_ERROR`	An issue not covered by an existing status.

Error statuses — needs customer intervention

Display name	API value	Description
MFA Token Expired	`MFA_TOKEN_EXPIRED`	MFA is required on login but codes aren’t reaching Nectar or the session expired. Walk the customer through the MFA recommendation ladder — upload documents or disable MFA before any forwarding-based recovery.
Password Incorrect	`PASSWORD_INCORRECT`	The connection password is incorrect.
New Password Needed	`NEW_PASSWORD_NEEDED`	The utility website requires a new password to be created.
Additional Credentials Needed	`ADDITIONAL_CREDENTIALS_NEEDED`	The website requires additional information to proceed.

System statuses

Display name	API value	Description
Company Inactive	`COMPANY_INACTIVE`	The parent company has been deactivated.
Deactivated	`DEACTIVATED`	Data collection has been deactivated via `PATCH /connection/{id}/details` with `isActive: false`. Set back to `true` to activate collection.

Account statuses

Account statuses track the lifecycle of individual utility accounts within a connection. API responses return the exact string values shown in the API value column.

Standard statuses

Display name	API value	Description
Detected	`DETECTED`	The account has been discovered but not yet onboarded.
Onboarded	`ONBOARDED`	The account has been confirmed and is actively tracked.
Pull Completed	`PULL_COMPLETED`	Data has been successfully pulled and processed.

Error statuses

Display name	API value	Description
No Documents Found	`NO_DOCUMENTS_FOUND`	No documents were found for this account.
PDF Download Failed	`PDF_DOWNLOAD_FAILED`	Documents were available, but there was an issue downloading them.
Account Not Found	`ACCOUNT_NOT_FOUND`	Nectar was unable to locate this account on the connection’s website.
Workflow Not Accessible	`WORKFLOW_NOT_ACCESSIBLE`	There was a larger issue with the connection (e.g., password incorrect).
Other Error	`OTHER_ERROR`	An issue not covered by an existing status.

Terminal statuses

Display name	API value	Description
Old Account	`OLD_ACCOUNT`	This account has been closed and will not have new data.
Duplicate	`DUPLICATE`	This account is a duplicate of another account.
Customer Not Tracked	`CUSTOMER_NOT_TRACKED`	The client has elected not to track this account.
Company Inactive	`COMPANY_INACTIVE`	The parent company has been deactivated.

Check frequency

Connections are checked weekly, with two exceptions:

Accounts with a terminal status — Old Account, Duplicate, and Customer Not Tracked are not re-checked.
Connections needing customer intervention — Password Incorrect, New Password Needed, Additional Credentials Needed, and MFA Token Expired require action before the next check runs.

For all other scenarios, expect an update within 7 days of the last status update.

Status fields

Both connection and account objects include the following status-related fields:

Field	Type	Description
`status`	String	The current status value (one of the API values listed above).
`statusLastUpdateTime`	Datetime	When this status was last recorded.
`statusFirstSeenTime`	Datetime	When this status was first set.
`statusErrorDetail`	String	Additional details when the status is an error.

Filtering by status

You can filter connections by status when listing them:

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

Connection lifecycle — state diagram, developer actions, and integration patterns for each status
Webhooks — receive connection.updated.v2 events when statuses change
Troubleshooting — platform guide for resolving connection issues

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

Connection statuses

Standard statuses

Error statuses — website issues

Error statuses — needs customer intervention

System statuses

Account statuses

Standard statuses

Error statuses

Terminal statuses

Check frequency

Status fields

Filtering by status

​Connection statuses

​Standard statuses

​Error statuses — website issues

​Error statuses — needs customer intervention

​System statuses

​Account statuses

​Standard statuses

​Error statuses

​Terminal statuses

​Check frequency

​Status fields

​Filtering by status

​Related pages

Connection statuses

Standard statuses

Error statuses — website issues

Error statuses — needs customer intervention

System statuses

Account statuses

Standard statuses

Error statuses

Terminal statuses

Check frequency

Status fields

Filtering by status

Related pages