> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct integration

> For energy suppliers: let customers connect their tariff in Connect by signing in with you.

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](mailto:integrations@flatpeak.com). If you do not integrate, Flatpeak can still list your tariffs in its library.

> [!NOTE]
>
> The endpoints on this page are partner endpoints, which are not in the [Energy API](/docs/energy-api/reference.md) reference. Flatpeak gives you credentials for them during onboarding.

## Authorize access

**1. 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:

```http theme={"system"}
https://<your authentication URI>?connect_session=cos_68541c4c407600f62fd98a97
```

**2. Get the session context**

```bash Request theme={"system"}
curl --request GET \
  --url https://energy-api.flatpeak.com/connect/session/{connect_session} \
  --header 'Authorization: Basic <encoded-value>'
```

```json Response theme={"system"}
{
  "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 |

**3. Sign the customer in**

Show your own login screen.

**4. 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](https://mintcdn.com/flatpeak-d495c19e/2B6nWUU4-c2pSD3E/images/busbar/connect/consent.png?fit=max\&auto=format\&n=2B6nWUU4-c2pSD3E\&q=85\&s=cbed09127ec56c17448c381e7c95c62c)

Consent screen

**5. 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` |

```bash Consent given theme={"system"}
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"
  }'
```

```bash Declined theme={"system"}
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"
}'
```

```json Response theme={"system"}
{
  "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` |

**6. Send the customer back**

Redirect the browser to `connect_url` with the `connect_session` query parameter:

```http theme={"system"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.