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

# Update Customer Master Data via Change Requests

> Submit and track process-based master data change requests for customer addresses, bank details, and contract attributes using the Lumenaza v3 API.

# 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.

<Note>
  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.
</Note>

**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**

```bash theme={null}
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**

```json theme={null}
{
  "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:

```bash theme={null}
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**

```json theme={null}
{
  "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/
```

```bash theme={null}
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.

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

**Example response**

```json theme={null}
[
  {
    "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.

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

**Example response**

```json theme={null}
{
  "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.


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