Update Customer Master Data via Change Requests

Master data changes in Lumenaza are handled through a process-based system rather than direct field updates. When you submit a change — such as a new billing address or bank account — Lumenaza initiates the corresponding market communication processes with grid operators and other stakeholders. This ensures regulatory compliance and an accurate audit trail for every data change.

Changes submitted through this API go through a multi-step internal process. Depending on the grid operator’s response time and market communication workflows, it may take some time before a change is fully reflected on a contract. You can track the status of any change using the tracking endpoints described below.

Base URLs

Environment	URL
Production	`https://api.lumenaza.de/`
Test	`https://api.test.lumenaza.de/`

All requests require an Authorization: Bearer <token> header.

Available Change Endpoints

1. Billing Address

Update the billing address for a customer contract.

POST /v3/master_data/changes/bill_address/

Request fields

Field	Type	Required	Description
`customer_id`	string	✅	The customer (consumer or producer) identifier
`contract_id`	string	✅	The contract to update
`is_consumer`	boolean	✅	`true` for consumers, `false` for producers
`bill_address_street`	string	✅	Street name of the new billing address
`bill_address_house_number`	string	✅	House number
`bill_address_zipcode`	string	✅	Postal/ZIP code
`bill_address_city`	string	✅	City name

Example request

curl -X POST "https://api.lumenaza.de/v3/master_data/changes/bill_address/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_001",
    "contract_id": "contract_abc123",
    "is_consumer": true,
    "bill_address_street": "Musterstraße",
    "bill_address_house_number": "42",
    "bill_address_zipcode": "10115",
    "bill_address_city": "Berlin"
  }'

Response

{
  "change_id": "chg_a1b2c3"
}

2. Delivery Address

Update the physical delivery (metering) address for a contract.

POST /v3/master_data/changes/delivery_address/

The request follows the same pattern as billing address, but uses deliv_address_* fields:

curl -X POST "https://api.lumenaza.de/v3/master_data/changes/delivery_address/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_001",
    "contract_id": "contract_abc123",
    "is_consumer": true,
    "deliv_address_street": "Neue Straße",
    "deliv_address_house_number": "7",
    "deliv_address_zipcode": "20095",
    "deliv_address_city": "Hamburg"
  }'

Response

{
  "change_id": "chg_d4e5f6"
}

3. Bank Data / Payment Method

Update a customer’s IBAN, BIC, payment method, or SEPA mandate date.

POST /v3/master_data/changes/bank_data/

curl -X POST "https://api.lumenaza.de/v3/master_data/changes/bank_data/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_001",
    "contract_id": "contract_abc123",
    "is_consumer": true,
    "payment_method": "sepa_direct_debit",
    "bank_data_iban": "DE89370400440532013000",
    "bank_data_bic": "COBADEFFXXX",
    "sepa_date": "2024-05-01"
  }'

Key fields

Field	Description
`payment_method`	Payment method to apply (e.g., `sepa_direct_debit`, `bank_transfer`)
`bank_data_iban`	New IBAN
`bank_data_bic`	BIC/SWIFT code of the bank
`sepa_date`	Date from which the SEPA mandate becomes valid

Track Change Status

List Active Changes

Retrieve all in-progress change processes.

curl -X GET "https://api.lumenaza.de/v3/master_data/changes/" \
  -H "Authorization: Bearer <token>"

Example response

[
  {
    "change_id": "chg_a1b2c3",
    "type": "bill_address",
    "status": "in_progress",
    "created_at": "2024-04-10T09:00:00Z"
  },
  {
    "change_id": "chg_d4e5f6",
    "type": "delivery_address",
    "status": "completed",
    "created_at": "2024-04-08T14:30:00Z"
  }
]

Get Change Details

Fetch the full details of a specific change, including the old and new values.

curl -X GET "https://api.lumenaza.de/v3/master_data/changes/{id}/" \
  -H "Authorization: Bearer <token>"

Example response

{
  "change_id": "chg_a1b2c3",
  "type": "bill_address",
  "status": "in_progress",
  "contract_id": "contract_abc123",
  "customer_id": "cust_001",
  "old_values": {
    "bill_address_street": "Altstraße",
    "bill_address_house_number": "10",
    "bill_address_zipcode": "10115",
    "bill_address_city": "Berlin"
  },
  "new_values": {
    "bill_address_street": "Musterstraße",
    "bill_address_house_number": "42",
    "bill_address_zipcode": "10115",
    "bill_address_city": "Berlin"
  },
  "created_at": "2024-04-10T09:00:00Z",
  "updated_at": "2024-04-10T11:15:00Z"
}

The old_values and new_values fields let you verify exactly what changed and when, making it straightforward to audit or roll back data if needed.

Get Started

Core Concepts

Guides

Data & Analytics

Update Customer Master Data via Change Requests

Update Customer Master Data via Change Requests

Available Change Endpoints

1. Billing Address

2. Delivery Address

3. Bank Data / Payment Method

Track Change Status

List Active Changes

Get Change Details

​Update Customer Master Data via Change Requests

​Available Change Endpoints

​1. Billing Address

​2. Delivery Address

​3. Bank Data / Payment Method

​Track Change Status

​List Active Changes

​Get Change Details

Update Customer Master Data via Change Requests

Available Change Endpoints

1. Billing Address

2. Delivery Address

3. Bank Data / Payment Method

Track Change Status

List Active Changes

Get Change Details