Direct integration

This page is for energy suppliers. With a DIRECT integration, a customer connects their tariff by signing in with you, and Flatpeak then reads the tariff from your systems. Flatpeak builds the integration against your authentication method and data format; OAuth with long-lived tokens works best. It typically takes 2 to 4 weeks, followed by 2 weeks of testing. To start, contact integrations@flatpeak.com. If you do not integrate, Flatpeak can still list your tariffs in its library.

The endpoints on this page are partner endpoints, which are not in the Energy API reference. Flatpeak gives you credentials for them during onboarding.

Authorize access

Receive the redirect

When the customer selects you as their supplier, their app opens your authentication URI with a connect_session, a time-limited token for the session:

https://<your authentication URI>?connect_session=cos_68541c4c407600f62fd98a97

Get the session context

curl --request GET \
  --url https://energy-api.flatpeak.com/connect/session/{connect_session} \
  --header 'Authorization: Basic <encoded-value>'

{
  "connect_session": "cos_68541c4c407600f62fd98a97",
  "energy_flow_direction": "IMPORT",
  "live_mode": true,
  "data": {
    "accepted_terms": false,
    "account": {
      "id": "acc_65e421bed29d88d9012e0662",
      "display_name": "ACME",
      "logo_url": "https://static.flatpeak.com/<...>/acme.png",
      "privacy_url": "https://acme.com/privacy",
      "support_url": "https://acme.com/support",
      "terms_url": "https://acme.com/terms"
    },
    "urls": {
      "redirect_uri": "<your authentication URI>",
      "connect_url": "https://auth.direct.flatpeak.com"
    }
  }
}

Field	Use
`data.account`	The company asking for access. Show its name, logo and links on your consent screen
`data.urls.redirect_uri`	Your authentication URI, for audit
`data.urls.connect_url`	Where you send the customer when you finish

Sign the customer in

Show your own login screen.

Ask for consent

Ask the customer to let the company in data.account access their tariff data.

Consent screen naming the company that asks for tariff access — Consent screen

Report the outcome

Outcome	Call
Login declined or failed	`PUT /connect/consent_capture/{connect_session}` with `action` `DISMISS_LOGIN`
Consent declined	`PUT /connect/consent_capture/{connect_session}` with `action` `DISMISS_CONSENT`
Consent given	`PUT /connect/auth_capture/{connect_session}` with `auth_data`

curl --request PUT \
  --url 'https://energy-api.flatpeak.com/connect/auth_capture/{connect_session}' \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
    "auth_data": {
      "access_token": "476dfc58-fd6a-4a32-9483-7dd9b8126c6e",
      "user_prefix": "EYR43EUT-1"
    },
    "postal_address": {
      "address_line1": "1-3",
      "address_line2": "Strand",
      "city": "London",
      "post_code": "WC2N 5EH",
      "country_code": "GB"
    },
    "contract_term": {
      "start_date": "2026-01-01T00:00:00Z",
      "end_date": "2027-01-01T00:00:00Z"
    },
    "terms_url": "https://acme.com/terms"
  }'

curl --request PUT \
  --url 'https://energy-api.flatpeak.com/connect/consent_capture/{connect_session}' \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "DISMISS_CONSENT"
}'

{
  "connect_session": "cos_68541c4c407600f62fd98a97",
  "energy_flow_direction": "IMPORT",
  "live_mode": true,
  "status": "accepted"
}

Field	Required	Use
`auth_data`	Yes	Every key-value pair Flatpeak needs to read the customer’s tariff without them, such as an access token
`postal_address`	No	Sets the market region and grid fees
`contract_term`	No	The start date sets where tariff history begins. The end date triggers a reminder to reconnect
`terms_url`	No	The terms the customer accepted with you, which Flatpeak stores with the timestamp. Also accepted with `DISMISS_CONSENT`

Send the customer back

Redirect the browser to connect_url with the connect_session query parameter:

https://auth.direct.flatpeak.com?connect_session=cos_68541c4c407600f62fd98a97

Tariff polling

Flatpeak reads the tariff from your systems with the credentials in auth_data, typically every 1 to 2 days. You set the polling frequency you allow and how tokens renew. Return, in your own format:

The customer’s tariff, covering at least the next 24 hours.
The contract start date. Flatpeak uses it to backfill tariff history.
The contract end date, optional. Flatpeak uses it to remind the customer to reconnect before the tariff expires.

Get started

Enroll customers

Devices

Tariffs

Dispatch devices

Settle and reward

Platform

Direct integration

Authorize access

Tariff polling