Register an Electricity Consumer

This guide walks you through the full lifecycle of onboarding a new electricity consumer — from address validation and price preview all the way to confirming registration status and handling revocations. Base URL: https://api.lumenaza.de/ (use https://api.test.lumenaza.de/ for sandbox testing) All requests require an Authorization header:

Authorization: Bearer <token>

Validate the Delivery Address (Recommended)

Before submitting a registration, validate the delivery address and confirm the earliest possible delivery start date. This step is optional but strongly recommended to avoid rejected registrations.

Check Earliest Delivery Start

Use the preferred_delivery_start endpoint to determine the earliest date Lumenaza can begin delivery at the given address.

GET /v3/validation/preferred_delivery_start/?zip_code=10115&street=Unter+den+Linden&house_number=1

Example response:

{
  "preferred_delivery_start": "2024-03-01"
}

The preferred_delivery_start date must be at least 2 weeks in the future for most registrations. For E03 (provider switch) registrations only, dates up to 6 weeks in the past are accepted. Always check this value before submitting the registration to avoid validation errors.

Validate a Market Location ID

If you have a market location identifier (Marktlokations-ID), validate it before use:

GET /v3/validation/market_location/?market_location_identifier=52173487564

Example response:

{
  "is_valid": true,
  "market_location_identifier": "52173487564",
  "address": {
    "street": "Unter den Linden",
    "house_number": "1",
    "zip_code": "10115",
    "city": "Berlin"
  }
}

Preview Pricing (Optional)

Before registering, you can fetch a price estimate for a specific tariff, postal code, and annual consumption. This helps surface pricing to the end customer before they commit.

GET /v3/offer_calculator/?tariff_name=YOUR_TARIFF&zip_code=10115&consumption=3500

Query Parameter	Type	Description
`tariff_name`	string	The tariff identifier configured in your account
`zip_code`	string	Five-digit German postal code
`consumption`	integer	Estimated annual consumption in kWh

Example response:

{
  "offer_item_price_results": [
    {
      "name": "Base price",
      "price_net": 8.90,
      "price_gross": 10.59,
      "unit": "EUR/month"
    },
    {
      "name": "Energy price",
      "price_net": 0.28,
      "price_gross": 0.33,
      "unit": "EUR/kWh"
    }
  ],
  "total_price_results": {
    "monthly_net": 86.23,
    "monthly_gross": 102.61,
    "annual_net": 1034.76,
    "annual_gross": 1231.36
  }
}

Use offer_item_price_results to display a line-item breakdown and total_price_results for a summary view.

Submit the consumer’s details to create a new contract in Lumenaza.

POST /v3/consumers/create/
Content-Type: application/json
Authorization: Bearer <token>

Key Parameters

string

required

Consumer’s first name.

string

required

Consumer’s last name.

string

required

Consumer’s email address. Used for contract communications.

string

required

Consumer’s salutation. Must be one of: Frau, Herr, Eheleute, Divers.

boolean

required

Set to true for business customers, false for private consumers.

string

required

Street name of the delivery address.

string

required

House number of the delivery address. Maximum 5 characters.

string

required

Five-digit postal code of the delivery address. Maximum 5 characters.

string

required

City of the delivery address.

integer

required

Estimated annual electricity consumption in kWh.

string

required

Reason for the subscription. One of:

E01 — New move-in
E02 — New connection
E03 — Provider switch

string

required

Tariff identifier to assign to this consumer.

string

Required when subscription_reason is E03. The BDEW code or name of the consumer’s current electricity provider.

string

Your internal customer identifier. Maximum 32 characters. Must be unique across all consumers in your account.

string

Your internal contract identifier. Maximum 64 characters.

string

Payment method for the contract, e.g. sepa_direct_debit or bank_transfer.

string

Consumer’s IBAN for SEPA direct debit payments.

string

BIC/SWIFT code associated with bank_data_iban.

string

Date of the SEPA mandate signature (ISO 8601 format: YYYY-MM-DD).

saas_customer_id must be unique within your Lumenaza account. If you submit a duplicate value, the API will return a validation error. Use a stable internal ID (e.g. your CRM’s customer UUID) rather than a mutable identifier.

Example Request Body

{
  "first_name": "Maria",
  "last_name": "Müller",
  "email": "maria.mueller@example.com",
  "salutation": "Frau",
  "is_business": false,
  "deliv_address_street": "Unter den Linden",
  "deliv_address_house_number": "1",
  "deliv_address_zipcode": "10115",
  "deliv_address_city": "Berlin",
  "annual_consumption": 3500,
  "subscription_reason": "E03",
  "previous_provider": "Vattenfall",
  "tariff_type": "green_basic_2024",
  "saas_customer_id": "crm-customer-00123",
  "saas_contract_id": "crm-contract-00456",
  "payment_method": "sepa_direct_debit",
  "bank_data_iban": "DE89370400440532013000",
  "bank_data_bic": "COBADEFFXXX",
  "sepa_date": "2024-01-15"
}

Success Response

HTTP 201 Created

{
  "consumer_id": "usr_4f9a23bc1e",
  "contract_id": "ctr_7d81e04c2a"
}

Store both consumer_id and contract_id — they are required for all subsequent operations on this consumer.

Confirm Registration Status

After registration, poll the contract endpoint to track the registration lifecycle.

GET /v3/consumers/{userID}/contracts/{contractID}/
Authorization: Bearer <token>

Replace {userID} with the consumer_id and {contractID} with the contract_id returned in Step 3.Example response:

{
  "contract_id": "ctr_7d81e04c2a",
  "consumer_id": "usr_4f9a23bc1e",
  "reg_status": "open_join",
  "tariff_type": "green_basic_2024",
  "deliv_address_street": "Unter den Linden",
  "deliv_address_house_number": "1",
  "deliv_address_zipcode": "10115",
  "deliv_address_city": "Berlin",
  "annual_consumption": 3500,
  "delivery_start": "2024-03-01",
  "created_at": "2024-01-15T10:32:00Z"
}

`reg_status` Value	Meaning
`open_join`	Registration submitted, awaiting grid operator processing
`closed_join`	Grid operator confirmed; delivery is active
`rejected`	Registration rejected by the grid operator
`revoked`	Contract was revoked during the open window

Typically, open_join transitions to closed_join within a few business days once the grid operator processes the switch.

Handle the Revocation Window

While a contract is in open_join status, it can be revoked within 14 days of the registration date. This is the standard cancellation window before delivery is confirmed.

POST /v3/consumers/{userID}/contracts/{contractID}/revoke/
Authorization: Bearer <token>

Example response:

{
  "contract_id": "ctr_7d81e04c2a",
  "consumer_id": "usr_4f9a23bc1e",
  "reg_status": "revoked",
  "revoked_at": "2024-01-20T14:05:00Z"
}

After a successful revocation, the reg_status transitions to revoked and the contract is closed. No delivery will take place.

Revocation is only possible while the contract is in open_join status. Once the contract transitions to closed_join, it cannot be revoked through this endpoint — contact Lumenaza support for assistance with active contracts.

Next Steps

Retrieve invoices: Use GET /v3/consumers/{userID}/invoices/ to fetch billing documents.
Update consumer data: Use PATCH /v3/consumers/{userID}/ to update contact or address information.
Register a producer: If your customer also generates electricity, see Register a Renewable Energy Producer.

Get Started

Core Concepts

Guides

Data & Analytics

Register an Electricity Consumer

Check Earliest Delivery Start

Validate a Market Location ID

Key Parameters

Example Request Body

Success Response

Next Steps

​Check Earliest Delivery Start

​Validate a Market Location ID

​Key Parameters

​Example Request Body

​Success Response

​Next Steps

Check Earliest Delivery Start

Validate a Market Location ID

Key Parameters

Example Request Body

Success Response

Next Steps