Before you can use the Genius API service, you’ll need to be registered and set up with us. If you are already registered and have received credentials for access, you are ready to start using the Genius API service.
For security, requests are required to be made over the TLS protocol.
https://api-home.myutilitygenius.co.uk/{yourRequest}
Although other MIME types may be used, "application/Json" is the official MIME type supported
Accept: application/json
All request URI's should not exceed 260 characters in length. On making a request you should state the version of the API that you require. If the version is not stated it would be presumed that the default one is required. Explicitly state the version of the API that you require in the accept header like so:
Accept: application/json; version=default
In the above example a request was made on the “default” version of the API for a MIME type of "application/json" response.
Depending on the request made (typically POST) some requirements in the body are grouped as a BindingModel. BindingModels are simple JSON objects conveniently grouped together for management and readability. As an example, a PersonBindingModel is shown below:
PersonBindingModel: [
{
firstName="Some",
middleName="Random",
lastName="Name"
}
]
In the example above, the PersonBindingModel is a JSON object describing a person whose keys state values for a first, middle, and last name.
All APIs respond with a status code response. These status codes are chosen to give as much useful information about the request made as possible. If there is a response body it would typically be a Response that consists of one or more of the following:
Once registration and set up with MyUtilityGenius is complete, you would be able to request an authorisation Token. An authorisation token needs to accompany every request made.
You request an authorisation token by making a POST request at the token endpoint:
https://authorisation.myutilitygenius.co.uk/connect/token
In the header of the request, you would need to state a form encoded content-type.
Content-Type: application/x-www-form-urlencoded
In the body of the request, you would need to state your username and password created during registration, and a grant_type of client_credentials in a serialized form:
grant_type=client_credentials&scope=DomesticApi&client_id={YourUsernameFromRegistration}&client_secret={YourPasswordFromRegistration}
If the request is succesful (and in turn authenticated) you can expect to get a JSON formated response. The sample shown below is similar to what you can expect:
{
"access_token":"d96tM0nCKx2G1Gz[...]", // this has been shortened for conciseness
"token_type":"bearer",
"expires_in":86399
}
The access_token (defined by the token_type) is required when making every request. In the above example the token "d96tM0nCKx2G1Gz[...]" is of type "bearer"" and is valid for 1 hour. Within that time you can make as many request (as allowed by your registration). After 1 hour you would need a new bearer token to make additional requests to the API.
To make a request, simply include an Authorization header denoting a bearer type together with the bearer token.
Authorization: Bearer d96tM0nCKx2G1Gz[...]
The token sample above has been shortened for conciseness.
Client request to the token endpoint authenticates them. However it's the token that authorizes the client for access to protected resources.
You can make as many request as you like to obtain multiple tokens each of which would be valid for the time stated.
The API is a completely cookieless service and in turn adds to its already secure design.