[accountId]:[apiKey]

FlatPeak

Guides

API Reference

API Help

Commercials

Home

Dashboard

Support

FlatPeak API reference

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.

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

Try 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

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.

Handling tariff lifecycle

Connect lifecycle with events and webhooks

Adding devices

Why add your Devices to FlatPeak

Submitting meter records

Why submit metering records to FlatPeak

Calculating energy cost

Calculating your customer's energy cost

Carbon intensity

Why FlatPeak includes grid carbon intensity data

Add provider integration

Provider integration development guide

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

Pricing

Plans that scale with your company

Terms of Service

Privacy Statement

Service Level Agreement

Data Processing Agreement

Disclosure Request

To create a bearer token, send a request to this endpoint using basic auth. Use following username/password pair:

  | []()            | []()                                                                   
  | --------------- | ------------------------------ |
  | `username`      | Your FlatPeak account id.      |
  | `password`      | Any of your FlatPeak API keys. |

You can locate your FlatPeak account ID and generate an api_key in [API keys section](https://dashboard.flatpeak.com/keys) of Dashboard.

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 customers are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all customers 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.

<Warning>Do not update 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 update customers as part of its flow.</Warning>

Update a customer

Delete a customer

Returns list of all Locations.

<Info>Location is an identifier of a supply address where energy is being imported or/and exported under the contract between the provider (aka supplier, aka utility) and a customer (i.e. consumer of energy).</Info>

List locations

Retrieves a location.

<Info>Location is an identifier of a supply address where energy is being imported and/or exported under the contract between the provider (aka supplier, aka utility) and a customer (i.e. consumer of energy).</Info>

Retrieve a location

Create a location.

<Warning>Do not create locations 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 locations as part of its flow.</Warning>

Create a location

Updates the specified location.

<Warning>Do not update locations 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 update locations as part of its flow.</Warning>

Update a location

Delete a location

List all devices

Retrieves the details of an existing device.

Retrieve a device

Create a device

Updates the specified device. 

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

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

Get tariff rates

<Warning>
This object is made available for transparency and troubleshooting only. Do not utilise it in your live systems. Use [/tariff-rates](/api-reference/tariffs/get-tariff-rates) instead.
</Warning>

Retrieve a tariff element

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

Accepts an array of meter records.

If you are metering an individual device (such as EV or EVSE), make sure you submit records under `device_id` [learn more](/help/devices).

Only submit records for `location_id` if they represent data for an entire location (i.e. from the main supply address meter).

Submit meter records

Submit an array of meter records

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

Returns processing status of meter records batch when multiple records were submitted to [/meters](/api-reference/meters/submit-an-array-of-meter-records) endpoint.

Check batch status

Meter batch status

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

Ingests a meter record and instantly returns import or export monetary value (cost) of energy by FlatPeak `location_id` or `device_id`.

<Info>Meter records are permanently stored and can be used in other cost-calculations endpoints.</Info>

Instantly on-demand

Instantly calculate energy cost

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

Returns import or export monetary value (cost) of energy by FlatPeak `location_id` or `device_id`. Meter records must have been previously submitted to [/meters](/api-reference/meters/submit-an-array-of-meter-records) endpoint.

By time interval

Calculate energy cost by time interval

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

Returns import or export monetary value (cost) of energy by `session_reference_id` that have been previously submitted to [/meters](/api-reference/meters/submit-an-array-of-meter-records) endpoint.

By session id

Calculate energy cost by session ID

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

Creates an import or export schedule for a location. Every time you make a request, all previous schedules for specified direction (i.e., IMPORT or EXPORT) are invalidated.

Create for a location

Create schedule for a location

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

Retrieves the details of an existing schedule for a location.

Introduction

Connect

Tariff rates

Meters (beta)

Cost calculations (beta)

Schedules (beta)

FlatPeak API reference

FlatPeak makes it easy to build applications that smartly use energy

Introduction

Connect

Tariff rates

Meters (beta)

Cost calculations (beta)

Schedules (beta)

​FlatPeak makes it easy to build applications that smartly use energy

FlatPeak makes it easy to build applications that smartly use energy