[accountId]:[apiKey]

FlatPeak

Guides

API Reference

API Help

Legal

Home

Dashboard

Support

Retrieve an event

This object represents a device or another asset of a compatible type.

Timestamp of when the device has last queried the service.

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

A reference that is meaningful to you, for example, an ID from your system.

Time when the object was created, in UTC.

Device

bearerAuth

FlatPeak is an energy tariff data and optimisation platform. It connects you to your customer’s electricity tariff in real time and helps you steer your devices (or other assets) to use lower-cost energy.

Introduction

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.

Planning your integration

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

Trying hosted 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

Single-page web app Tutorial

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

Native app or Server-side

Native app or server-side Tutorial

When integrating Connect into your app, you can build an informative page that enables your customers to quickly check, initiate and manage tariff connections.

Displaying tariff settings

Implementing 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 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.

Implementing tariff lifecycle

Implementing tariff lifecycle webhooks

Creating device identifiers

FlatPeak [tariff-rates](/api-reference/tariffs/get-tariff-rates) API endpoint returns live tariff rates by `location_id`.

Getting tariff rates

Calculating energy cost

Calculating carbon

Calculating carbon intensity

Using Copilot steering

Implementing tariff based consumption steering

Accounting local generation

Energy provider integration

How to develop an energy provider integration pluggable to FlatPeak

Authorization

API Authorization

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 mode

Pagination

Events

Webhooks

Deletions

Objects deletion

Errors

API Errors

Market rates

How FlatPeak supports dynamic market rates

Terms of Service

Service Level Agreement

Support Policy

Data Processing Agreement

Privacy Statement

Data Disclosure Policy

Acceptable Use Policy

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

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

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

<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

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

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

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 a /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

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

Returns tariff rates by FlatPeak `location_id` in time series format.

Get tariff rates

<Note>This endpoint is in invite-only beta. [Request access](https://forms.gle/jyoPr3rihseywr988).</Note>

Returns audit of tariff rates calculation by FlatPeak `location_id`.

Audit tariff rates

<Note>This endpoint is in invite-only beta. [Request access](https://forms.gle/jyoPr3rihseywr988).</Note>

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

<Note>This endpoint is in invite-only beta. [Request access](https://forms.gle/jyoPr3rihseywr988).</Note>

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

<Note>This endpoint is in invite-only beta. [Request access](https://forms.gle/jyoPr3rihseywr988).</Note>

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

<Note>This endpoint is in invite-only beta. [Request access](https://forms.gle/jyoPr3rihseywr988).</Note>

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

Delete a tariff

<Note>This endpoint is in invite-only beta. [Request access](https://forms.gle/jyoPr3rihseywr988).</Note>

Returns list of all schedules.

List schedules

<Note>This endpoint is in invite-only beta. [Request access](https://forms.gle/jyoPr3rihseywr988).</Note>

Creates import/export schedule for devices at a location.

Create a schedule

<Note>This endpoint is in invite-only beta. [Request access](https://forms.gle/jyoPr3rihseywr988).</Note>

Retrieves a schedule.

Introduction

Tariff connect

Cost reporting

Metering

Tariff rates

Tariff elements (beta)

Copilot (beta)

Retrieve an event

Authorizations

Path Parameters

Response