Customer Migrations Guide: Account Import
This page documents the data import APIs for account creation.
API Endpoints
Overview
Use this endpoint to validate account data before creating an account.
Schema
Loading...
POST https://api.essentialenergy-kraken.systems/v2/data-import/accounts/validate/
Responses
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the payload is valid, a |
400 - Bad Request |
If there are validation errors a {
"customers": {
"0": {
"landline": [
"abcde is not a valid phone number"
]
}
}
} |
Payloads
Example water payload
{
"payload": {
"import_supplier": "TEST_SUPPLIER",
"external_account_number": "E-1",
"customers": [
{
"given_name": "Homer",
"family_name": "Simpson",
"email": "homer@simpson.com",
"mobile": "0488008221",
"landline": "+61280082213",
"date_of_birth": "1959-01-01",
"title": "Mr"
}
],
"billing_name": "The Simpsons",
"billing_sub_name": "Fourth of their name",
"billing_customer_reference": "Water Supply",
"billing_attention_of": "The Bursar",
"billing_address": {
"administrative_area": "NSW",
"country": "AU",
"locality": "ANY",
"postal_code": "3070",
"delivery_point_identifier": "51234568",
"structured_street_address": {
"street_name": "That Street"
}
},
"account_billing_options": {},
"account_type": "DOMESTIC",
"sales_channel": "DIRECT",
"sales_subchannel": "Disney",
"date_of_sale": "1989-12-17",
"supply_addresses": [
{
"supply_address": {
"administrative_area": "NSW",
"country": "AU",
"locality": "ANY",
"postal_code": "3070",
"delivery_point_identifier": "51234568",
"structured_street_address": {
"house_number_1": "11",
"building_or_property_name": "",
"flat_or_unit_number": "1",
"flat_or_unit_type": "U",
"street_name": "Queen's",
"street_type": "RD"
}
},
"is_landlord": true,
"property_administrators": [
{
"given_name": "Mick",
"family_name": "Jagger",
"email": "mick.jager@rollingstones.com",
"mobile": "0488008221",
"landline": "0212345678"
}
],
"customer_at_supply_address_from_date": "2019-04-01",
"property_external_reference": "1126421",
"supply_points": [
{
"identifier": "WATER:1234567890",
"supply_type": "TREATED",
"supply_start_date": "2019-04-01",
"agreements": [
{
"tariff_code": "TEST_WATER",
"effective_from": "2024-10-01"
}
],
"last_billed_to_date": "2025-03-01",
"restriction": false,
"backflow_device": false,
"meter_points": [
{
"location": "SHED",
"latitude": "33.8568",
"longitude": "151.2153",
"category": "NORMAL",
"access_information": "Keypad entry",
"address_identifier": "a1023924",
"route_id": "b728",
"reading_months": [
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12
],
"non_return_to_sewage_allowance": "6.000",
"meters": [
{
"serial_number": "2LU07HYB",
"installed_on": "2025-01-01",
"removed_on": "2025-02-01",
"number_of_digits": 5,
"size": 20,
"status": "REMOVED",
"make": "Acme Inc.",
"model": "Aqua1000",
"capability_type": "MANUAL",
"readings": [
{
"reading_date": "2025-01-01",
"reading_value": "1.000",
"reading_type": "METER_READER",
"reading_reason": "INITIAL",
"leakage_allowance": null,
"is_tripped": false
}
],
"tamper_proofing": "SEAL"
}
],
"services": [
{
"name": "TREATED_WATER",
"active_from": "2025-03-01",
"active_to": "2025-03-02"
}
]
}
]
}
]
}
],
"ledgers": [
{
"ledger_code": "WATER_LEDGER",
"last_statement_closing_date": "2025-03-01",
"last_statement_issue_date": "2025-03-02",
"last_statement_balance": -1.21616,
"ledger_balance": -2.43232,
"current_statement_transactions": [
{
"transaction_id": "test_4",
"transaction_date": "2025-03-18",
"amount": 11.21616,
"type": "SUPPLY_CHARGE",
"product_code": "TEST_WATER",
"line_items": [
{
"rate_band": "TEST_WATER_STANDING",
"start_date": "2025-03-04",
"end_date": "2025-03-13",
"number_of_units": 10,
"net_amount": 11.21616
}
]
},
{
"transaction_id": "test_3",
"transaction_date": "2025-03-15",
"amount": 10,
"type": "CREDIT",
"display_note": "Balance transfer",
"reason": "BALANCE_TRANSFER"
}
],
"historical_statement_transactions": [
{
"transaction_id": "test_2",
"transaction_date": "2025-02-01",
"amount": 11.21616,
"type": "SUPPLY_CHARGE",
"product_code": "TEST_WATER",
"line_items": [
{
"rate_band": "TEST_WATER_STANDING",
"start_date": "2025-01-22",
"end_date": "2025-01-31",
"number_of_units": 10,
"net_amount": 11.21616
}
]
},
{
"transaction_id": "test_1",
"transaction_date": "2025-01-30",
"amount": 10,
"type": "PAYMENT",
"reason": "ACCOUNT_CHARGE_PAYMENT"
}
]
}
],
"payment_instructions": [],
"payment_schedules": [
{
"amount": 20.0,
"day_of_month": 10,
"frequency": "MONTHLY",
"means": "MANUAL",
"start_date": "2018-01-01",
"trigger": "REGULAR",
"ledger_code": "WATER_LEDGER"
}
],
"payment_promises": [
{
"ledger_code": "WATER_LEDGER",
"amount": 20.0,
"payment_date": "2025-03-25"
}
],
"debts": [
{
"aged_debt": [
{
"debt_amount": 5.0,
"due_date": "2025-01-01"
}
]
}
],
"notes": [
{
"created_at": "2018-10-10T10:20:00Z",
"body": "This is a note",
"document_paths": [
{
"document_path": "/notes/1234/attachment.jpg"
}
]
},
{
"created_at": "2018-10-10T10:20:00Z",
"body": "This is a pinned note",
"document_paths": [
{
"document_path": "/notes/1234/attachment.jpg"
}
],
"is_pinned": true
}
],
"events": [],
"transfer_balance": -2.43232,
"unknown_occupier": false
}
}Overview
Use this endpoint to process account data into an account in Kraken.
Schema
Loading...
POST https://api.essentialenergy-kraken.systems/v2/data-import/accounts/
Responses
The following responses may be returned from the API.
| Status code | Description |
|---|---|
201 - Created |
If the payload is valid and an account creation has been scheduled, a |
400 - Bad Request |
If there are validation errors, a
If an account has already been imported, a {
"non_field_errors": {
"detail": "The account import process with the account number 1234567890 has already been imported.",
"code": "account_import_process_already_imported"
},
"account_id": "A-12345678"
} |
Payloads
Example water payload
{
"payload": {
"import_supplier": "TEST_SUPPLIER",
"external_account_number": "E-1",
"customers": [
{
"given_name": "Homer",
"family_name": "Simpson",
"email": "homer@simpson.com",
"mobile": "0488008221",
"landline": "+61280082213",
"date_of_birth": "1959-01-01",
"title": "Mr"
}
],
"billing_name": "The Simpsons",
"billing_sub_name": "Fourth of their name",
"billing_customer_reference": "Water Supply",
"billing_attention_of": "The Bursar",
"billing_address": {
"administrative_area": "NSW",
"country": "AU",
"locality": "ANY",
"postal_code": "3070",
"delivery_point_identifier": "51234568",
"structured_street_address": {
"street_name": "That Street"
}
},
"account_billing_options": {},
"account_type": "DOMESTIC",
"sales_channel": "DIRECT",
"sales_subchannel": "Disney",
"date_of_sale": "1989-12-17",
"supply_addresses": [
{
"supply_address": {
"administrative_area": "NSW",
"country": "AU",
"locality": "ANY",
"postal_code": "3070",
"delivery_point_identifier": "51234568",
"structured_street_address": {
"house_number_1": "11",
"building_or_property_name": "",
"flat_or_unit_number": "1",
"flat_or_unit_type": "U",
"street_name": "Queen's",
"street_type": "RD"
}
},
"is_landlord": true,
"property_administrators": [
{
"given_name": "Mick",
"family_name": "Jagger",
"email": "mick.jager@rollingstones.com",
"mobile": "0488008221",
"landline": "0212345678"
}
],
"customer_at_supply_address_from_date": "2019-04-01",
"property_external_reference": "1126421",
"supply_points": [
{
"identifier": "WATER:1234567890",
"supply_type": "TREATED",
"supply_start_date": "2019-04-01",
"agreements": [
{
"tariff_code": "TEST_WATER",
"effective_from": "2024-10-01"
}
],
"last_billed_to_date": "2025-03-01",
"restriction": false,
"backflow_device": false,
"meter_points": [
{
"location": "SHED",
"latitude": "33.8568",
"longitude": "151.2153",
"category": "NORMAL",
"access_information": "Keypad entry",
"address_identifier": "a1023924",
"route_id": "b728",
"reading_months": [
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12
],
"non_return_to_sewage_allowance": "6.000",
"meters": [
{
"serial_number": "2LU07HYB",
"installed_on": "2025-01-01",
"removed_on": "2025-02-01",
"number_of_digits": 5,
"size": 20,
"status": "REMOVED",
"make": "Acme Inc.",
"model": "Aqua1000",
"capability_type": "MANUAL",
"readings": [
{
"reading_date": "2025-01-01",
"reading_value": "1.000",
"reading_type": "METER_READER",
"reading_reason": "INITIAL",
"leakage_allowance": null,
"is_tripped": false
}
],
"tamper_proofing": "SEAL"
}
],
"services": [
{
"name": "TREATED_WATER",
"active_from": "2025-03-01",
"active_to": "2025-03-02"
}
]
}
]
}
]
}
],
"ledgers": [
{
"ledger_code": "WATER_LEDGER",
"last_statement_closing_date": "2025-03-01",
"last_statement_issue_date": "2025-03-02",
"last_statement_balance": -1.21616,
"ledger_balance": -2.43232,
"current_statement_transactions": [
{
"transaction_id": "test_4",
"transaction_date": "2025-03-18",
"amount": 11.21616,
"type": "SUPPLY_CHARGE",
"product_code": "TEST_WATER",
"line_items": [
{
"rate_band": "TEST_WATER_STANDING",
"start_date": "2025-03-04",
"end_date": "2025-03-13",
"number_of_units": 10,
"net_amount": 11.21616
}
]
},
{
"transaction_id": "test_3",
"transaction_date": "2025-03-15",
"amount": 10,
"type": "CREDIT",
"display_note": "Balance transfer",
"reason": "BALANCE_TRANSFER"
}
],
"historical_statement_transactions": [
{
"transaction_id": "test_2",
"transaction_date": "2025-02-01",
"amount": 11.21616,
"type": "SUPPLY_CHARGE",
"product_code": "TEST_WATER",
"line_items": [
{
"rate_band": "TEST_WATER_STANDING",
"start_date": "2025-01-22",
"end_date": "2025-01-31",
"number_of_units": 10,
"net_amount": 11.21616
}
]
},
{
"transaction_id": "test_1",
"transaction_date": "2025-01-30",
"amount": 10,
"type": "PAYMENT",
"reason": "ACCOUNT_CHARGE_PAYMENT"
}
]
}
],
"payment_instructions": [],
"payment_schedules": [
{
"amount": 20.0,
"day_of_month": 10,
"frequency": "MONTHLY",
"means": "MANUAL",
"start_date": "2018-01-01",
"trigger": "REGULAR",
"ledger_code": "WATER_LEDGER"
}
],
"payment_promises": [
{
"ledger_code": "WATER_LEDGER",
"amount": 20.0,
"payment_date": "2025-03-25"
}
],
"debts": [
{
"aged_debt": [
{
"debt_amount": 5.0,
"due_date": "2025-01-01"
}
]
}
],
"notes": [
{
"created_at": "2018-10-10T10:20:00Z",
"body": "This is a note",
"document_paths": [
{
"document_path": "/notes/1234/attachment.jpg"
}
]
},
{
"created_at": "2018-10-10T10:20:00Z",
"body": "This is a pinned note",
"document_paths": [
{
"document_path": "/notes/1234/attachment.jpg"
}
],
"is_pinned": true
}
],
"events": [],
"transfer_balance": -2.43232,
"unknown_occupier": false
}
}Overview
Use this endpoint to retrieve the current status of an account import.
GET https://api.essentialenergy-kraken.systems/v2/data-import/accounts/<import-supplier-code>/<external-identifier>/
Responses
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the account import process exists, a For example when there is no error in processing: {
"status": "DRY_RUN_SUCCEEDED | PROCESSED | PENDING | IN_PROGRESS | CANCELLED",
"kraken_identifier": null,
"created_at": "2025-10-07T09:00:21.179194+02:00",
"modified_at": "2025-10-07T09:06:38.078396+02:00",
"latest_error": null
}For example when the import process is processed we have an internal kraken id: {
"status": "PROCESSED",
"kraken_identifier": "INTERNAL-KRAKEN-IDENTIFIER",
"created_at": "2025-10-07T09:00:21.179194+02:00",
"modified_at": "2025-10-07T09:06:38.078396+02:00",
"latest_error": null
}For example when there is an error in processing: {
"status": "ERRORED | DRY_RUN_ERRORED",
"kraken_identifier": null,
"created_at": "2025-10-07T09:00:21.179194+02:00",
"modified_at": "2025-10-07T09:06:38.078396+02:00",
"latest_error": {
"code": "some_error_code",
"detail": "A detailed error message",
"domain": "account_import"
}
} |
404 - Not Found |
If the account import process does not exist, a {
"detail": "The requested resource was not found.",
"code": "not_found"
} |