Customer Migrations Guide: Account Import

This page documents the data import APIs for account creation.

Validate account
Create account
Get account import status

Validate account

Use this endpoint to validate account data before creating an account.

POST https://api.norlys-kraken.energy/v2/data-import/accounts/validate/

The following responses may be returned from the API.

Status code Description

Status code	Description
`200 - OK`	If the payload is valid, a 200 OK response will be returned with the empty payload as its body. Example: `{}`
`400 - Bad Request`	If there are validation errors a 400 Bad Request response will be returned detailing the errors. To resolve these errors, refer to the field definitions and validation rules. Example: `{ "detail": "Could not validate account data.", "code": "account_failed_validation", "errors": [ { "detail": "abcde is not a valid phone number", "code": "invalid_phone_number", "attr": "customers.0.landline" } ] }`

200 - OK

If the payload is valid, a 200 OK response will be returned with the empty payload as its body.

Example:

{}

400 - Bad Request

If there are validation errors a 400 Bad Request response will be returned detailing the errors. To resolve these errors, refer to the field definitions and validation rules.

Example:

{
    "detail": "Could not validate account data.",
    "code": "account_failed_validation",
    "errors": [
        {
            "detail": "abcde is not a valid phone number",
            "code": "invalid_phone_number",
            "attr": "customers.0.landline"
        }
    ]
}

{
    "payload": {
        "import_supplier": "NORLYS",
        "external_account_number": "EXTERNAL-1234",
        "unknown_occupier": false,
        "customers": [
            {
                "given_name": "Homer",
                "family_name": "Simpson",
                "email": "homer@simpson.com",
                "mobile": "+4587654321",
                "landline": "+4533123456",
                "date_of_birth": "1959-01-01",
                "title": "Mr",
                "salutation": "Hi",
                "customer_preferences": {
                    "opted_into_sms": true,
                    "opted_into_recommended": true,
                    "opted_into_updates": true,
                    "opted_into_third_parties": true,
                    "opted_into_offers": true,
                    "is_user_psr_consent_obtained": true
                }
            }
        ],
        "billing_email": "homer@simpson.com",
        "billing_name": "The Simpsons",
        "billing_sub_name": "Fourth of their name",
        "billing_customer_reference": "Electricity Supplier",
        "billing_address": {
            "name": "Jane Smith",
            "organization": "Denmark Builders Ltd",
            "street_address": "The Terrace 1",
            "locality": "The Terrace",
            "postal_code": "9000",
            "country": "DK",
            "delivery_point_identifier": "12345678",
            "structured_street_address": null
        },
        "account_billing_options": {
            "period_length": "MONTHLY",
            "period_start_day": 20,
            "period_start_month": null,
            "use_industry_billing": false
        },
        "account_type": "DOMESTIC",
        "date_of_sale": "1989-12-17",
        "sales_channel": "DIRECT",
        "sales_subchannel": "Disney",
        "communication_preference": "ONLINE",
        "document_accessibility": "LARGE_PRINT",
        "notes": [
            {
                "body": "Some note",
                "created_at": "2024-02-10T12:34:56Z",
                "is_pinned": true,
                "unpin_at": "2024-02-11T12:34:56Z"
            }
        ],
        "ledgers": [
            {
                "ledger_code": "DENMARK_ELECTRICITY_LEDGER",
                "last_statement_balance": 20.0,
                "last_statement_closing_date": "2023-07-31",
                "ledger_balance": 20.0,
                "current_statement_transactions": [],
                "historical_statement_transactions": [
                    {
                        "transaction_id": "1",
                        "transaction_date": "2023-06-01",
                        "amount": 10.0,
                        "type": "PAYMENT",
                        "reason": "ACCOUNT_CHARGE_PAYMENT",
                        "payment_type": "CREDIT_CARD"
                    },
                    {
                        "transaction_id": "2",
                        "transaction_date": "2023-07-01",
                        "amount": 10.0,
                        "type": "PAYMENT",
                        "reason": "ACCOUNT_CHARGE_PAYMENT",
                        "payment_type": "DEBIT_CARD"
                    }
                ]
            }
        ],
        "transfer_balance": 20.0,
        "statements": [
            {
                "bill_period_from_date": "2023-06-01",
                "bill_period_to_date": "2023-07-01",
                "statement_path": "EXTERNAL-1234/2023-06-01-to-2023-07-01-electricity.pdf",
                "statement_id": "1"
            }
        ],
        "metadata": [
            {
                "key": "metadata_key",
                "value": {
                    "some_data": "some_value"
                }
            }
        ],
        "operations_team_name": "Team A",
        "supply_addresses": [
            {
                "primary_place_of_residence_since": "2023-04-01",
                "customer_at_supply_address_from_date": "2023-04-01",
                "supply_postcode": "9000",
                "supply_address1": "1 Fleet Street"
            }
        ]
    }
}

Create account

Use this endpoint to process account data into an account in Kraken.

Before an account is created, it is validated according to the same rules as the validate endpoint above. This is an extra safety check to make sure nothing has changed between creating the data and submitting it for account creation in Kraken.

POST https://api.norlys-kraken.energy/v2/data-import/accounts/

The following responses may be returned from the API.

Status code Description

Status code	Description
`201 - Created`	If the payload is valid and an account creation has been scheduled, a `201 Created` response will be returned with the empty payload as its body.
`400 - Bad Request`	If there are validation errors, a `400 Bad Request` response will be returned detailing the errors. To resolve these errors, refer to the field definitions and validation rules. If an account has already been imported, a `400 Bad Request` response will be returned with `account_id` representing existing Kraken account number. `{ "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" }`

201 - Created

If the payload is valid and an account creation has been scheduled, a 201 Created response will be returned with the empty payload as its body.

400 - Bad Request

If there are validation errors, a 400 Bad Request response will be returned detailing the errors. To resolve these errors, refer to the field definitions and validation rules.

If an account has already been imported, a 400 Bad Request response will be returned with account_id representing existing Kraken account number.

{
    "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"
}

{
    "payload": {
        "import_supplier": "NORLYS",
        "external_account_number": "EXTERNAL-1234",
        "unknown_occupier": false,
        "customers": [
            {
                "given_name": "Homer",
                "family_name": "Simpson",
                "email": "homer@simpson.com",
                "mobile": "+4587654321",
                "landline": "+4533123456",
                "date_of_birth": "1959-01-01",
                "title": "Mr",
                "salutation": "Hi",
                "customer_preferences": {
                    "opted_into_sms": true,
                    "opted_into_recommended": true,
                    "opted_into_updates": true,
                    "opted_into_third_parties": true,
                    "opted_into_offers": true,
                    "is_user_psr_consent_obtained": true
                }
            }
        ],
        "billing_email": "homer@simpson.com",
        "billing_name": "The Simpsons",
        "billing_sub_name": "Fourth of their name",
        "billing_customer_reference": "Electricity Supplier",
        "billing_address": {
            "name": "Jane Smith",
            "organization": "Denmark Builders Ltd",
            "street_address": "The Terrace 1",
            "locality": "The Terrace",
            "postal_code": "9000",
            "country": "DK",
            "delivery_point_identifier": "12345678",
            "structured_street_address": null
        },
        "account_billing_options": {
            "period_length": "MONTHLY",
            "period_start_day": 20,
            "period_start_month": null,
            "use_industry_billing": false
        },
        "account_type": "DOMESTIC",
        "date_of_sale": "1989-12-17",
        "sales_channel": "DIRECT",
        "sales_subchannel": "Disney",
        "communication_preference": "ONLINE",
        "document_accessibility": "LARGE_PRINT",
        "notes": [
            {
                "body": "Some note",
                "created_at": "2024-02-10T12:34:56Z",
                "is_pinned": true,
                "unpin_at": "2024-02-11T12:34:56Z"
            }
        ],
        "ledgers": [
            {
                "ledger_code": "DENMARK_ELECTRICITY_LEDGER",
                "last_statement_balance": 20.0,
                "last_statement_closing_date": "2023-07-31",
                "ledger_balance": 20.0,
                "current_statement_transactions": [],
                "historical_statement_transactions": [
                    {
                        "transaction_id": "1",
                        "transaction_date": "2023-06-01",
                        "amount": 10.0,
                        "type": "PAYMENT",
                        "reason": "ACCOUNT_CHARGE_PAYMENT",
                        "payment_type": "CREDIT_CARD"
                    },
                    {
                        "transaction_id": "2",
                        "transaction_date": "2023-07-01",
                        "amount": 10.0,
                        "type": "PAYMENT",
                        "reason": "ACCOUNT_CHARGE_PAYMENT",
                        "payment_type": "DEBIT_CARD"
                    }
                ]
            }
        ],
        "transfer_balance": 20.0,
        "statements": [
            {
                "bill_period_from_date": "2023-06-01",
                "bill_period_to_date": "2023-07-01",
                "statement_path": "EXTERNAL-1234/2023-06-01-to-2023-07-01-electricity.pdf",
                "statement_id": "1"
            }
        ],
        "metadata": [
            {
                "key": "metadata_key",
                "value": {
                    "some_data": "some_value"
                }
            }
        ],
        "operations_team_name": "Team A",
        "supply_addresses": [
            {
                "primary_place_of_residence_since": "2023-04-01",
                "customer_at_supply_address_from_date": "2023-04-01",
                "supply_postcode": "9000",
                "supply_address1": "1 Fleet Street"
            }
        ]
    }
}

Get account import status

Use this endpoint to retrieve the current status of an account import.

GET https://api.norlys-kraken.energy/v2/data-import/accounts/<import-supplier-code>/<external-identifier>/

The following responses may be returned from the API.

Status code Description

Status code	Description
`200 - OK`	If the account import process exists, a `200 OK` response will be returned, detailing the `status`. For example when there is no error in processing: `{ "status": "DRY_RUN_SUCCEEDED \| IN_PROGRESS \| PENDING \| CANCELLED \| PROCESSED", "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 `404 Not Found` response will be returned. `{ "detail": "The requested resource was not found.", "code": "not_found" }`

200 - OK

If the account import process exists, a 200 OK response will be returned, detailing the status.

For example when there is no error in processing:

{
    "status": "DRY_RUN_SUCCEEDED | IN_PROGRESS | PENDING | CANCELLED | PROCESSED",
    "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 404 Not Found response will be returned.

{
    "detail": "The requested resource was not found.",
    "code": "not_found"
}

Norlys

Customer Migrations Guide: Account Import

API Endpoints

Validate account

Overview

Schema

Responses

Payloads

Example payload

Create account

Overview

Schema

Responses

Payloads

Example payload

Get account import status

Overview

Responses