Momentum Energi External API is the customer facing API of Momentum Energi, a SaaS solution mainly used for managing facilities' energy consumptions. We provide a REST API built on RESTful design principles.
Our API uses resource-oriented URLs that leverage built in features of HTTP, like authentication, verbs and response codes. All request and response bodies are JSON encoded, including error responses. Any off-the-shelf HTTP client can be used to communicate with the API.
This is a versioned API that uses the endpoints' URIs for routing between different versions of the API. Endpoints as well as whole API versions can be marked as deprecated indicating that they have been replaced by newer versions. It is strongly recommended to adapt to the newer versions because deprecated versions are subject to removal.
All available API versions and endpoints can be found in the menu item API here above.
Before being able to connect to the API, the following needs to be done.
You will need to setup a specific user in Momentum Energi. The user must have a role containing the operation named Access external API acc_extapi.
Setup the user's access rights according to your preferences. All data accessed through the API will be restricted by the user's access rights.
You will have your own client configuration in Momentum Energi. The client information is used when authenticating. In order to configure your API client, we need the below information. Please contact your account manager at Momentum to begin the process of enabling API access. If you don't have a specific account manager assigned to your company, please contact our help desk via Momentum Kontakt.
Mandatory information for API access:
This API is authenticated using OAuth2 Auth over HTTPS. Any requests over plain HTTP will fail.
All requests are associated with a specific user in Momentum Energi, see prerequisites section above, and permissions are limited to that user's capabilities.
Current OAuth flow is Resource Owner but please note that this will be a subject of change in the near future because plans are that we will switch to Authorization Code flow with PKCE.
The URL for authenticating is https://identity-rc.momentum.se/connect/token. Pass along the information in the table below in the request body as x-www-form-urlencoded
Upon succesful authentication you will be receiving your access token of JWT type in the response's header. Use that access token when performing your requests to the API.
| Key | Value | Example |
|---|---|---|
| client_id | Identification of the client. Value is preregistered by Momentum and it's value is external_access. | external_access |
| client_secret | Secret that only you know and which are set up during section Prerequisites above. The secret is coupled with the client id. | MyPrivateAPISecret |
| grant_type | In what way are you going to authenticate the API user. For now, only password is a valid value. | password |
| username | The user name and company name as configured in Momentum Energi. Please see section Prerequisites above. | apiUser@myCompanyName |
| password | The API user's password in Momentum Energi. | mySecretPassword |
| scope | Which scopes does the authentication request want access to? For now, only external_access is a valid value. | external_access |
The lifetime of the access token is one (1) hour which also is informed of in the authentication response headers. Currently there is no support for refresh tokens and requesting part therefor needs to handle renewing access token via above mentioned authentication procedure manually.
The base URL for all requests to the API is https://api-rc.momentum.se.
We use standard HTTP verbs to indicate intent of a request:
GET To retrieve a resource or a collection of resources.
POST To create a resource.
PUT To set/update a resource.
DELETE To delete a resource.
All POST- and PUT-requests are JSON encoded and must have have content type of application/json, or the API will return a 415 Unsupported Media Type status code.
All response bodies are JSON encoded.
A single resource is represented as a JSON object:
{
"field1": "value",
"field2": true,
"field3": []
}A collection of resources is represented as a JSON array of objects.
{
"data": [
{
"itemKey": "sample string 1",
"usageType": "sample string 2",
"mediaClass": "sample string 3",
"mediaType": "sample string 4",
"startDate": "2021-10-15T10:41:04.393597+02:00",
"stopDate": "2021-10-15T10:41:04.393597+02:00",
"consumptionUnit": "sample string 7",
"consumption": 1.1,
"consumptionNormalized": 1.1,
"energyUnit": "sample string 8",
"energy": 1.1,
"energyNormalized": 1.1,
"lastUpdated": "2021-10-15T10:41:04.3946315+02:00"
},
{
"itemKey": "sample string 1",
"usageType": "sample string 2",
"mediaClass": "sample string 3",
"mediaType": "sample string 4",
"startDate": "2021-10-15T10:41:04.393597+02:00",
"stopDate": "2021-10-15T10:41:04.393597+02:00",
"consumptionUnit": "sample string 7",
"consumption": 1.1,
"consumptionNormalized": 1.1,
"energyUnit": "sample string 8",
"energy": 1.1,
"energyNormalized": 1.1,
"lastUpdated": "2021-10-15T10:41:04.3946315+02:00"
}
],
"total": 36,
"take": 2,
"skip": 0
}
In general, timestamps are in UTC and formatted as ISO8601. Unset fields will be represented as a null instead of not being present. If the field is an array, it will be represented as an empty array, i.e. [].
We use HTTP status codes to indicate success or failure of a request.
Success codes:
200 OK - Request succeeded. Response included
201 Created - Resource created. URL to new resource in Location header
204 No Content - Request succeeded, but no response body
Error codes:
400 Bad Request - The request was unacceptable, often due to missing a required parameter.
401 Unauthorized - No authentication credentials provided or authentication failed
403 Forbidden - Authenticated user does not have access
404 Not Found - Resource not found
415 Unsupported Media Type - POST/PUT/PATCH request occurred without a application/json content type
422 Unprocessable Entry - A request to modify or create a resource failed due to a validation error
429 Too Many Requests - Request rejected due to rate limiting. We recommend an exponential backoff of your requests.
500, 501, 502, 503, etc - Something went wrong on Momentum's end.
All 400 series errors will be returned with a JSON object in the body and a application/json content type.
{
"message": "Not Found"
}
Requests for collections can return between 0 and 10.000 results, controlled using the query parameters Take and Skip. All end points are limited to 3.000 results by default. In the example below,
the response is skipping the first 450 results and returning result 451 to 600, i.e. page 4.
GET api/external/v1/statistics/level/E/updatedAfter/2021-01-01?Take=150&Skip=450Not all endpoints may support pagination. If not, the full result set is returned no matter what values Take and Skip has.