Use this method integrate FlatPeak’s Connect flow into your app using your existing framework. We recommend starting with the WebView integraiton guide before implementing the Native API. It provides helpful context on how the Connect flow works and what to expect during integration.

​
Integrating Connect

The Connect API works as a conversational flow using JSON messages — unlike traditional REST APIs.
1

Start the Connect Session

  1. Present a “Connect My Tariff” button (or similar UI control).
  2. Call the create-connect-token endpoint to generate a temporary connect_token.
  3. Use the token to launch the session via the session_restore endpoint.
Your app is now ready to interact with Connect.
2

Render Page Objects

FlatPeak will send a sequence of Page Objects each containing the next step in the tariff discovery flow. Your app must:
  • Render the UI implied by the current Page Object,
  • Capture user input,
  • Send it back to the Connect API,
  • Receive the next object in sequence.
This loop continues until the session completes.
3

Handle Completion

Once the flow completes:
  • You receive a session_complete page.
  • A webhook is sent to callback_uri you specified when creating the connect_token - to inform your backend that the tariff is now connected.
  • You exchange the connect_token for a permanent location_id and store it alongside your customer’s address.
4

Subscribe to Lifecycle Webhooks

FlatPeak keeps tariff data up to date post-connection. If customer action is needed (e.g. expired password), FlatPeak will generate an events and send it to you via webhook. Subscribe to them to inform users and guide them to re-connect when necessary.
5

Allow Configuration Changes

To let users review or update their tariffs post-connection, refer to the Tariff Settings Page guide to provide UI controls for users to view, reconnect, or adjust their tariff flows—including commodity, export, or grid-fee options.

​
Next integration steps

After connecting the tariff, you can access:

​
Summary workflow

StepAction
1UI triggers Connect flow using create-connect-token and session_restore
2App loops through Page Objects: render, collect input, send response
3On session_complete, exchange token for location_id
4Subscribe to lifecycle webhooks (tariff.expiring, tariff.expired, tariff.fetch.failed)
5Offer tariff settings UI for reconnecting or adjusting flows
6Use scheduling, cost reporting, or raw rate endpoints as needed