Customer Migrations Guide: Account Import

By now you should be prepared to go ahead and migrate an account, so let’s get stuck in.

In this section we’ll guide you step by step through the process of validating, staging and creating an account, and what kind of responses you can expect to receive.

API Endpoints

Validate account

Overview

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

The endpoint accepts a JSON payload containing an object representing a single account.

Providing an unrecognised field will not raise an error: instead the field will be omitted from the payload entirely.

Schema

Field definitions

See here for a complete list of the fields available in the API, along with a definition and their rules for validation.

Refer to this table when preparing the data, and use it to correct any invalid data you might have inputted resulting in an error response.

POST https://api.octopus.energy/v1/data-import/validate-account/

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 validated data 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. Here's an example response:

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

For more detail on validation error responses see here.

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": [ { "mpxn": "1200060176720", "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" } ] }, { "mpxn": "9353824109", "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", "address1": "114A East Road", "address2": "Kirkwall", "address3": "Orkney", "address4": "", "address5": "", "postcode": "KW15 5LL" } ] } ], "contracts": [ { "mpxn": "1200060176720", "tariff_code": "ELEC-1234-J", "effective_from": "2019-08-01" }, { "mpxn": "9353824109", "tariff_code": "GAS-1234-J", "effective_from": "2019-08-01" } ], "last_statement_balance": "20.00", "last_statement_issue_date": "2019-08-01", "last_billed_to_date": "2019-08-01", "transfer_balance": "30.00", "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" } ], "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" }, "debt": { "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" } } ] }

Stage account

Overview

Use this endpoint to stage account data before creating an account. As the name suggests, this endpoint stores the data in Kraken but does not create an account from the data. Staged account data can be updated as many times as you like before an account is created.

Just as with the validation endpoint, this one accepts a JSON payload containing an object representing a single account.

Before an account is staged, 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 staging in Kraken.

Schema

Field definitions

See here for a complete list of the fields available in the API, along with a definition and their rules for validation.

Refer to this table when preparing the data, and use it to correct any invalid data you might have inputted resulting in an error response.

POST https://api.octopus.energy/v1/data-import/account-import-process/create-or-update/

Responses

The following responses may be returned from the API.

Status codeDescription
200 - OK

If the payload is valid, and the request is updating data for an account that has been staged previously, then a 200 OK response will be returned detailing the external_account_number and import_supplier. For example:

{"import_supplier": "TENTACLE_ENERGY", "external_account_number": "1234"}
201 - Created

If the payload is valid, and the request is staging data for an account for the first time, then a 201 Created response will be returned detailing the external_account_number and import_supplier. For example:

{"import_supplier": "TENTACLE_ENERGY", "external_account_number": "1234"}
400 - Bad Request

If account data fails to be staged, then a 400 Bad Request response will be returned detailing the errors. In this scenario, check that:

  • The payload is valid (refer to the field definitions and validation rules table).

  • The account has not been imported already, or marked to be skipped.

  • The migration for the import_supplier is still ongoing (if you receive an error indicating it is paused or complete, get in touch with the Kraken team).

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": [ { "mpxn": "1200060176720", "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" } ] }, { "mpxn": "9353824109", "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", "address1": "114A East Road", "address2": "Kirkwall", "address3": "Orkney", "address4": "", "address5": "", "postcode": "KW15 5LL" } ] } ], "contracts": [ { "mpxn": "1200060176720", "tariff_code": "ELEC-1234-J", "effective_from": "2019-08-01" }, { "mpxn": "9353824109", "tariff_code": "GAS-1234-J", "effective_from": "2019-08-01" } ], "last_statement_balance": "20.00", "last_statement_issue_date": "2019-08-01", "last_billed_to_date": "2019-08-01", "transfer_balance": "30.00", "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" } ], "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" }, "debt": { "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 staged account data into an account in Kraken.

The endpoint accepts a JSON payload that contains an object referencing existing staged account data. The operations_team_name that the account should be linked to should also be provided. An optional dry_run field is available to test the account creation process without actually creating the account. This is useful for testing the process to ensure that an account would be created successfully.

The referenced team must already exist in Kraken and the account data must already have been staged.

Schema

Field definitions

See here for a complete list of the fields available in the API, along with a definition and their rules for validation.

Refer to this table when preparing the data, and use it to correct any invalid data you might have inputted resulting in an error response.

POST https://api.octopus.energy/v1/data-import/account-import-process/process/

Responses

The following responses may be returned from the API.

Status codeDescription
201 - Created

If the payload is valid and an account has been created, a 201 Created response will be returned with the newly created Kraken account number. For example:

{"kraken_account_number": "A-E8981832"}
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 then two additional fields will be present in the response: external_account_number and kraken_account_number.

If the API request was run with the dry_run flag set to true, and the request would ordinarily have been sucessful, then a 400 Bad Request response will be returned with the following response:

Account would successfully import. Rolled back due to Dry Run.
429 - Too Many Requests

There is an optional concurrency limit on the number of accounts that can be processed at once. If enabled, any requests to create an account that exceed this limit will be rejected with 429 Too Many Requests responses. These requests should be retried once other ongoing accounts have finished processing.

The concurrency limit is currently: 100.

Payloads

Example payload
{ "external_account_number": "EXTERNAL-1234", "import_supplier_code": "TENTACLE_ENERGY", "operations_team_name": "A", "dry_run": false }