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).

Examples

// 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"
}

Authorization Note Types

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.