Customer Migrations Guide: Account Import

This page documents the data import APIs for account creation.

API Endpoints

Validate account

Overview

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

Schema

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

Responses

The following responses may be returned from the API.

Status codeDescription
200 - OK

If the payload is valid, a 200 OK 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. Response example:

{ "customers": { "0": { "landline": [ "abcde is not a valid phone number" ] } } }

Payloads

Example payload
{ "import_supplier": "TENTACLE_ENERGY", "external_account_number": "EXTERNAL-1234", "unknown_occupier": false, "customers": [ { "given_name": "Bob", "family_name": "Jabłoński", "email": "bob@jablonski.com", "mobile": "07123456789", "landline": "02072343456", "date_of_birth": "1989-01-11", "title": "Mr", "salutation": "Hi", "psr": [ { "elec_industry_code": "01", "effective_from": "2012-01-01" }, { "gas_industry_code": "01", "effective_from": "2012-01-01" } ], "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_name": "Robert Jabłoński", "billing_address1": "123 Fake Street", "billing_address2": "", "billing_address3": "", "billing_address4": "", "billing_address5": "", "billing_postcode": "W1F 9DE", "account_type": "DOMESTIC", "sales_channel": "DIRECT", "sales_subchannel": "", "supply_addresses": [ { "supply_address1": "123 Fake Street", "supply_address2": "", "supply_address3": "", "supply_address4": "", "supply_address5": "", "supply_postcode": "W1F 9DE", "is_landlord": false, "customer_at_supply_address_from_date": "2019-01-01", "meter_points": [ { "identifier": "1200060176720", "supply_type": "ELECTRICITY", "agreements": [ { "tariff_code": "ELEC-1234-J", "effective_from": "2019-08-01" } ], "mpid": "TENT", "supply_start_date": "2019-01-01", "profile_class": 1, "ssc": "0393", "meters": [ { "meter_serial_number": "Z16N389556", "installed_on": "2001-01-01", "registers": [ { "register_id": "1", "tpr": "00001", "number_of_digits": 5 }, { "register_id": "X", "tpr": "00043", "number_of_digits": 5, "is_settlement": false } ], "transfer_readings": [ { "register_id": "1", "reading_date": "2019-08-01", "reading_value": "1000.00", "reading_type": "CUSTOMER" } ], "reading_history": [ { "register_id": "1", "reading_date": "2019-06-20", "reading_value": "980.00", "reading_type": "CUSTOMER", "billed": true }, { "register_id": "1", "reading_date": "2019-05-20", "reading_value": "960.00", "reading_type": "ROUTINE", "billed": true } ] } ], "et_in_progress": false, "dr_in_progress": false, "smart_refusal_interest": { "type": "NOT_INTERESTED", "date": "2020-04-01", "refusal_reason": "DO_NOT_OWN_HOME", "source": "EMAIL" }, "eac_history": [ { "effective_from": "2019-10-01", "tpr": "00001", "consumption": "1500", "source": "D0019" }, { "effective_from": "2019-09-01", "tpr": "00001", "consumption": "1300", "source": "D0019" } ] }, { "identifier": "9353824109", "supply_type": "GAS", "agreements": [ { "tariff_code": "GAS-1234-J", "effective_from": "2019-08-01" } ], "mpid": "TEN", "shipper_mpid": "TCL", "supply_start_date": "2019-04-10", "meters": [ { "meter_serial_number": "54BV", "installed_on": "2002-01-01", "gas_number_of_digits": 5, "smart_type": "SMETS1", "transfer_readings": [ { "reading_date": "2019-08-01", "reading_value": "500.00", "reading_type": "CUSTOMER" } ], "is_prepay": true, "prepay_details": { "debt_balance": "21.3", "credit_balance": "12.3", "transfer_vend_read_date": "2019-07-31", "gas_debt_repayment_options": { "weekly_min": "3.00", "weekly_max": "3.50" } } } ], "et_in_progress": false, "dr_in_progress": false, "aq_history": [ { "effective_from": "2019-01-01", "consumption": "8720" }, { "effective_from": "2018-01-01", "effective_to": "2018-12-31", "consumption": "8712" }, { "effective_from": "2017-01-01", "effective_to": "2017-12-31", "consumption": "8716" } ] } ], "property_administrators": [ { "given_name": "Groundskeeper", "family_name": "Willie", "email": "groundskeeper@willie.com", "mobile": "07712354321", "landline": "+442076543210", "date_of_birth": "1955-02-23", "title": "Mr", "salutation": "Hi" } ] } ], "transfer_balance": "30.00", "ledgers": [ { "current_statement_transactions": [ { "transaction_id": "1", "transaction_date": "2019-08-04", "amount": "10.00", "type": "REPAYMENT", "reason": "FULL_CREDIT_REFUND", "payment_type": "" }, { "transaction_id": "2", "transaction_date": "2019-08-05", "amount": "20.00", "type": "PAYMENT", "reason": "ACCOUNT_CHARGE_PAYMENT" } ], "historical_statement_transactions": [ { "transaction_id": "3", "transaction_date": "2018-08-05", "amount": "10.00", "type": "PAYMENT", "reason": "ACCOUNT_CHARGE_PAYMENT" }, { "transaction_id": "4", "transaction_date": "2018-07-05", "amount": "10.00", "type": "CREDIT", "reason": "DIRECT_DEBIT_DISCOUNT" } ], "last_statement_closing_date": "2019-07-31", "last_statement_balance": "20.00", "last_statement_issue_date": "2019-08-01", "ledger_balance": "30.00" } ], "last_billed_to_date": "2019-08-01", "payment_schedules": [ { "amount": "6.00", "day_of_month": 10, "frequency": "MONTHLY", "means": "DD", "start_date": "2018-01-01", "is_debt_repayment_plan": true, "debt_repayment_element": "2.00", "debt_repayment_end_date": "2020-03-26" }, { "amount": "60.00", "day_of_month": 2, "frequency": "MONTHLY", "means": "DD", "start_date": "2018-01-01" } ], "references": [ { "namespace": "tentacle-energy.allpay-client-reference-number", "value": "1234567890" } ], "notes": [ { "created_at": "2018-10-10T10:20:00Z", "body": "This is a note", "document_paths": [ { "document_path": "/notes/1234/attachment.jpg" } ] } ], "statements": [ { "bill_period_from_date": "2019-06-01", "bill_period_to_date": "2019-07-01", "statement_path": "/EXTERNAL-1234/2019-06-01-to-2019-07-01.pdf", "statement_id": "54321" }, { "bill_period_from_date": "2019-07-01", "bill_period_to_date": "2019-08-01", "statement_path": "/EXTERNAL-1234/2019-07-01-to-2019-08-01.pdf", "statement_id": "12345" } ], "warm_home_discount": [ { "tax_year": "2017/18", "account_type": "CREDIT", "group": "CORE" } ], "dunning_path": { "path_name": "standard_domestic", "start_date": "2020-03-26" }, "debts": [ { "agency_name": "Debt R Us", "start_date": "2019-03-26", "is_insolvent": false, "aged_debt": [ { "debt_amount": "123.00", "due_date": "2020-12-01" } ] } ], "last_payment_review_date": "2019-06-01", "next_bill_due_date": "2019-09-20", "smart_read_frequency": "HALF_HOURLY", "smart_read_cycle_day": 10, "communication_preference": "ONLINE", "document_accessibility": "LARGE_PRINT", "account_campaigns": [ { "slug": "super_account", "campaign_note": "Campaign note" } ], "metadata": [ { "key": "metadata_key", "value": { "some_data": "some_value" } } ] }

Create account

Overview

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.

Schema

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

Responses

The following responses may be returned from the API.

Status codeDescription
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" }

Payloads

Example payload
{ "import_supplier": "TENTACLE_ENERGY", "external_account_number": "EXTERNAL-1234", "unknown_occupier": false, "customers": [ { "given_name": "Bob", "family_name": "Jabłoński", "email": "bob@jablonski.com", "mobile": "07123456789", "landline": "02072343456", "date_of_birth": "1989-01-11", "title": "Mr", "salutation": "Hi", "psr": [ { "elec_industry_code": "01", "effective_from": "2012-01-01" }, { "gas_industry_code": "01", "effective_from": "2012-01-01" } ], "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_name": "Robert Jabłoński", "billing_address1": "123 Fake Street", "billing_address2": "", "billing_address3": "", "billing_address4": "", "billing_address5": "", "billing_postcode": "W1F 9DE", "account_type": "DOMESTIC", "sales_channel": "DIRECT", "sales_subchannel": "", "supply_addresses": [ { "supply_address1": "123 Fake Street", "supply_address2": "", "supply_address3": "", "supply_address4": "", "supply_address5": "", "supply_postcode": "W1F 9DE", "is_landlord": false, "customer_at_supply_address_from_date": "2019-01-01", "meter_points": [ { "identifier": "1200060176720", "supply_type": "ELECTRICITY", "agreements": [ { "tariff_code": "ELEC-1234-J", "effective_from": "2019-08-01" } ], "mpid": "TENT", "supply_start_date": "2019-01-01", "profile_class": 1, "ssc": "0393", "meters": [ { "meter_serial_number": "Z16N389556", "installed_on": "2001-01-01", "registers": [ { "register_id": "1", "tpr": "00001", "number_of_digits": 5 }, { "register_id": "X", "tpr": "00043", "number_of_digits": 5, "is_settlement": false } ], "transfer_readings": [ { "register_id": "1", "reading_date": "2019-08-01", "reading_value": "1000.00", "reading_type": "CUSTOMER" } ], "reading_history": [ { "register_id": "1", "reading_date": "2019-06-20", "reading_value": "980.00", "reading_type": "CUSTOMER", "billed": true }, { "register_id": "1", "reading_date": "2019-05-20", "reading_value": "960.00", "reading_type": "ROUTINE", "billed": true } ] } ], "et_in_progress": false, "dr_in_progress": false, "smart_refusal_interest": { "type": "NOT_INTERESTED", "date": "2020-04-01", "refusal_reason": "DO_NOT_OWN_HOME", "source": "EMAIL" }, "eac_history": [ { "effective_from": "2019-10-01", "tpr": "00001", "consumption": "1500", "source": "D0019" }, { "effective_from": "2019-09-01", "tpr": "00001", "consumption": "1300", "source": "D0019" } ] }, { "identifier": "9353824109", "supply_type": "GAS", "agreements": [ { "tariff_code": "GAS-1234-J", "effective_from": "2019-08-01" } ], "mpid": "TEN", "shipper_mpid": "TCL", "supply_start_date": "2019-04-10", "meters": [ { "meter_serial_number": "54BV", "installed_on": "2002-01-01", "gas_number_of_digits": 5, "smart_type": "SMETS1", "transfer_readings": [ { "reading_date": "2019-08-01", "reading_value": "500.00", "reading_type": "CUSTOMER" } ], "is_prepay": true, "prepay_details": { "debt_balance": "21.3", "credit_balance": "12.3", "transfer_vend_read_date": "2019-07-31", "gas_debt_repayment_options": { "weekly_min": "3.00", "weekly_max": "3.50" } } } ], "et_in_progress": false, "dr_in_progress": false, "aq_history": [ { "effective_from": "2019-01-01", "consumption": "8720" }, { "effective_from": "2018-01-01", "effective_to": "2018-12-31", "consumption": "8712" }, { "effective_from": "2017-01-01", "effective_to": "2017-12-31", "consumption": "8716" } ] } ], "property_administrators": [ { "given_name": "Groundskeeper", "family_name": "Willie", "email": "groundskeeper@willie.com", "mobile": "07712354321", "landline": "+442076543210", "date_of_birth": "1955-02-23", "title": "Mr", "salutation": "Hi" } ] } ], "transfer_balance": "30.00", "ledgers": [ { "current_statement_transactions": [ { "transaction_id": "1", "transaction_date": "2019-08-04", "amount": "10.00", "type": "REPAYMENT", "reason": "FULL_CREDIT_REFUND", "payment_type": "" }, { "transaction_id": "2", "transaction_date": "2019-08-05", "amount": "20.00", "type": "PAYMENT", "reason": "ACCOUNT_CHARGE_PAYMENT" } ], "historical_statement_transactions": [ { "transaction_id": "3", "transaction_date": "2018-08-05", "amount": "10.00", "type": "PAYMENT", "reason": "ACCOUNT_CHARGE_PAYMENT" }, { "transaction_id": "4", "transaction_date": "2018-07-05", "amount": "10.00", "type": "CREDIT", "reason": "DIRECT_DEBIT_DISCOUNT" } ], "last_statement_closing_date": "2019-07-31", "last_statement_balance": "20.00", "last_statement_issue_date": "2019-08-01", "ledger_balance": "30.00" } ], "last_billed_to_date": "2019-08-01", "payment_schedules": [ { "amount": "6.00", "day_of_month": 10, "frequency": "MONTHLY", "means": "DD", "start_date": "2018-01-01", "is_debt_repayment_plan": true, "debt_repayment_element": "2.00", "debt_repayment_end_date": "2020-03-26" }, { "amount": "60.00", "day_of_month": 2, "frequency": "MONTHLY", "means": "DD", "start_date": "2018-01-01" } ], "references": [ { "namespace": "tentacle-energy.allpay-client-reference-number", "value": "1234567890" } ], "notes": [ { "created_at": "2018-10-10T10:20:00Z", "body": "This is a note", "document_paths": [ { "document_path": "/notes/1234/attachment.jpg" } ] } ], "statements": [ { "bill_period_from_date": "2019-06-01", "bill_period_to_date": "2019-07-01", "statement_path": "/EXTERNAL-1234/2019-06-01-to-2019-07-01.pdf", "statement_id": "54321" }, { "bill_period_from_date": "2019-07-01", "bill_period_to_date": "2019-08-01", "statement_path": "/EXTERNAL-1234/2019-07-01-to-2019-08-01.pdf", "statement_id": "12345" } ], "warm_home_discount": [ { "tax_year": "2017/18", "account_type": "CREDIT", "group": "CORE" } ], "dunning_path": { "path_name": "standard_domestic", "start_date": "2020-03-26" }, "debts": [ { "agency_name": "Debt R Us", "start_date": "2019-03-26", "is_insolvent": false, "aged_debt": [ { "debt_amount": "123.00", "due_date": "2020-12-01" } ] } ], "last_payment_review_date": "2019-06-01", "next_bill_due_date": "2019-09-20", "smart_read_frequency": "HALF_HOURLY", "smart_read_cycle_day": 10, "communication_preference": "ONLINE", "document_accessibility": "LARGE_PRINT", "account_campaigns": [ { "slug": "super_account", "campaign_note": "Campaign note" } ], "metadata": [ { "key": "metadata_key", "value": { "some_data": "some_value" } } ] }

Get account import status

Overview

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

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

Responses

The following responses may be returned from the API.

Status codeDescription
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": "PROCESSED | DRY_RUN_SUCCEEDED | IN_PROGRESS | CANCELLED | PENDING", "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" }