Skip to main content

Quickstart

Introduction​

This guide will help you get started with the Energy Coordination API. It will walk you through the process of authenticating with the API, registering a user and some resources, subscribing to events, and sending a report.

The base URL for the API is https://api.sandbox.voluespark.com/energy-coordination/v1

Postman​

We have a Postman Collection with all the endpoints from the API, as well as a folder that follows along with this guide. You can download the Postman Collection here.

Authentication​

We use OAuth2 for authentication. If don't have a client ID and secret, you can create those in the Spark Portal. Get an access token by sending a POST request to https://auth.identity.volue.com/connect/token as follows:

curl --location 'https://auth.identity.volue.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your_client_id>' \
--data-urlencode 'client_secret=<your_client_secret>'

Then you can use the access token to authenticate with the API by sending it in the Authorization header in subsequent requests to the Energy Coordination API:

Authorization: Bearer <access_token>

The token is valid for 60 minutes so you will need to refresh it periodically.

Postman Authentication​

If you are using the Postman Collection, you can set up the authentication by following these steps:

  1. Go to the Variables tab in the Collection
  2. Set the client_id and client_secret variables to your client ID and secret
  3. Click the Get New Access Token button

1. Registering a User​

The User object represents a user or customer of your service. Use it to register Locations and Resources that your user owns to let us know who should get incentives based on your Reports.

You can create users via POST /users, the response is a userId that you can use to refer to the user in subsequent requests.

{
  "userId": "3880a832-f483-4b6a-998d-6109d3a54b06"
}

2. Registering a Vehicle​

Resources can either be registered to a fixed location, or be free standing resources that move around such as vehicles.

You can create vehicles via POST /users/:userId/vehicles, the payload should be information identifying a unique vehicle:

{
  "resourceId": "4b146c67-9e59-4cfb-863c-8c175659e8ba",
  "resourceType": "Vehicle"
}

3. Registering a Location​

The Location object represents a specific location that belongs to one of your users. This is the information we give to DSOs so they can correctly send out incentives to your users.

You can create locations via POST /users/:userId/locations:

{
  "locationId": "3fd2a74c-9a01-4c78-a924-60054faffa75",
  "locationType": "Residential",
  "meterPointId": "12345678901234567890123456789012",
}

4. Registering a Location Bound Resource​

The Resource object represents a specific resource that your user owns.

You can create resources that are bound to a fixed specific location via POST /users/:userId/locations/:locationId/resources, the payload should be information identifying a unique resource:

{
  "resourceId": "23202835-7843-4a90-b6d9-235fdf0e5844",
  "resourceType": "HotWaterTank"
}