Ongoing Monitoring [BETA]

This feature is still under development. Stopping and starting new Ongoing Monitoring subscriptions using this endpoint may result in unexpected charges.

Ongoing Monitoring is available only to users who are on a prepaid package .

Ongoing monitoring is a method to schedule periodic Historical Collections charged monthly. This endpoint lets you bulk start and stop ongoing monitoring for Meters. Ongoing monitoring will automatically update the Meter's bills and intervals at the specified frequency. If the update interval is set to off, the specified Meters will stop Ongoing Monitoring.

A Meter's current Ongoing Monitoring settings can be found in its ongoing_monitoring attribute, which is an Ongoing Monitoring Object.

NOTE: If you set a Meter to be monitored, we will only collect data from the date you initiate monitoring onwards. The first collection will be scheduled one duration of the frequency from the date initiated (ie. A weekly subscription will be scheduled to first refresh a week in the future, collecting data covering that one-week period). If you wish to also collect full historical data for the meter, run a Historical Collection.

NOTE: For PCE, SVCE, NGNY, and FCU, new meters will inherit ongoing monitoring if the meters under the entire account are on the same ongoing monitoring settings or the new meter replaces a stopped meter with ongoing monitoring subscription.

HTTP Request

POST https://utilityapi.com/api/v2/meters/ongoing-monitoring

Examples

# Start Ongoing Monitoring
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"meters": ["123", "234"], "frequency": "monthly"}' \
    'https://utilityapi.com/api/v2/meters/ongoing-monitoring'

# Stop Ongoing Monitoring
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"meters": ["123", "234"], "frequency": "off"}' \
    'https://utilityapi.com/api/v2/meters/ongoing-monitoring'

POST Body

The request body must be a valid JSON object. Below are the parameters that are required.

Parameter	Format	Description	Example
`meters`	List(UID String)	A list of Meter uids for which to collect data.	`["123", "234"]`
`frequency`	FrequencyType	The frequency on which to monitor the meters.	`"monthly"`
`fixed_refresh_day`	Integer or `null`	(Optional, defaults to `null`; may only be set on meters without active monitoring subscriptions, and when `frequency == "monthly"`) Sets the day of the month on which ongoing monitoring collections will run. If the value is greater than the number of days in the current month, the collection will run on the last day of the month.	`14`

NOTE: Meters that are revoked (i.e. revoked != null) or expired (i.e. expires <= now) are silently ignored in the meters list. If all Meters in the list are revoked or expired, we will return a 400 response. You can figure out which meters have been ignored by comparing your POST body meters list and the response's meters list. We silently drop so you don't have to check the revoke or expiration status of every meter every time you want to monitor your meters.

Response

Returns a Success object with an additional meters attribute with the meters that have had their monitoring status updated. Also included is the confirmed frequency attribute. The confirmed fixed_refresh_day attribute is included for monthly subscriptions.

// Example result
{
    "success": true,
    "meters": ["123", "234"],
    "frequency": "daily",
}

// Example monthly result with fixed refresh day
{
    "success": true,
    "meters": ["345", "456"],
    "frequency": "monthly",
    "fixed_refresh_day": 11
}

HTTP Response Codes

Code	Response Format	Description
`200`	Success	Successful request.
`400`	Error	The POST body contains invalid parameters. Check the `error` in the response for the type of error: `required_param_missing` - Missing the `meters` list. `invalid_param` - Values in the `meters` list are invalid. `expired_or_revoked` - All of the Authorizations for these meters are expired, so nothing can be collected. We may add more error types in the future, so be able to handle unknown types.
`401`	Error	Invalid or missing `access_token`. See our docs on Authentication for how to properly use your `access_token`.
`402`	Error	Payment Required. Monitoring updates costs money, so you either need to have a positive balance or have a credit card on file. Go to your settings and add a credit card or pre-pay for data collections.
`404`	Error	None of the Meters exist or you don't have permissions to see them.
`429`	N/A	The request was rate limited. Check the `Retry-After` response header for how long to wait until retrying the request. Do not expect any specific response format for this error (could be html, json, or nothing).
`500`	N/A	Internal server error. Do not expect any specific response format for this error (could be html, json, or nothing). This error is logged and will be fixed by our engineers.
`503`	N/A	Site is currently down for maintenance. Do not expect any specific response format for this error (could be html, json, or nothing).
`504`	N/A	We tried to build this request but timed out. Please try again later. Do not expect any specific response format for this error (could be html, json, or nothing).

Ongoing Monitoring Object

This is the object that contains the current Ongoing Monitoring settings for a Meter, including how frequently we will collect data for the Meter. You can find this object in any Meter's ongoing_monitoring attribute.

Examples

// daily monitoring
{
    "frequency": "daily",
    "next_prepay": "2017-05-01T12:30:24.653422+00:00",
    "next_refresh": "2017-04-03T18:28:33.347382+00:00",
    "fixed_refresh_day": null
}

// monthly monitoring (with fixed refresh day)
{
    "frequency": "monthly",
    "next_prepay": "2017-05-01T18:28:33.347382+00:00",
    "next_refresh": "2017-04-11T06:59:59.347382+00:00",
    "fixed_refresh_day": 11
}

// stopped monitoring
{
    "frequency": "off",
    "next_prepay": null,
    "next_refresh": null,
    "fixed_refresh_day": null
}

Attributes

Attribute	Format	Description	Example
`frequency`	FrequencyType	The frequency on which to monitor the Meter.	`"monthly"`
`next_prepay`	ISO8601 or `null`	The timestamp of next prepay. Will be `null` if there is no next prepay (e.g. if frequency is off).	`"2020-01-01T12:30:24.653422+00:00"`
`next_refresh`	ISO8601 or `null`	The timestamp of next expected refresh (see scheduling notes). Will be `null` if there is no next refresh scheduled (e.g. if frequency is off).	`"2019-01-11T08:30:24.653422+00:00"`
`fixed_refresh_day`	Integer or `null`	The fixed day of the month a monthly subscription will refresh on, if it was set when monitoring was started (see the `fixed_refresh_day` parameter). For subscriptions whose `frequency` is not `monthly`, this will always be `null`	`11`
Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.

Frequency Types

When starting Ongoing Monitoring, you can set how often you want us to go collect any new Bills and Intervals.

NOTE: Scheduling updates is a complex task, and we optimize the timing of monitoring updates to increase chances of success. You may occasionally see the scheduled time of updates vary. This is normal. To see when data was last collected, check the Meter's status_ts attribute. To see when the next monitoring update is scheduled, check the Meter's ongoing_monitoring.next_refresh note.

Type	Description	Notes
`monthly`	Refresh data on a monthly basis.	If we have previously collected bills for these Meters, we will attempt to proactively refresh within a few days of the monthly billing cycle. We continually optimize the timing of monthly updates to ensure you get new bill data promptly. If you need a more predictable schedule, you can manually set a day of the month for refreshes to occur on; you can do this when you begin monitoring a meter using the `fixed_refresh_day` parameter.
`weekly`	Refresh data on a weekly basis.	By default we schedule the update weekly from when monitoring was started. Occasionally, if that day of the week is consistently not successful at collecting data, we may shift the day of the week or time of day of the monitoring update.
`daily`	Refresh data on a daily basis.	We usually schedule daily updates overnight to optimize chances of success. When utility access is not available (e.g. when they are down for maintenance), we may shift the time of day of the monitoring update.
`off`	Do not refresh data.	By default, Meters are not set to refresh automatically, so this is the frequency you will see by default in the Meter object. Also, if you had previously started ongoing monitoring and want to turn it off for a meter, use this types.
Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.