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

# HEMS Integration

> Create real value for your users in just a few steps!

### Prerequisites:

* A contractual relationship must exist between RABOT and your organisation before you will receive credentials to access the API.

### Let's dive in!

<Steps>
  <Step title="Request your API Credentials">
    Contact your Account Manager at RABOT or our [Integration Management Team](mailto:j.ohara@rabot-charge.de) to get your API client details.

    <Warning>
      Make sure to always keep your client credentials safe. Do not include client credentials in client side code (smartphone app, web application), as they could easily be extracted and misused. If you think your credentials have been compromised, contact RABOT to invalidate the credentials and get a new secret.
    </Warning>
  </Step>

  <Step title="Authenticate using the OAuth 2.0 flow">
    See our guide for reference. Ensure you have the correct scopes!

    <Card title="Authentication" icon="key" href="/guides/authentication">
      API authentication & Scopes
    </Card>
  </Step>

  <Step title="Set up the User Auth Flow to connect their RABOT Tariff">
    As a HEMS partner using our API, your users will need to authorize your client's access to their data, please see our guide below for more information

    <Card title="3rd Party Authorization" icon="link-horizontal" href="guides/customer_linking">
      Generate an authorization link and connect your customer's RABOT tariff
    </Card>

    <Tip>
      Store the `customerNumber` for usage in further API calls, it is a key parameter for generating accessing user data once the accounts are linked
    </Tip>
  </Step>

  <Step title="Access User Data">
    With the `customerNumber` returned in the redirect to `successUrl` above, you can then query customer and contract information, e.g. by calling the [list contracts](/api-reference/customers/list_contracts) endpoint:

    ```bash theme={null}
    curl -L 'https://api.rabot-charge.de/partner/v1/customers/:customerNumber/contracts' \
    -H 'Authorization: ••••••'
    ```
  </Step>

  <Step title="Access Pricing Data">
    Depending on your optimization logic, you can retrieve EPEX day-ahead spot prices and/or the effective WorkingPrice for a specific customer contract.

    **EPEX Day Ahead Spot Price**

    ```shell Request theme={null}
    curl --request GET \
      --url https://api.rabot-charge.de/partner/v1/day-ahead-prices/limited \
      --header 'Authorization: Bearer <token>'
    ```

    **Day Ahead Working Price**

    ```shell Request theme={null}
    curl -L "https://api.rabot-charge.de/partner/v1/customers/:customerNumber/contracts/:contractNumber/metrics?period.from=2025-05-05&period.to=2025-05-06&interval=Hourly&metricType=WorkingPrice&valueType=Combined" \
    -H "Authorization: Bearer <token>"
    ```
  </Step>

  <Step title="Handle the Response">
    Parse the response by deserializing the returned time-series data and transforming it into a normalized format suitable for chart rendering and optimization logic inputs.

    <Card title="Price Charts" icon="chart-line" href="/guides/price_chart">
      Instantly add frills to your UI and participate in the smartification journey!
    </Card>
  </Step>
</Steps>

### Next Steps

Hooray! You've just authenticated the first user account connection and queried the price data to digest and process as desired.

Browse our API endpoints

* [Generate Auth URL](/api-reference/customers/create_customer_linking)
* [Query EPEX Day Ahead Spot Prices](/api-reference/epex-spot-prices/day_ahead_prices)
* [Customer Contract Metrics](/api-reference/customers/get_contract_metrics)

Check out our comprehensive guides for Sales Affilliate partners to ensure a swift and effortless onboarding experience

* [3rd Party Authorization: Customer Data](/guides/customer_linking)
* [Price Charts](/guides/price_chart)

## Questions or Concerns?

Feel free to speak with our [Integration Management Team](mailto:j.ohara@rabot.energy) or alternatively, ask our built-in AI assistant, Rabotini 🤖 (several languages supported).