Error object

Account disabled error

[accountId]:[apiKey]

FlatPeak

Getting Started

API Guides

API Reference

Open Source

Commercials

Home

Dashboard

Support

Errors

FlatPeak is an energy tariff data and optimisation platform that connects you to your customer's actual electricity tariff. It enables you to optimise your devices to use lower-cost energy and report monetary savings.

What is FlatPeak

It only takes two steps to integrate FlatPeak into your app and back-end before you can start making requests for your customer's energy tariff.

Service architecture

FlatPeak enables you to optimise the operation of devices under your control to reduce your customers’ energy costs and demonstrate savings.

Overview

This tutorial shows how to use FlatPeak to reduce and report energy costs for systems like EVSEs or smart sockets.

Switched system

In this tutorial, you will learn how to leverage FlatPeak if your system generates energy, such as solar PV or wind turbine, and you want to report cost savings and export revenue that it creates.

Generation system

In this tutorial, you will learn how to leverage FlatPeak if your system is an energy storage device, and you want to optimise its operations to maximise savings and accelarate the ROI.

Storage system

In this tutorial, you will learn how to leverage FlatPeak if your system is an EV, and you want to optimise charging to lower energy cost.

Electric vehicle

Before implementing Connect integration, you can use the FlatPeak-hosted version of Connect to quickly test the experience it provides.

Exploring Connect

In this tutorial, you will learn how to integrate the web version of Connect, the **Connect-web** into your application.

Single-page web app

In this tutorial, you will learn how to integrate the "JSON API" version of *Connect*, the **Connect-headless**, natively into your application.

Native app or Server-side

Native app or server-side integration

In this tutorial, you will learn how to build a page in your app to enable your customers to quickly add, check status and manage tariff connections.

Tariff settings page

Building tariff settings page in your app

Once your customer has completed the Connect flow, you can use Connect to display the summary of their tariff inside your app.

Displaying tariff summary

Displaying customer's tariff on-demand in your app

Once your customer has completed the Connect flow, FlatPeak systems will kick in to automatically keep their tariff information up to date.

Lifecycle webhooks

Implementing tariff lifecycle webhooks

If you are missing FlatPeak direct integration with your favorite energy provider, you can develop it yourself by following this guide.

Energy provider integration connector

Open source FlatPeak provider integration module

Test mode is an isolated environment in your FlatPeak account that enables you to develop and test your integration without affecting your production data.

Test (sandbox) mode

Authorization

API Authorization

Events

Pagination

Webhooks

Objects deletion

In this tutorial, you will learn how to import and manage your customer's tariffs in FlatPeak when you cannot use [Connect](/start/connect/explore).

Tariff elements

Using API to create and manage tariffs

Device identifiers

Managing device identifiers

In this tutorial, you will learn how to calculate the cost of energy that your device is using (or exporting) at your customer's premises.

Calculating energy cost

In this tutorial, you will learn how to use FlatPeak API to calculate carbon footprint of your devices, in addition to the monetary cost of energy they use.

Calculating carbon

Calculating carbon intensity

In this tutorial, you will learn how obtain your customer's tariff rates and use it to calculate your customer's energy cost.

Getting tariff rates

Getting market rates

Automatic market rates integration

In this tutorial, you will learn how to account for local generation in FlatPeak service.

Local generation

Accounting local generation

In this tutorial, you will learn how to lower your device's energy cost by aligning its operation with price of energy in real-time with FlatPeak Copilot Schedules.

Scheduling energy use

Scheduling energy import and export

Terms of Service

Service Level Agreement

Support Policy

Data Processing Agreement

Privacy Statement

Data Disclosure Policy

Acceptable Use Policy

Introduction

FlatPeak API uses [bearer authentication](/help/api-authorization) (also called token authentication) to authorize access to API endpoints. To create a bearer token, use this `/login` endpoint with basic auth:

  | []()            | []()                                                                   
  | --------------- | ------------------------------ |
  | `username`      | Your FlatPeak Account ID.      |
  | `password`      | Any of your FlatPeak API Keys. |

<Tip>Account ID and API Keys can be found on [API Keys](https://dashboard.flatpeak.com/keys/api) page of Dashboard.</Tip>

Create a bearer token

In order launch a session with Connect you need a `connect_token`. 

Connect tokens serve single purpose of authenticating your customer's session with Connect and are dismissed as soon as you [exchanged](/api-reference/connect/exchange-a-connect-token) the token for `location_id` once your customer's session with Connect has ended.

<Info>Refer to [Connect-web](/guides/connect-web-tariff) and [Connect-headless](/guides/connect-headless-tariff) to learn how to implement Connect with your application.</Info>

Create a token

Create a connect token

To start requesting your customer's tariff rates from this API, you need to exchange the `connect_token` for a `location_id`.

Exchange a token

Exchange a connect token

Lists events, going back up to 90 days.

Events are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all events in pages of 100 are returned.

List all events

Retrieve an event

Returns a list of all customers. 

The objects are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all objects in pages of 100 are returned.

List all customers

Retrieves the details of an existing customer.

Retrieve a customer

Creates new customer.

<Warning>Do not create customers via this endpoint unless you are performing a bulk import from your system or have been advised by FlatPeak support. Instead, use [Connect](/guides/integration-plan), which will automatically create customers as part of its flow.</Warning>

Create a customer

Updates the specified customer. Any parameters not provided will be left unchanged.

Update a customer

Delete a customer

<Info>Location is an identifier of a supply address.</Info>

Returns list of all Locations.

The objects are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all objects in pages of 100 are returned.

List locations

Retrieve a location

<Note>This endpoint is in invite-only beta. [Request access](https://flatpeak.com/support).</Note>

<Info>This endpoint supports Locations with up to one each of `commodity_import`, `commodity_export`, `non_commodity_import`, and `non_commodity_export` tariff elements, covering all use cases currently supported by Connect. If your implementation requires more (typically complex industrial cases) contact [support](mailto:support@flatpeak.com) for assistance.</Info>

Retrieves current status of a location.

Retrieve a location status

<Info>Location is an identifier of a supply address.</Info>

Creates a location.

Create a location

Updates the specified location. Any parameters that have not been provided will be left unchanged.



Update a location

Delete a location

Returns list of all tariffs. Use this to read tariff objects listed in tariff_elements property of Location.

The objects are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all objects in pages of 100 are returned.

List tariffs

Creates a tariff. Use this endpoint to manually create a tariff and link it to a Location. Useful when you are importing data to FlatPeak.

Create a tariff

Retrieves the details of an existing tariff. Use this endpoint to via details of a specific tariff listed in `tariff_elements` property of the Location object.


Retrieve a tariff

Deletes a tariff. Will also automatically remove tariff from `tariff_elements` property of the Location object it is associated with.

Delete a tariff

List all devices

Retrieves the details of an existing device identifier.

Retrieve a device

Create a device

Updates the specified device identifier. Any parameters that have not been provided will be left unchanged.

Update a device

Delete a device

Accepts array of meter records holding energy use values for each period.

- If you are metering a device, submit records under `device_id`.
- If you are metering a location (i.e. main supply address meter), submit records under `location_id`.

Submit interval

Submit interval meter records

Accepts array of meter records holding energy use as cumulative values.

- If you are metering a device, submit records under `device_id`.
- If you are metering a location (i.e. main supply address meter), submit records under `location_id`.

Submit cumulative

Submit cumulative meter records

Returns processing status of meter records batch when multiple records were submitted to meters endpoints.

Check batch status

Check submission batch status

Ingests a meter record and instantly returns import or export monetary value (cost) of energy.

- If you are metering a device, submit records using `device_id` parameter.
- If you are metering a location (i.e. main supply address meter), submit records under `location_id` parameter.

<Info>Meter records that are submitted via this endpoint will be permanently stored and will be used for other cost-calculations endpoints.</Info>

Instantly on-demand

Instantly calculate energy cost

Returns monetary value (cost) of energy by FlatPeak `location_id` or `device_id`. Meter records must have been previously submitted to the `/meters` endpoint.

By time interval

Calculate energy cost by time interval

Returns monetary value (cost) of energy by `session_reference_id` that have been previously submitted to a /meters endpoint.

By session id

Calculate energy cost by session ID

Returns raw tariff rates in time series format, by Location ID.

Get raw tariff rates

Returns audit of tariff rates calculation, by Location ID.

<Info>Please note that this endpoint is intended for diagnostic purposes and when you need to demonstrate how tariff rates are calculated. Strict usage limits may be applied. Use [tariff-rates](/api-reference/tariffs/get-tariff-rates) for high-frequency use cases.</Info>

Audit tariff rates

Returns a time slot when tariff is highest or lowest, over requested time period. 

*Useful when you need 5 hours of lowest price time over a given day. Slot might be split into a multiple segments unless you set continuous to true.*

Amount of time

Get usage slots for required time amount

Returns time slots were tariff rate is below or above target level, by Location ID. 

*Useful when you need to provide, say, 5 hours of charging time between 9pm and 6am when price is lowest.*

Code	Description
`2XX`	Indicates success.
`4XX`	Indicates an invalid request. (error type: `invalid_request`)
`5XX`	indicates FlatPeak-related issues (error type: `api_error`).

Property	Description
`object`	Indicates API object type, i.e. `error`.
`live_mode`	Indicates if `live` or `test` mode API key was used.
`context`	Indicates error context. It provides information on which service and method has errored. For example, `connect.postal_address_capture` or `api.location_create`.
`type`	Indicates error type; possible values are `invalid_request` - when your request is invalid. And `api_error` when the FlatPeak service cannot process the request (these are rare).
`code`	Connect-related error codes are listed in connect-headless guide under code sample of every page. API-related error codes are listed in the API error codes table later on this page. Example: `country_code_missing`.
`message`	Error description in the English language. Example: `Country code is required`.
`connect_token`	The Connect token used to make the request resulted in an error.
`time_created`	Timestamp when this error has occurred.

Service objects

Reporting

Planning

Errors

Error object

Account disabled error

Service objects

Reporting

Planning

​Error object

​Account disabled error

Error object

Account disabled error