Authorization Notes

You will see these Authorization notes in the Authorization['notes'] list.

Since authorizations can be fairly complex, with different steps happening a different times, we have several states we like to keep track of to make the user experience better. For example, when a customer authorizes access, we need to validate the access credentials work, followed by collecting the meter information. We don't want the customer to wait around for the meter collection to finish (which can sometimes take a while), so we make a note of when we validated the access credentials, which signals to the customer that all their steps are complete and they can go about their day.

Attribute Format Description Example
type Note Type The type of note. See list below for list of types. "access_valid"
msg String A human readable description of the note. It may be tweaked often, so don't rely on it always staying the same for a given type. "Succesfully registered with account number."
ts ISO8601 The timestamp of note. "2016-01-01T12:30:24.653422+00:00"
Extra attributes based on type (see below).
// Example access_valid note
{
    "type": "access_valid",
    "msg": "Succesfully registered with account number.",
    "ts": "2019-01-01T12:32:42.347321+00:00"
}
// Example retrying note
{
    "type": "retrying",
    "msg": "Data collection encountered errors, retrying in 2 hours.",
    "ts": "2019-01-01T12:35:42.347321+00:00",
    "eta ": "2019-01-01T14:35:42.347321+00:00"
}
Type Description Additional Attributes
access_valid Access credentials (login or account info) was successfully validated. No further authorization steps needed by the customer.
access_invalid Access credentials (login or account info) has an error. The customer needs to update the authorization to fix the fields that are invalid.
access_locked Access to the customer's account has been locked. This usually happens when the customer tries invalid login credentials too many times.
access_unsupported We found we do not support the full access method for the user. This usually comes up when we encounter a multi-factor process that we do not yet support. For supported multi-factor methods, you'll see an access_code_needed or interaction_needed note.
access_code_needed We ran into a multi-factor access process outside of the normal authorization process, so we need the utility customer to re-authorize access again. This typically happens if you're refreshing or monitoring some meters, and the user's session we had been given access to during authorization expired or became stale. To fix this, all you need to do is send an authorization update request to the utility customer and we'll get a new session.
access_method For utilities that have multiple ways to access data, this will describe what type of access this authorization uses in the access_method field
  • access_method - String - A utility-specific description of the method used to access this authorization's data
interaction_needed

We need you or the customer to provide some additional information for the authorization to proceed. This usually happens when we need to ask for a multi-factor access code, to solve a captcha, or to answer a question about the authorization (e.g. "Is this login for the commercial portal?"). Visit the provided url to perform this interaction.

NOTE: This note is usually for an "in-the-moment" interaction, and you'll only see it while the url is still valid. We try to include an estimated expires time, but if the url expires before then (e.g. we saw things timeout on the utility side), this note may disappear early. Also, the opposite can be true, where we are able to extend the validity period past the estimated expiration (if you're polling you'll see the expires time for this note switch to a date further in the future).
  • url - URL - A link to the temporary information request.
  • expires - ISO8601 or null - Estimated expiration time, if any.
incomplete_registration The account has been created by the utility but there are some more steps the account holder must complete before we can access data. For example, many utilities require users to accept the terms of service the first time they log in.
meters_full We found all the meters associated with this authorization.
meters_errored We weren't able to collect the meter list because the utility returned errors for all meters.
meters_empty The meter list collection completed successfully, but no meters were found.
meters_partial We found some meters, but the full list returned errors so some meters were skipped.
meters_closed The utility reported that this account and its services have been closed.
utility_down The utility appears to be down for maintenance. Authorization will be attempted to be validated later.
account_down The utility reported a problem with this account that prevented us from collecting some or all of the data. This can be temporary but if it occurs repeatedly then the account holder may have to login and manually fix the problem.
internal_error Something unexpected went wrong when trying to collect data, the issue has been logged, and we are working on a fix.
retrying We encountered an error, and will be automatically retrying in a moment.
  • eta - ISO8601 - When the retry is scheduled.
waiting The task is waiting for other jobs to complete (usually to prevent getting locked out), and will start in a moment.
  • eta - ISO8601 - When the task will check again to see if it should run.
wait_to_login Access to the customer's account has been temporarily limited or blocked by the utility. The utility may restore access at any time.
pending_manual UtilityAPI has to manually collect the meter list from this utility for you. We constantly monitor for such cases, and no further action is needed on your part.
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.