Stream - Continuous Feed (Beta)
Link Once, Stay Connected Forever
Overview
Stream maintains active connections to utility accounts, enabling periodic data retrieval based on a configurable refresh schedule.
First Step: Establish a Rewind Connection
By default, your first connection with a new Login using Rewind will activate Stream unless explicitly disabled. While this won’t set a specific schedule, it ensures that you can activate a Stream schedule at any time after that first connection.
How Stream Works
1. Activate a Available options include:
• Daily refresh: Automatically fetch data every 24 hours.
• Weekly refresh: Choose a specific day of the week for the refresh (e.g., every Monday).
• Monthly refresh:
• Specify a particular day or multiple days of the month (e.g., 5th, 15th).
• If the specified day doesn’t exist in a given month, Deck automatically refreshes on the last valid day.
• Quarterly refresh:
• Specify a day in each quarter for the refresh (e.g., 1st day of each quarter or any custom day like 15th).
• If the specified day doesn’t exist in the quarter (e.g., 30th for February in Q1), Deck automatically refreshes on the last valid day of that quarter.
• Next bill date refresh: Refresh automatically on the billing date extracted from the latest bill.
• Manual reconnections: Trigger reconnections on demand via API for specific use cases. Schedule
Use POST /accounts/{account_id}/stream to activate a Stream and configure the refresh schedule.
Available options include:
• Daily refresh: Automatically fetch data every 24 hours.
• Weekly refresh: Choose a specific day of the week for the refresh (e.g., every Monday).
• Monthly refresh:
- Specify a particular day or multiple days of the month (e.g., 5th, 15th).
- If the specified day doesn’t exist in a given month, Deck automatically refreshes on the last valid day.
• Quarterly refresh:
- Specify a day in each quarter for the refresh (e.g., 1st day of each quarter or any custom day like 15th).
- If the specified day doesn’t exist in the quarter (e.g., 30th for February in Q1), Deck automatically refreshes on the last valid day of that quarter.
• Next bill date refresh: Refresh automatically on the billing date extracted from the latest bill.
• Manual reconnections: Trigger reconnections on demand via API for specific use cases.
2. Schedule Management
Use the flexible API structure to:
• Set and update recurring schedules.
• Trigger punctual refreshes based on user actions (e.g., when a user logs into your application).
3. Webhook Notifications
Deck provides webhook notifications when new data becomes available, ensuring your system stays updated in real-time.
4. Check Stream Status
Use GET /accounts/{account_id}/stream/status to check the active Stream schedule. The response will include:
• Whether the account is currently active on Stream.
• The schedule type (e.g., daily, weekly, specific monthly dates, etc.).
Difference between Stream and Rewind
While you can technically refresh data using a Rewind call, the Rewind response retrieves a predefined historical period (e.g., one month, one year, or two years). This means that if you’ve already fetched data for an account, a subsequent Rewind call will include overlapping data, leading to duplicates.
In contrast, Stream is designed to deliver only new data that hasn’t been previously fetched for a given account, ensuring efficiency and avoiding redundancy.
Step by step with samples
Step 1: Activate Stream with Daily Frequency
Use the Stream endpoint to set the refresh schedule to daily for interval data.
Sample Stream Activation Request
POST /accounts/{account_id}/stream
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
"schedule": "daily",
"data_type": "interval"
}
Stream Activation Response
{
"account_id": "123456789",
"schedule": "daily",
"data_type": "interval",
"status": "active"
}
Adjusting a Stream Schedule
POST /accounts/{account_id}/stream
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
"schedule": "weekly",
"data_type": "interval",
"schedule_details": {
"day_of_week": "Monday"
}
}
Explanation:
• schedule: Indicates the frequency of the refresh. Options are daily, weekly, monthly, or manual.
• data_type: Specifies the type of data to refresh (e.g., interval).
• schedule_details: Provides additional parameters based on the chosen schedule.
• For weekly, specify day_of_week (e.g., Monday).
• For monthly, specify day_of_month or multiple days (e.g., [5, 15]).
• For daily, no additional details are required.
Response Example
{
"account_id": "123456789",
"schedule": "weekly",
"data_type": "interval",
"status": "updated",
"schedule_details": {
"day_of_week": "Monday"
}
}
Sample Webhook Payload for Daily Interval Data
{
"source_name": "Example Utility Co",
"source_country": "US",
"username": "[email protected]",
"accounts": [
{
"account_number": "123456789",
"interval_resolution_minutes": 15,
"intervals": [
{
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-01-01T00:15:00Z",
"usage": 1.25,
"unit": "kWh"
},
{
"start_time": "2023-01-01T00:15:00Z",
"end_time": "2023-01-01T00:30:00Z",
"usage": 0.80,
"unit": "kWh"
},
{
"start_time": "2023-01-01T00:30:00Z",
"end_time": "2023-01-01T00:45:00Z",
"usage": 0.90,
"unit": "kWh"
},
{
"start_time": "2023-01-01T00:45:00Z",
"end_time": "2023-01-01T01:00:00Z",
"usage": 1.10,
"unit": "kWh"
},
{
"start_time": "2023-01-01T01:00:00Z",
"end_time": "2023-01-01T01:15:00Z",
"usage": 1.35,
"unit": "kWh"
},
{
"start_time": "2023-01-01T01:15:00Z",
"end_time": "2023-01-01T01:30:00Z",
"usage": 0.75,
"unit": "kWh"
},
{
"start_time": "2023-01-01T01:30:00Z",
"end_time": "2023-01-01T01:45:00Z",
"usage": 1.00,
"unit": "kWh"
},
{
"start_time": "2023-01-01T01:45:00Z",
"end_time": "2023-01-01T02:00:00Z",
"usage": 1.40,
"unit": "kWh"
},
{
"start_time": "2023-01-01T02:00:00Z",
"end_time": "2023-01-01T02:15:00Z",
"usage": 0.95,
"unit": "kWh"
},
{
"start_time": "2023-01-01T02:15:00Z",
"end_time": "2023-01-01T02:30:00Z",
"usage": 0.85,
"unit": "kWh"
}
// Additional intervals for the day...
]
}
]
}
Sample Response for No New Data from a Scheduled Stream Connection
{
"account_id": "123456789",
"status": "no_new_data",
"last_refresh": "2023-01-01T00:00:00Z"
}
Sample response for when a Stream reconnection fails due to invalid credentials:
{
"account_id": "123456789",
"status": "reconnection_failed",
"code": 40101,
"message": "Reconnection failed due to invalid credentials. User credentials may have changed.",
"last_attempt": "2024-12-15T12:00:00Z",
"next_scheduled_attempt": "2024-12-16T12:00:00Z",
"resolution": {
"action_required": "user_update",
"details": "Please prompt the user to update their credentials via the client application."
}
}
Sample response for when a Stream reconnection fails due to an unsuccessful Multi-Factor Authentication (MFA) attempt:
{
"account_id": "123456789",
"status": "reconnection_failed",
"code": 40102,
"message": "Reconnection failed due to unsuccessful Multi-Factor Authentication (MFA).",
"last_attempt": "2024-12-15T12:00:00Z",
"mfa_status": {
"required": true,
"last_prompt": "2024-12-15T11:55:00Z",
"failure_reason": "No code provided."
},
"next_scheduled_attempt": "2024-12-16T12:00:00Z",
"resolution": {
"action_required": "user_mfa",
"details": "Please prompt the user to complete MFA verification via the client application."
}
}
Check on the Stream status of a Connection
To monitor the status of an active Stream connection, Deck provides the GET /accounts/{account_id}/stream/status endpoint. This endpoint allows you to check the current schedule, view details about the most recent reconnection attempt, and determine whether fresh data was retrieved.
How It Works
Use GET /accounts/{account_id}/stream/status to retrieve the status of a Stream connection for a specific account.
2. Information Returned:
The response includes:
• Schedule: The current refresh schedule for the Stream connection (e.g., daily, weekly, monthly).
• Last Reconnection Attempt: Timestamp and result of the last reconnection attempt.
• Fresh Data Retrieved: Indicates whether new data was retrieved during the last attempt.
GET /accounts/{account_id}/stream/status
Authorization: Bearer {API_TOKEN}
Sample Response: Successful Reconnection with Fresh Data
{
"account_id": "123456789",
"status": "active",
"schedule": {
"type": "daily",
"next_refresh": "2024-12-16T00:00:00Z"
},
"last_attempt": {
"timestamp": "2024-12-15T00:00:00Z",
"result": "success",
"fresh_data_retrieved": true
}
}
Account-level Control for Stream Scheduling
Overview:
Deck now allows users to manage their Stream schedules at the account level. This includes activating or deactivating specific accounts from a Stream schedule, providing granular control over which accounts receive updates.
API Endpoint: POST /accounts/stream
This endpoint has been updated to support account-specific activation or deactivation for Stream schedules.
Request Example for Activating Specific Accounts:
POST /accounts/stream
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
"schedule": "daily",
"data_type": "interval",
"accounts": [
"123456789",
"987654321"
]
}
Explanation:
• schedule: Indicates the refresh frequency (e.g., daily, weekly, etc.).
• data_type: Specifies the data type (e.g., interval or billing data).
• accounts: A list of account IDs to activate for the Stream schedule.
Request Example for Deactivating Specific Accounts:
POST /accounts/stream
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
"action": "deactivate",
"accounts": [
"123456789"
]
}
Explanation:
• action: Specify "deactivate" to remove specific accounts from the Stream schedule.
• accounts: A list of account IDs to deactivate.
Response Example for Account-Level Activation:
{
"status": "success",
"message": "Stream schedule updated successfully.",
"active_accounts": [
"123456789",
"987654321"
],
"inactive_accounts": []
}
Response Example for Account-Level Deactivation:
{
"status": "success",
"message": "Accounts deactivated from Stream schedule.",
"active_accounts": [],
"inactive_accounts": [
"123456789"
]
}
List of Valid Vales for Scheduling
To ensure smooth integration and minimize errors, here are the accepted formats and values for scheduling parameters:
Schedule Values (Frequency)
• "daily": Refresh data every 24 hours.
• "weekly": Refresh data once a week on a specific day.
• "monthly": Refresh data on specific dates each month.
• "manual": No automatic refresh; only manual triggers.
Schedule_details Parameters
For daily:
• No additional details are required.
For weekly:
• Key: day_of_week
• Accepted Values: Full day names (case-insensitive):
• "Monday"
• "Tuesday"
• "Wednesday"
• "Thursday"
• "Friday"
• "Saturday"
• "Sunday"
Examples:
{
"schedule": "weekly",
"schedule_details": {
"day_of_week": "Monday"
}
}
For monthly:
• Key: days_of_month
• Accepted Values: Integer values from 1 to 31 (inclusive). Multiple days can be provided as an array.
• If the specified day does not exist in a given month (e.g., 31 in February), the refresh will occur on the last valid day of the month.
Examples:
{
"schedule": "monthly",
"schedule_details": {
"days_of_month": [1, 15, 30]
}
}
For manual:
• No additional details are required.
Examples:
{
"schedule": "manual"
}
Updated 3 days ago