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_code_needed A multi-factor code is needed to complete the authentication. We usually handle this as part of the authorization process, so you should only usually see this if you are polling during an in-progress authorization. If url is null, it's not possible to submit the access code (e.g. the code request timed out), so you can treat this like access_invalid.
  • url - URL or null - A temporary link to embed to submit the multi-factor code.
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.
utility_down The utility appears to be down for maintenance. Authorization will be attempted to be validated later.
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.
... We may add other types in the future, so be able to handle unknown types gracefully.