[accountId]:[apiKey]

FlatPeak

Guides

API Reference

API Help

Legal

Home

Dashboard

Support

<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

Represents tariff connection type. Set automatically by FlatPeak depending on how tariff was created.

Indicates end date of the energy supply contract between customer and provider.

Indicates start date of the energy supply contract between customer and provider.

Indicates direction of energy transfer this tariff applies to. Supported options are IMPORT, EXPORT or LOCAL. LOCAL direction is in beta. Contact support to enable.

This indicates that the tariff is linked to an external data source and is automatically updated from this source. Such as when it's linked to your customer's provider account or to a tariff in the FlatPeak tariffs library. This value is set automatically by FlatPeak and cannot be changed.

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

FlatPeak Location ID this tariff element is associated with.

Indicates if this tariff is based on a market rate.

FlatPeak object type. I.e. tariff_element.

FlatPeak ID of the provider this tariff belongs to.

Status of tariff element. Possible values are CONNECTED or ERROR.

Indicates time when this tariff object was created.

The timezone at the location, in 'tz database format'. I.e. 'Europe/Berlin'.

Indicates tariff type you want to work with. Set to COMMODITY or NON_COMMODITY.

TariffElementNew

Array of 3-letter abbreviation on months names when the tariff is valid. `All` specifies all months.

An array of months when the tariff valid.

TariffSchedule

bearerAuth

FlatPeak connects your product or service to your customer's energy tariff and other key energy data. Allowing it to intelligently use and export 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, use the FlatPeak-hosted version of Connect to quickly test your application with FlatPeak's simulated test energy provider. You can also test with any live energy provider using your own account with them.

Trying hosted Connect

In this tutorial, we will learn how to integrate the single-page web version of Connect, the **Connect-web** into your application to get consent from your customers to access their energy tariffs.

Single-page web app

Single-page web app Tutorial

In this tutorial, we will learn how to integrate the JSON version of Connect, the **Connect-headless** into your application to get consent from your customers to access their energy tariffs.

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 (+solar) based consumption and/or export steering with Copilot

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

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

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

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)

List tariffs

Authorizations

Query Parameters

Response