Understanding connection statuses is critical for effectively integrating with the Deck API. While /connection/context provides a straightforward response, interpreting the returned fields accurately ensures that applications can monitor connection health, detect issues early, and manage user expectations appropriately.

This document explains each key connection-level field, how timestamps relate to session history, the meaning of various connection states and job statuses (connection status reason), and offers practical guidance for developers.

/connection/context endpoint

The /connection/context endpoint is the primary way to retrieve a connection’s current status in Deck API. It provides critical information about connectivity and data availability, helping customers integrate reliably and monitor connection health in real time.

here's a sample response from /connection/context endpoint:

{
  "connection_id": "Guid",
  "provider": {
    "id": "Guid",
  	"name": "string"
  },

  "connection_status": "Connected",
  "connection_status_timestamp": "YYYY-MM-DD:hh-mm-ss",
  "connection_status_reason": "DataFound",
  "numOfEntities": "int",
  "entities": [
    {
      "account_number": "123456789"
    },
    {
      "account_number": "987654321"
    }
  ]
}

The /connection/context response contains several important fields that describe the connection’s current state and data availability:

Understanding these fields is essential because not all statuses refer to the same scraping session.

Connection Status Overview

Each connection has a connection_status, which describes the overall phase. Within each connection status, specific connection_status_reason (connection_status_reason) provide more granular detail.

There are four possible values:

Connecting

The connection attempt is in progress. Authentication steps, user input, or additional verification may be required.

Possible Connection Status Reasons:

• New — A new session has started but not yet advanced.
• Connecting - Session is initializing and connecting to the source, this is a transient status, will transition to the next status soon without the need of any user action.
• SecurityAnswerRequired — A security question needs to be answered by the user.
• SecurityAnswerInvalid — The user must choose an MFA method (e.g., SMS or email).
• MfaMethodChoiceRequired — The user must choose an MFA method (e.g., SMS or email).
• MfaCodeRequired — The user must enter an MFA code.
• MfaCodeInvalid — The MFA code provided was invalid.
• MfaActionRequired — The user must approve an MFA action on their device.
• AccountSelectionRequired — Connection is configured to select 1 or multiple entities, the user must select to proceed.

Connected

The connection to the provider was successful. Data retrieval may or may not have been completed.

Possible Connection Status Reasons:

• ConnectedCredentials — Connection established, ready to retrieve data.
• ConnectedWaitingOnDataExtraction — Documents fetched, awaiting structured data extraction.
• DataFound — Connection established, document fetched and the extraction is done, data is available.
• NoDataFound — Connection established, but there's no statement or any data found.

Disconnected

The connection attempt failed, or the session has been closed due to an error or user action.

Possible Connection Status Reasons:

• InvalidCredentials — Incorrect username or password provided.
• SecurityAnswerTimeout — No security answer provided within the allowed time.
• MfaCodeTimeout — MFA code was not entered in time.

Error

An unexpected error occurred during the scraping session, likely requiring internal investigation.

Possible Connection Status Reasons:

• RetryLater — Temporary issue at provider; retry after some time.
• Error — Internal scraper bug requiring Deck investigation.

Conclusion

Connection statuses provide critical insight into the health of a customer's connection with their utility provider.

By accurately interpreting connection status, connection status reason and timestamp, developers can:

• Detect real issues versus expected "no new data" conditions.
• Improve application resilience.
• Enhance user experience by delivering accurate, actionable feedback.

Mastering connection statuses is key to building robust integrations with the Deck platform.