Connection statuses
Thestatus 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 | A multi-factor authentication challenge needs to be completed. |
| 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. |
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.
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:Related pages
- Connection lifecycle — state diagram, developer actions, and integration patterns for each status
- Webhooks — receive
connection.updated.v2events when statuses change - Troubleshooting — platform guide for resolving connection issues