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.
For tips on how to most effectively use authorization objects, visit Tips.
/api/v2/authorizations
List or search your authorizations
/api/v2/authorizations/123
Get a specific authorization
/api/v2/authorizations/123
Modify an existing authorization
/api/v2/authorizations/123
Delete a authorization (test-submits only)
/api/v2/authorizations/123/revoke
Revoke an authorization (deletes all meters and data)
| 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.
NOTE: If a Form had an expires scope parameter as a
duration,
it will be converted into a timestamp when the authorization form is submitted,
so you won't ever see durations as an expires string on Authorizations.
|
Preset strings:
ISO8601:
|
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.
WARNING: These file formats are not documented and may change,
so don't rely on these files existing. They are mainly included for non-API
users of our dashboard to have some common non-API download formats. If you want
documented formats for bills and intervals, use the
/bills and
/intervals API endpoints.
DEPRECATED: Expect this to be removed in future versions of the API. Use exports_list instead.
|
{"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.
WARNING: These file formats are not documented and may change,
so don't rely on these files existing. They are mainly included for non-API
users of our dashboard to have some common non-API download formats. If you want
documented formats for bills and intervals, use the
/bills and
/intervals API endpoints.
|
[{'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 most recent authorization process, if any. | "12345d345" |
template_uid |
UID String or
null
|
The Template used for the most recent authorization process, if any. | "1111-d345" |
referrals |
List(String) | Referral codes, if any, that were created when using redirects. If no referral codes were created during the authorization process, this will be an empty list. | ["abcd1234", ...] |
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 |
notes |
List(Authorization Note) | List of notes about the Authorization. Will be an empty list if no notes. | [{"type": "access_valid", ...}] |
nickname |
String or
null
|
A nickname given to this authorization (if any) | "ACME Widgets Inc." |
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 |
scope |
Scope |
Any authorization scope parameters submitted.
If no scope is set, the default authorization scope was used and
this is
NOTE: The expires scope is included in this object
and also duplicated in the
expires
attribute for convenience. We did this so you don't have to parse
out all of the scope just to see if something is expired.
|
{"expires": "2017-01-01T00:00:00+00:00"} |
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" |
user_status |
User Status | Current user status | "active" |
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.
|
| Type | Description |
|---|---|
active |
The user is able to access data and activate meters via the dashboard and the API |
inactive |
The user is no longer able to access data or activate meters |
// 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": {}, "nickname": null, "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", "user_status": "active", "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": {}, "nickname": null, "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_status": "active", "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": {}, "nickname": null, "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", "user_status": "active", "utility": "", }