Request URLs

Our API servers reside at:

https://api.genability.com

You make requests to a URL that have the following pattern:

https://api.genability.com/rest/v1/{some resource path}

For instance, here are links to get a list of Accounts, and to get one Account using its Account ID, or use your own ID, respectively:

https://api.genability.com/rest/v1/accounts
https://api.genability.com/rest/v1/accounts/genability-account-id-here
https://api.genability.com/rest/v1/accounts/pid/your-own-unique-id-here

Each resource type has a documentation page that denotes the URL that is applicable for that resource. For example, here is the page for Account Tariffs.

Authentication

Each request needs to contain information that identifies you as the client. We have a simple authentication approach in this initial release and will be adding more as we roll out additional API’s. Details here.

Data Types

In addition to standard string and number inputs, we utilize additional input types throughout our APIs.

Array Inputs

Some fields can take multiple values as inputs. These can be specified as a String array. For example the customerClasses and tariffTypes for the Tariff method use this. There are two ways of specifying Arrays as inputs. In these examples we are requesting only "DEFAULT" and "ALTERNATIVE" tariffs:

tariffTypes=DEFAULT,ALTERNATIVE
tariffTypes=DEFAULT&tariffTypes=ALTERNATIVE

JSON Payloads

Data is returned using JSON (Javascript Object Notation). JSON is the only format we support. It’s a lightweight serialization language that is compatible with many different programming languages and technologies. JSON is syntactically correct JavaScript code, meaning you can use the Javascript eval() function to parse it. We have no plans to add in other formats (XML, for example) to our standard public RESTful APIs. However, we do handle lots of different formats and integration technologies, just not for our REST APIs.

You should also use JSON in your payload when making HTTP POST and PUT calls that require one.

We do not currently support compression of REST request or response payloads but we do for file uploads and download as part of our HTML API.

For more details of response formats, see the REST Response documentation.

HTTP Methods

The majority of calls to the API will be via HTTP GET since you will be requesting one or more resources. However, some operations require other HTTP methods:

HTTP Method POST Overload Description
GET n/a Reads resources via URL, often with query string criteria
POST n/a Create a new resource, or with parameter method, does an PUT or DELETE
PUT Y Updates an existing resource
DELETE Y Deletes an existing resource

Javascript libraries and some other technologies don’t have an easy way to submit a PUT or DELETE, so we have provided the POST overload. Include a parameter method with a value of PUT (to update) or DELETE (to remove) to get around this.

POST and PUT body

When submitting a POST or PUT request, you will typically supply a body with the request. Here is a description of some of the headers you may need to specify:

Parameter Type Description
Content-type String This is the Content-type of the body (not the content-type within the http header). For most requests you will need to set this to application/json. The only time you will want to specify a different value is when you are uploading a csv containing meter reading data. In that case, set this value to multipart/form-data (Required)
charset String Set this to charset=UTF-8 (Optional)

Pagination

To help control the quantity of response data returned in a call, we support pageStart and pageCount request parameters. The majority of calls to the API will allow for the use of pagination since you will be requesting one or more resources.

Parameter Value Description
pageStart Integer The index of the first result. If not specified, this is zero. (Optional)
pageCount Integer The number of results to return. If not specified, this will return 25 results. (Optional)

For example, you can fetch the first 100 results by setting pageStart to 0 and pageCount to 100. To fetch the second 100 results, set pageStart to 100 and pageCount to 100.

You can tell how many results matched your query by looking at the count property that is returned in every response back from the API. Note that we currently limit the count property to a maximum of 100,000. You should actually interpret 100,000 as “100,000 or more”. See the Response Payload documentation for an example of a JSON response with the count in it.

Searching and Sorting

Searching for data offers very flexible options for inputs as well as sorting. You can search for text within one or more fields. You can order your results using a prioritized list of fields, each with their own distinction of ascending or descending. Below are the options you can specify when searching, all of which are optional:

Parameter Value Description
search String The string of text to search on. This can also be a regular expression, in which case you should set the isRegex flag to true (see below). (Optional)
searchOn String Comma separated list of fields to query on. When searchOn is specified, the text provided in the search string field will be searched within these fields. The list of fields to search on depend on the entity being searched for. Read the documentation for the entity for more details on the fields that can be searched, and the default fields to be searched if searchOn is not specified. (Optional)
startsWith Boolean When true, the search will only return results that begin with the specified search string. Otherwise, any match of the search string will be returned as a result. Default is false. (Optional)
endsWith Boolean When true, the search will only return results that end with the specified search string. Otherwise, any match of the search string will be returned as a result. Default is false. (Optional)
isRegex Boolean When true, the provided search string will be regarded as a regular expression and the search will return results matching the regular expression. Default is false. (Optional)
sortOn String Comma separated list of fields to sort on. This can also be input via Array Inputs (see above). (Optional)
sortOrder String Comma separated list of ordering. Possible values are ASC and DESC. Default is ASC. If your sortOn contains multiple fields and you would like to order fields individually, you can pass in a comma separated list here (or use Array Inputs, see above). For example, if your sortOn contained 5 fields, and your sortOrder contained ASC,DESC,DESC, these would be applied to the first three items in the sortOn field. The remaining two would default to ASC. (Optional)

Getting Minimum/Standard/Extended Views

In the data definitions for the various objects in the Genability API, you’ll see a “Fields” column for each object property. It can be blank, contain an “E”, or contain an “M”. These values correspond to properties that are in the regular set of fields, the Extended set of fields, or the Minimum set of fields, respectively.

Most requests accept a fields parameter that customizes the data that is contained in the response. For example, pass in a value of min (for minimum) and you will only get a subset of fields in the results you get back. Pass in ext (for extended) and you will get all the fields we make available. “View” therefore modifies the response payload to return data properties flagged as part of the minimum or extended views respectfully. Not passing a fields parameter will return the standard view (so this is the default). The minimum view is designed to make the payload small (and thus quick to load). It’s ideal for situations like building drop-down list or auto complete input boxes. The standard view contains the properties that are commonly used, and is good for showing search results, doing standard computations, and so on. The extended view contains data that is usually not needed but can sometimes be of use.

Value Returns
(blank) Common fields needed for display and most actions.
min A subset of fields (primary and alternate keys, names and codes, important properties). Good for look-ups and cross references.
ext All the fields we make available.

Using SSL

All API methods should be called over SSL. You must use SSL when working with non-public data such as customer accounts and usage profiles. Make sure your client technology supports SSL (most common REST capable client languages and technologies can).

Compressing Requests

The Genability API supports gzip HTTP compression for API responses. You can enable this feature in your client and immediately enjoy a significant reduction in network traffic. Our official Java client library supports this out of the box.

HTTP Response Compression

To enable HTTP response compression, simply add the following header to your requests:

Accept-Encoding: gzip