Listing Authorizations

Get a list of Authorizations, reverse ordered by created date. Use parameters to filter the list.


GET https://utilityapi.com/api/v2/authorizations
# Get a list of all Authorizations
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/authorizations'
# Get some specific Authorizations 123 and 456
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/authorizations?uids=123,456'
# Get all archived Authorizations
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/authorizations?is_archived=true'
# Get the Authorizations that were created from a specific referral
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/authorizations?referrals=abcd1234'
# Get the Authorizations for a specific user
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/authorizations?users=6744'
Parameter Format Description Example
uids List(UID String) Filter by Authorization uids. Separate with commas (,). uids=123,456
forms List(UID String) Filter by Form uids. Separate with commas (,). forms=123,456
templates List(UID String) Filter by Template uids. Separate with commas (,). templates=888,999
users List(UID String) Filter by user uids (see user_uid). Separate with commas (,). users=4834,5898
referrals List(Referral Code) Filter by referral codes that have been received from redirects. Separate with commas (,). referrals=abcd1234,bcde2345
is_archived Boolean Filter by archived state. is_archived=true
is_declined Boolean Filter by declined state. is_declined=true
is_test Boolean Filter by authorizations submitted via /test-submit is_test=true
is_revoked Boolean Filter by revoked state. is_revoked=true
is_expired Boolean Filter by expired state. is_expired=true
utility List(UtilityID) Filter by utility. Separate with commas (,). utility=PG%26E,LADWP
after UID String List items after this Authorization uid. after=456
include List(Include Parameters) Add the specified child objects to this Authorization object. Separate with commas (,). include=meters
expand_meter_blocks Boolean Load complete meter block information. This will be ignored if include=meters is not set. This is only for utilities that do not expand Meter blocks by default. For utilities that expand their Meter blocks by default, this parameter is ignored. expand_meter_blocks=true
limit Integer Limit the number of results returned per page by the API to this value (Default 1000). Values greater than 1000 will be ignored. limit=100

Returns an AuthorizationListing object containing a list of Authorization objects from newest to oldest. If the number of results is over 1000, or the value set by limit, a next parameter will have the link to the next in the series of lists.

// Example result
{
    "authorizations": [
        {"uid": "12837438", "created": ...},
        {"uid": "12837438", "created": ...},
        ...
    ],
    "next": null,
}

This is the object that contains the Authorization results for the request. We don't just return a straight list of results so that we can paginate results if needed. Currently, the maximum results per request is set at 1000.

Parameter Format Description Example
authorizations List(Authorization) List of Authorization results. [{"uid": ...}, ...]
next URL or null If there are more results than the page limit, this is a link to the next set of results. "https://utilityapi.com/api/v2/authorizations?after=234"
// Example AuthorizationListing
{
    "authorizations": [...],
    "next": null,
}
Code Response Format Description
200 AuthorizationListing Successful request.
400 Error The query parameters included are malformed. Check the error in the response for the type of error:
  • invalid_param - One of the query parameters was invalid. Check the error description for more info.
We may add more error types in the future, so be able to handle unknown types.
401 Error Invalid or missing access_token. See our docs on Authentication for how to properly use your access_token.
429 N/A The request was rate limited. Check the Retry-After response header for how long to wait until retrying the request. Do not expect any specific response format for this error (could be html, json, or nothing).
500 N/A Internal server error. Do not expect any specific response format for this error (could be html, json, or nothing). This error is logged and will be fixed by our engineers.
503 N/A Site is currently down for maintenance. Do not expect any specific response format for this error (could be html, json, or nothing).
504 N/A We tried to build this request but timed out. Please try again later. Do not expect any specific response format for this error (could be html, json, or nothing).