Lumenaza API: Quickstart

This guide walks you through everything you need to make your first successful call to the Lumenaza API. By the end, you will have obtained an access token, confirmed connectivity to the test environment, and registered a consumer — all using plain HTTP requests you can run directly from your terminal.

Prerequisites

Before you begin, make sure you have the following:

OAuth 2.0 client credentials (client_id and client_secret) issued by Lumenaza for your organization. If you do not have these yet, contact your Lumenaza account manager.
curl or an equivalent HTTP client (Postman, Insomnia, etc.) installed locally.
Access to the test environment at https://api.test.lumenaza.de/ — no production data is affected during this guide.

All examples below target the test environment. To use the production environment, replace https://api.test.lumenaza.de/ with https://api.lumenaza.de/ in every URL. Never run exploratory or development requests against production.

Steps

Obtain an Access Token

The Lumenaza API uses the OAuth 2.0 client credentials flow. Send a POST request to the token endpoint with your credentials to receive a bearer token.Token endpoint: https://api.test.lumenaza.de/oauth2/token/

curl --request POST \
  --url https://api.test.lumenaza.de/oauth2/token/ \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET"

A successful response returns a JSON object containing your access_token and its lifetime in seconds:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Copy the value of access_token — you will use it as the Bearer token in all subsequent requests.

Access tokens expire after the number of seconds indicated by expires_in (typically 3 600 seconds / 1 hour). When a token expires, your requests will receive a 401 Unauthorized response. Simply repeat this step to obtain a fresh token. Build token refresh logic into your integration from the start so that long-running processes are never interrupted.

Make a Test API Call

Verify that your token works by fetching the list of consumers registered under your organization. This endpoint returns an empty list if you have not registered any consumers yet — that is expected.Endpoint: GET https://api.test.lumenaza.de/v3/consumers/

curl --request GET \
  --url https://api.test.lumenaza.de/v3/consumers/ \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

A successful response looks like this:

{
  "count": 0,
  "next": null,
  "previous": null,
  "results": []
}

If you receive a 401 Unauthorized error, your token may have expired or been copied incorrectly. Re-run Step 1 to obtain a new token and try again.

Always include the Authorization: Bearer header on every request. Omitting it or using a malformed value results in a 401 error and the request will not be processed.

Now register a consumer (electricity buyer) under your organization. Send a POST request to /v3/consumers/create/ with a JSON body containing the required fields.Endpoint: POST https://api.test.lumenaza.de/v3/consumers/create/

curl --request POST \
  --url https://api.test.lumenaza.de/v3/consumers/create/ \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada.lovelace@example.com",
    "salutation": "ms",
    "is_business": false,
    "deliv_address_street": "Musterstraße",
    "deliv_address_house_number": "12",
    "deliv_address_zipcode": "10115",
    "deliv_address_city": "Berlin",
    "annual_consumption": 3500,
    "subscription_reason": "move_in",
    "tariff_type": "green_standard"
  }'

The required fields for consumer registration are:

Field	Type	Description
`first_name`	string	Consumer’s given name
`last_name`	string	Consumer’s family name
`email`	string	Contact email address
`salutation`	string	Salutation code (e.g. `"mr"`, `"ms"`)
`is_business`	boolean	`true` for business accounts, `false` for private
`deliv_address_street`	string	Street name of the delivery address
`deliv_address_house_number`	string	House number of the delivery address
`deliv_address_zipcode`	string	Postal code of the delivery address
`deliv_address_city`	string	City of the delivery address
`annual_consumption`	integer	Estimated annual consumption in kWh
`subscription_reason`	string	Reason for joining (e.g. `"move_in"`, `"supplier_change"`)
`tariff_type`	string	Identifier of the tariff to assign

A successful 201 Created response returns the new consumer and contract identifiers:

{
  "consumer_id": "CON-0001234",
  "contract_id": "CTR-0009876"
}

Store both identifiers — you will use consumer_id to manage the account and contract_id to interact with billing and metering endpoints.

Next Steps

You have authenticated, verified API access, and registered your first consumer. From here you can:

Explore the API Reference to see every available endpoint, full request schemas, and error codes.
Learn about contract lifecycle — how to activate, amend, and terminate contracts.
Submit metering data for consumers and producers.
Register producers (renewable energy plant operators) using a similar flow under /v3/producers/.

Get Started

Core Concepts

Guides

Data & Analytics

Lumenaza API: Quickstart

Prerequisites

Steps

Next Steps

​Prerequisites

​Steps

​Next Steps

Prerequisites

Steps

Next Steps