Authorizations

This is the object representing a customer (i.e. utility account holder) authorization to share data with a user. This object contains the customer authorization and access information for the utility account.


Attribute Format Description Example
uid UID String Unique identifier of the Authorization. These uids may appear as integers, but they are not guaranteed to stay that way, so you should treat them as strings. "12345b"
created ISO8601 When the Authorization was submitted. "2016-01-01T12:30:24.653422+00:00"
customer_email String Customer email used on the authorization form. "pfry@planetexpress.com"
customer_signature Customer Signature or null Customer signature used on the latest authorization form. If an Authorization is declined, this will be null. {"type": "text", "full_name": "Philip J. Fry", ...}
declined ISO8601 or null Timestamp when the Authorization was declined. If not declined, this attribute will be null. "2016-01-05T12:35:24.653422+00:00"
is_declined Boolean Whether the Authorization was declined. If this is true, see declined for when the decline happened. false
expires ISO8601 or Preset String

When the Authorization will expire. This can either be a timestamp or a preset string.

is_expired Boolean Whether the Authorization has expired. This will be true when expires is a date in the past. This will be false when expires is either a Preset String or a date in the future. false
exports Exports

An object containing urls to various non-API downloads for meter, billing, and interval data for this Authorization.

{"bills_combined_csv": "https://utilityapi.com/api/v2/files/1111111111", ...}
exports_list Exports List

A List object containing the names and urls to various non-API downloads for meter, billing, and interval data for this Authorization.

[{'name': 'Bills: all bills [csv]','link': "https://utilityapi.com/api/v2/files/1238333328334323.csv"}]
form_uid UID String or null The Form used for the authorization form, if any. "12345d345"
template_uid UID String or null The Template used for the authorization form, if any. "1111-d345"
is_archived Boolean Whether the Authorization is archived. Default is false. false
is_test Boolean Whether the Authorization was submitted via /test-submit, was a DEMO utility, or was a test-submit username submitted through an auth form. false
scope Scope

Any authorization scope parameters submitted. If no scope is set, the default authorization scope was used and this is {}.

{"expires": "2017-01-01T00:00:00+00:00"}
notes List(Authorization Note) List of notes about the Authorization. Will be an empty list if no notes. [{"type": "access_valid", ...}]
revoked ISO8601 or null Timestamp when the Authorization was revoked. If not revoked, this attribute will be null. "2016-01-05T12:35:24.653422+00:00"
is_revoked Boolean Whether the Authorization has been revoked. If this is true, see revoked for when the revocation happened). false
status Status Current status of the Authorization. "pending"
status_message String Latest verbose message accompanying the latest status. "Found meters! Parsing..."
status_ts ISO8601 Latest update of the current status. "2016-01-01T12:35:24.653422+00:00"
user_email String Email of the owner the authorization form that was submitted. "sales@acmesolar.com"
user_uid UID String Unique identifier for the owner the authorization form that was submitted. "23456b"
utility UtilityID Utility selected for the authorization form. "PG&E"
Type Description
pending We are currently running tasks related to this Authorization. This is usually tasks related to updating the Meters list for this Authorization. We also update the Notes list of the Authorization live while our tasks are running, so you don't have to wait for the entire task to complete before you start activating meters, showing the user results, etc.
updated We are done doing all the tasks we need to do for this Authorization. See the Notes list for more verbose details about the results of any tasks we performed.
errored We ran into an issue when performing tasks related to this Authorization. Like updated, this status indicates we're not currently performing any tasks related to the Authorization, but this also indicates that the latest task failed to complete as expected. This generally happens when a utility changes interfaces or returns a new error that isn't currently handled by our system. We monitor these errors and our engineers work to resolve them as soon as they appear.

// Successful Authorization that have collected meters
{
    "uid": "12345",
    "created": "2016-01-01T12:30:24.653422+00:00",
    "customer_signature": {
        "type": "text",
        "ts": "2016-01-01T12:30:24.653422+00:00",
        "full_name": "Philip J. Fry"
    },
    "customer_email": "pfry@planetexpress.com",
    "declined": null,
    "is_declined": false,
    "expires": "2019-01-01T12:30:24.653422+00:00",
    "is_expired": false,
    "exports": {
        "bills_combined_csv": "https://utilityapi.com/api/v2/files/meters_bills_csv?meters=321,567",
        "meters_csv": "https://utilityapi.com/api/v2/files/meters_csv?accounts=12345"
    },
    "template_uid": "397hcu30",
    "form_uid": "87251",
    "is_archived": false,
    "is_test": false,
    "scope": {},
    "notes" : [
        {
            "type": "access_valid",
            "msg": "Succesfully registered with account number.",
            "ts": "2019-01-01T12:32:42.347321+00:00"
        },
        {
            "type": "meters_full",
            "msg": "Found all meters available.",
            "ts": "2019-01-01T12:35:42.347321+00:00"
        }
    ],
    "revoked": null,
    "is_revoked": false,
    "status": "updated",
    "status_message": "Meters found!",
    "status_ts": "2016-01-01T12:35:41.823324+00:00",
    "user_uid": "1337",
    "user_email": "sales@acmesolar.com",
    "utility": "PG&E",
}
// Bad login credentials
{
    "uid": "12345",
    "created": "2016-01-01T12:30:24.653422+00:00",
    "customer_signature": {
        "type": "text",
        "ts": "2016-01-01T12:30:24.653422+00:00",
        "full_name": "Philip J. Fry"
    },
    "customer_email": "pfry@planetexpress.com",
    "declined": null,
    "is_declined": false,
    "expires": "2019-01-01T12:30:24.653422+00:00",
    "is_expired": false,
    "exports": {},
    "template_uid": "397hcu30",
    "form_uid": "87251",
    "is_archived": false,
    "is_test": false,
    "scope": {},
    "notes" : [
        {
            "type": "access_invalid",
            "msg": "Username and/or password appears to be incorrect.",
            "ts": "2016-01-01T12:31:42.347321+00:00"
        }
    ],
    "revoked": null,
    "is_revoked": false,
    "status": "errored",
    "status_message": "Invalid login credentials.",
    "status_ts": "2016-01-01T12:31:42.347321+00:00",
    "user_email": "sales@acmesolar.com",
    "user_uid": "1337",
    "utility": "PG&E",
}
// Declined and archived Authorization
{
    "uid": "12346",
    "created": "2016-01-01T12:30:24.653422+00:00",
    "customer_signature": {
        "type": "text",
        "ts": "2016-01-01T12:30:24.653422+00:00",
        "full_name": "Philip J. Fry"
    },
    "customer_email": "pfry@planetexpress.com",
    "declined": "2016-01-01T12:30:24.653422+00:00",
    "is_declined": true,
    "expires": "2016-01-01T12:30:24.653422+00:00",
    "is_expired": true,
    "exports": {},
    "template_uid": "397hcu30",
    "form_uid": "87251",
    "is_archived": true,
    "is_test": false,
    "scope": {},
    "notes" : [],
    "revoked": null,
    "is_revoked": false,
    "status": "updated",
    "status_message": "Authorization declined",
    "status_ts": "2016-01-01T12:30:24.653422+00:00",
    "user_email": "sales@acmesolar.com",
    "user_uid": "1337",
    "utility": "",
}