1. Documentation
2. Formats

Formats

All of our API endpoints are formatted as JSON. Besides the endpoint object formats, we are documenting below the other formats inside these objects you will see.

Encoding

All API responses are encoded in UTF-8 .

Timestamp

All timestamps in this API are formatted in according to ISO 8601 : YYYY-MM-DDTHH:MM:SS.000000+00:00

For most timestamps on our API (created, revoked, etc.), we use UTC (i.e. +00:00) as the default timezone. However, for timestamps and dates we parse out from utility bills and intervals, we default to the timezone of the utility. So when you see interval data from a utility, it will have the local timezone of the utility in the timestamp so that you can convert it to UTC easily.

When you submit a date/time in a POST request, you need to format it in ISO 8601 format. The separator between the date and time is "T" and the time precision can be down to the microsecond. Here are some examples of valid and invalid ISO8601 formats:

Valid

• 2014-01-01T01:01:01+00:00
• 2014-01-01T01:01:01Z
• 2014-01-01T01:01:01.123456+00:00
• 2014-01-01T01:01:01.123456Z
• 2014-01-01T01:01:01.123456-08:00

Invalid

• 2014-01-01 01:01:01+00:00 (missing "T" separator)
• 2014-01-01T01:01:01PM (hours are 0-23, not a.m./p.m.)

Error

When you receive HTTP client error response codes ( 4xx ), it indicates that your request contained something we didn't like. We try to tell you exactly what was wrong so that you can fix it and everyone's happy. The error response format contains the following three parameters, but there may also be additional attributes for informational purposes:

• error - The specific error type.
• error_description - A human readable description of the error.
• url - If available, a URL to the docs for more info. Can also be null.

// Example error response
{
    "error": "invalid_param",
    "error_description": "Scope must be a valid json object",
    "url": "https://utilityapi.com/docs/authorization-forms/scopes"
}

Success

This is a success response object on API endpoints that don't return API objects. For example, when you trigger a historical collection, we will simply return this success object with "success": true. There may also be additional attributes for informational purposes.

// Example success objects
{
    "success": true
    ...
}

UID String

This is a unique identifier for an API object. This is set by UtilityAPI, not the utility, and is what you use to access specific objects on UtilityAPI. UID strings may look like integers, but don't be fooled! At some point we will likely change them to start including non-digits, so you should always treat them as strings.

// Example UID String
{
    "authorization_uid": "1234",
    ...
}

URL

This is a URL to another endpoint on the API, authorization form, or documentation.

// Example URL
{
    "base_url": "https://utilityapi.com/portal/example_solar",
    ...
}

String

This is a basic string of text. No really, that's it. Our API uses UTF-8 encoding on all responses, so strings are also encoded in UTF-8. For URL query parameters, be sure to percent encode strings.

// Example string in json
{
    "company_name": "Дcmé Solar, Inc.",
    ...
}

# Example percent encoded string in URL query parameter
https://utilityapi.com/api/v2/authorizations?utility=SDG%26E

Base64 Encoded String

This is a binary file that has been Base64 encoded .

// Example encoded png image
{
    "company_logo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==",
    ...
}

Integer

This is a basic integer. They are mainly used in utility data blocks.

// Example integer
{
    "level": 2,
    ...
}

Float

This is a basic float. They are mainly used in utility data blocks.

// Example float
{
    "bill_total_volume": 220.01234,
    "bill_total_unit": "kwh",
    ...
}

Boolean

This is a basic boolean. In json objects they are true and false. In URL query parameters they are the strings "true" and "false".

// Example booleans in json
{
    "is_test": true,
    "is_archived": false,
    ...
}

# Example boolean in URL query parameter
https://utilityapi.com/api/v2/authorizations?is_test=true&is_archived=false

Null

This is a basic null value. In json objects they are null.

// Example null
{
    "next": null,
    ...
}

---

Unit

Whenever we provide a numeric value in a generic field on the API it's usually accompanied by a string indicating the units for that number. We currently support all of the following units and will add to this list as we come across new types of data.

---

Source

We collect data from many different places and we may use data from multiple sources to compile a full data set. In order to be transparent about where this information comes from, we indicate sources on various types of data and provide links to the raw source files if possible. That way, you can verify that the information parsed from the raw files matches what's in the data provided by the API.

// Source example
{
    "type": "pdf",
    "raw_url": "https://utilityapi.com/api/v2/files/abc123abc123abc123"
}

// Source example with additional attributes
{
    "type": "pdf_other",
    "raw_url": "https://utilityapi.com/api/v2/files/pdf_file_2030_01_04.pdf",
    "format": "nem_details"
}

SourceType

---

SupplierType