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.

Validate account
Stage account
Create account

Validate account

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.

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

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

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.

{
    "external_account_number": "EXTERNAL-1234",
    "import_supplier": "TENTACLE_ENERGY",
    "unknown_occupier": false,
    "billing_address1": "126 Rue de l'Université",
    "billing_address2": "",
    "billing_address3": "",
    "billing_address4": "Paris",
    "billing_postcode": "75007",
    "sales_channel": "DIRECT",
    "sales_subchannel": "Website",
    "last_billed_to_date": "2022-08-14",
    "customers": [
        {
            "title": "M.",
            "given_name": "Robert",
            "family_name": "Terwilliger",
            "email": "robert.terwilliger@gmail.com",
            "mobile": "+33809685772",
            "landline": "",
            "date_of_birth": "1957-10-11",
            "deceased": "",
            "customer_preferences": {
                "opted_into_updates": true,
                "opted_into_sms": false,
                "opted_into_offers": true,
                "opted_into_recommended": false
            }
        }
    ],
    "supply_addresses": [
        {
            "supply_address1": "126 Rue de l'Université",
            "supply_address2": "",
            "supply_address3": "",
            "supply_address4": "Paris",
            "supply_postcode": "75007",
            "customer_at_supply_address_from_date": "2019-04-01",
            "supply_points": [
                {
                    "identifier": "46147259228742",
                    "supply_type": "ELECTRICITY",
                    "supply_start_date": "2021-07-29",
                    "payment_schedules": [
                        {
                            "amount": 60.0,
                            "day_of_month": 2,
                            "frequency": "MONTHLY",
                            "means": "DD",
                            "start_date": "2022-01-01"
                        }
                    ],
                    "payment_instructions": [
                        {
                            "vendor": "GOCARDLESS",
                            "reference": "SUPPLIER-ELEC-1234",
                            "type": "DIRECT_DEBIT",
                            "valid_from": "2022-06-15"
                        }
                    ],
                    "billing_frequency": 12,
                    "contracts": [
                        {
                            "tariff_code": "ELEC-123",
                            "agreed_at": "2021-07-25T10:03:00+02:00",
                            "effective_from": "2021-08-01",
                            "effective_to": "2022-08-01",
                            "addons": [
                                {
                                    "band": "GREEN_POWER_50"
                                }
                            ]
                        },
                        {
                            "tariff_code": "ELEC-456",
                            "agreed_at": "2022-07-25T10:03:00+02:00",
                            "effective_from": "2022-08-01",
                            "effective_to": "2023-08-01",
                            "addons": [
                                {
                                    "band": "GREEN_POWER_55"
                                }
                            ]
                        },
                        {
                            "tariff_code": "ELEC-789",
                            "agreed_at": "2023-07-21T14:05:00+02:00",
                            "effective_from": "2023-08-01",
                            "addons": [
                                {
                                    "band": "CARBON_OFFSET_50"
                                }
                            ]
                        }
                    ],
                    "consent_data": {
                        "ELEC_CURVES": true,
                        "ELEC_INDEXES": false
                    }
                },
                {
                    "identifier": "35438560738869",
                    "supply_type": "GAS",
                    "supply_start_date": "2021-07-29",
                    "payment_schedules": [
                        {
                            "amount": 55.0,
                            "day_of_month": 2,
                            "frequency": "MONTHLY",
                            "means": "DD",
                            "start_date": "2022-01-01"
                        }
                    ],
                    "payment_instructions": [
                        {
                            "vendor": "GOCARDLESS",
                            "reference": "SUPPLIER-GAS-12345",
                            "type": "DIRECT_DEBIT",
                            "valid_from": "2022-06-15"
                        }
                    ],
                    "billing_frequency": 12,
                    "contracts": [
                        {
                            "tariff_code": "GAS-123",
                            "agreed_at": "2021-07-25T10:03:00+02:00",
                            "effective_from": "2021-08-01",
                            "effective_to": "2022-08-01"
                        },
                        {
                            "tariff_code": "GAS-456",
                            "agreed_at": "2022-07-25T10:03:00+02:00",
                            "effective_from": "2022-08-01",
                            "effective_to": "2023-08-01"
                        },
                        {
                            "tariff_code": "GAS-789",
                            "agreed_at": "2023-07-21T14:05:00+02:00",
                            "effective_from": "2023-08-01"
                        }
                    ],
                    "consent_data": {
                        "GAS_INDEXES": true
                    }
                }
            ]
        }
    ],
    "statements": [
        {
            "bill_period_from_date": "2021-01-01",
            "bill_period_to_date": "2022-01-01",
            "statement_path": "EXTERNAL-1234/2021-01-01-to-2022-01-01-electricity.pdf",
            "statement_id": "1"
        }
    ],
    "supplementary_ledgers": [
        {
            "ledger_code": "ENERGY_CHEQUE_LEDGER",
            "energy_cheques": [
                {
                    "number": "1232542",
                    "protection_from": "2023-01-01",
                    "protection_to": "2023-06-01",
                    "source": "PAPERLESS",
                    "asp_remittance_ref": "abcdefg-1234567",
                    "amount": 1234,
                    "valid_to": "2023-06-01",
                    "status": "VALID"
                }
            ]
        }
    ],
    "notes": [
        {
            "created_at": "2018-10-10T10:20:00Z",
            "body": "This is a note",
            "document_paths": [
                {
                    "document_path": "/notes/1234/attachment.jpg"
                }
            ]
        }
    ],
    "account_campaigns": [
        {
            "slug": "super_account",
            "campaign_note": "Campaign note"
        }
    ],
    "metadata": [
        {
            "key": "metadata_key",
            "value": {
                "some_data": "some_value"
            }
        }
    ]
}

{
    "external_account_number": "EXTERNAL-1234",
    "import_supplier": "TENTACLE_ENERGY",
    "account_type": "BUSINESS",
    "business": {
        "business_type": "EURL",
        "details": [
            {
                "key": "siret",
                "value": "604 876 474 00494"
            }
        ]
    },
    "unknown_occupier": false,
    "billing_address1": "126 Rue de l'Université",
    "billing_address2": "",
    "billing_address3": "",
    "billing_address4": "Paris",
    "billing_postcode": "75007",
    "sales_channel": "DIRECT",
    "sales_subchannel": "Website",
    "last_billed_to_date": "2022-08-14",
    "customers": [
        {
            "title": "M.",
            "given_name": "Robert",
            "family_name": "Terwilliger",
            "email": "robert.terwilliger@gmail.com",
            "mobile": "+33809685772",
            "date_of_birth": "1957-10-11"
        }
    ],
    "supply_addresses": [
        {
            "supply_address1": "126 Rue de l'Université",
            "supply_address2": "",
            "supply_address3": "",
            "supply_address4": "Paris",
            "supply_postcode": "75007",
            "customer_at_supply_address_from_date": "2019-04-01",
            "supply_points": [
                {
                    "identifier": "46147259228742",
                    "supply_type": "ELECTRICITY",
                    "supply_start_date": "2021-07-29",
                    "payment_schedules": [
                        {
                            "amount": 60.0,
                            "day_of_month": 2,
                            "frequency": "MONTHLY",
                            "means": "DD",
                            "start_date": "2022-01-01"
                        }
                    ],
                    "payment_instructions": [
                        {
                            "vendor": "GOCARDLESS",
                            "reference": "SUPPLIER-ELEC-1234",
                            "type": "DIRECT_DEBIT",
                            "valid_from": "2022-06-15"
                        }
                    ],
                    "billing_frequency": 12,
                    "contracts": [
                        {
                            "tariff_code": "ELEC-BUSINESS",
                            "agreed_at": "2023-07-21T14:05:00+02:00",
                            "effective_from": "2023-01-01"
                        }
                    ],
                    "consent_data": {
                        "ELEC_CURVES": true,
                        "ELEC_INDEXES": false
                    }
                }
            ]
        }
    ]
}

Stage account

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.

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

The following responses may be returned from the API.

docs--rest--api-guides--data-import--account-creation-guide--staging--api-responses--html

Status code	Description

{
    "external_account_number": "EXTERNAL-1234",
    "import_supplier": "TENTACLE_ENERGY",
    "unknown_occupier": false,
    "billing_address1": "126 Rue de l'Université",
    "billing_address2": "",
    "billing_address3": "",
    "billing_address4": "Paris",
    "billing_postcode": "75007",
    "sales_channel": "DIRECT",
    "sales_subchannel": "Website",
    "last_billed_to_date": "2022-08-14",
    "customers": [
        {
            "title": "M.",
            "given_name": "Robert",
            "family_name": "Terwilliger",
            "email": "robert.terwilliger@gmail.com",
            "mobile": "+33809685772",
            "landline": "",
            "date_of_birth": "1957-10-11",
            "deceased": "",
            "customer_preferences": {
                "opted_into_updates": true,
                "opted_into_sms": false,
                "opted_into_offers": true,
                "opted_into_recommended": false
            }
        }
    ],
    "supply_addresses": [
        {
            "supply_address1": "126 Rue de l'Université",
            "supply_address2": "",
            "supply_address3": "",
            "supply_address4": "Paris",
            "supply_postcode": "75007",
            "customer_at_supply_address_from_date": "2019-04-01",
            "supply_points": [
                {
                    "identifier": "46147259228742",
                    "supply_type": "ELECTRICITY",
                    "supply_start_date": "2021-07-29",
                    "payment_schedules": [
                        {
                            "amount": 60.0,
                            "day_of_month": 2,
                            "frequency": "MONTHLY",
                            "means": "DD",
                            "start_date": "2022-01-01"
                        }
                    ],
                    "payment_instructions": [
                        {
                            "vendor": "GOCARDLESS",
                            "reference": "SUPPLIER-ELEC-1234",
                            "type": "DIRECT_DEBIT",
                            "valid_from": "2022-06-15"
                        }
                    ],
                    "billing_frequency": 12,
                    "contracts": [
                        {
                            "tariff_code": "ELEC-123",
                            "agreed_at": "2021-07-25T10:03:00+02:00",
                            "effective_from": "2021-08-01",
                            "effective_to": "2022-08-01",
                            "addons": [
                                {
                                    "band": "GREEN_POWER_50"
                                }
                            ]
                        },
                        {
                            "tariff_code": "ELEC-456",
                            "agreed_at": "2022-07-25T10:03:00+02:00",
                            "effective_from": "2022-08-01",
                            "effective_to": "2023-08-01",
                            "addons": [
                                {
                                    "band": "GREEN_POWER_55"
                                }
                            ]
                        },
                        {
                            "tariff_code": "ELEC-789",
                            "agreed_at": "2023-07-21T14:05:00+02:00",
                            "effective_from": "2023-08-01",
                            "addons": [
                                {
                                    "band": "CARBON_OFFSET_50"
                                }
                            ]
                        }
                    ],
                    "consent_data": {
                        "ELEC_CURVES": true,
                        "ELEC_INDEXES": false
                    }
                },
                {
                    "identifier": "35438560738869",
                    "supply_type": "GAS",
                    "supply_start_date": "2021-07-29",
                    "payment_schedules": [
                        {
                            "amount": 55.0,
                            "day_of_month": 2,
                            "frequency": "MONTHLY",
                            "means": "DD",
                            "start_date": "2022-01-01"
                        }
                    ],
                    "payment_instructions": [
                        {
                            "vendor": "GOCARDLESS",
                            "reference": "SUPPLIER-GAS-12345",
                            "type": "DIRECT_DEBIT",
                            "valid_from": "2022-06-15"
                        }
                    ],
                    "billing_frequency": 12,
                    "contracts": [
                        {
                            "tariff_code": "GAS-123",
                            "agreed_at": "2021-07-25T10:03:00+02:00",
                            "effective_from": "2021-08-01",
                            "effective_to": "2022-08-01"
                        },
                        {
                            "tariff_code": "GAS-456",
                            "agreed_at": "2022-07-25T10:03:00+02:00",
                            "effective_from": "2022-08-01",
                            "effective_to": "2023-08-01"
                        },
                        {
                            "tariff_code": "GAS-789",
                            "agreed_at": "2023-07-21T14:05:00+02:00",
                            "effective_from": "2023-08-01"
                        }
                    ],
                    "consent_data": {
                        "GAS_INDEXES": true
                    }
                }
            ]
        }
    ],
    "statements": [
        {
            "bill_period_from_date": "2021-01-01",
            "bill_period_to_date": "2022-01-01",
            "statement_path": "EXTERNAL-1234/2021-01-01-to-2022-01-01-electricity.pdf",
            "statement_id": "1"
        }
    ],
    "supplementary_ledgers": [
        {
            "ledger_code": "ENERGY_CHEQUE_LEDGER",
            "energy_cheques": [
                {
                    "number": "1232542",
                    "protection_from": "2023-01-01",
                    "protection_to": "2023-06-01",
                    "source": "PAPERLESS",
                    "asp_remittance_ref": "abcdefg-1234567",
                    "amount": 1234,
                    "valid_to": "2023-06-01",
                    "status": "VALID"
                }
            ]
        }
    ],
    "notes": [
        {
            "created_at": "2018-10-10T10:20:00Z",
            "body": "This is a note",
            "document_paths": [
                {
                    "document_path": "/notes/1234/attachment.jpg"
                }
            ]
        }
    ],
    "account_campaigns": [
        {
            "slug": "super_account",
            "campaign_note": "Campaign note"
        }
    ],
    "metadata": [
        {
            "key": "metadata_key",
            "value": {
                "some_data": "some_value"
            }
        }
    ]
}

{
    "external_account_number": "EXTERNAL-1234",
    "import_supplier": "TENTACLE_ENERGY",
    "account_type": "BUSINESS",
    "business": {
        "business_type": "EURL",
        "details": [
            {
                "key": "siret",
                "value": "604 876 474 00494"
            }
        ]
    },
    "unknown_occupier": false,
    "billing_address1": "126 Rue de l'Université",
    "billing_address2": "",
    "billing_address3": "",
    "billing_address4": "Paris",
    "billing_postcode": "75007",
    "sales_channel": "DIRECT",
    "sales_subchannel": "Website",
    "last_billed_to_date": "2022-08-14",
    "customers": [
        {
            "title": "M.",
            "given_name": "Robert",
            "family_name": "Terwilliger",
            "email": "robert.terwilliger@gmail.com",
            "mobile": "+33809685772",
            "date_of_birth": "1957-10-11"
        }
    ],
    "supply_addresses": [
        {
            "supply_address1": "126 Rue de l'Université",
            "supply_address2": "",
            "supply_address3": "",
            "supply_address4": "Paris",
            "supply_postcode": "75007",
            "customer_at_supply_address_from_date": "2019-04-01",
            "supply_points": [
                {
                    "identifier": "46147259228742",
                    "supply_type": "ELECTRICITY",
                    "supply_start_date": "2021-07-29",
                    "payment_schedules": [
                        {
                            "amount": 60.0,
                            "day_of_month": 2,
                            "frequency": "MONTHLY",
                            "means": "DD",
                            "start_date": "2022-01-01"
                        }
                    ],
                    "payment_instructions": [
                        {
                            "vendor": "GOCARDLESS",
                            "reference": "SUPPLIER-ELEC-1234",
                            "type": "DIRECT_DEBIT",
                            "valid_from": "2022-06-15"
                        }
                    ],
                    "billing_frequency": 12,
                    "contracts": [
                        {
                            "tariff_code": "ELEC-BUSINESS",
                            "agreed_at": "2023-07-21T14:05:00+02:00",
                            "effective_from": "2023-01-01"
                        }
                    ],
                    "consent_data": {
                        "ELEC_CURVES": true,
                        "ELEC_INDEXES": false
                    }
                }
            ]
        }
    ]
}

Create account

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.

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

The following responses may be returned from the API.

docs--rest--api-guides--data-import--account-creation-guide--creation--api-responses--html

Status code	Description

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

Octopus Energy France

Customer Migrations Guide: Account Import

API Endpoints

Validate account

Overview

Schema

Responses

Payloads

Domestic account

Business account

Stage account

Overview

Schema

Responses

Payloads

Domestic account

Business account

Create account

Overview

Schema

Responses

Payloads

Example payload