Customer Migrations Guide: Post Account Import

After an account has successfully been created you might need to import additional data. In this section we’ll walk you through the various endpoints you can use to add information to an imported account in Kraken.

Importing account notes
Importing financial transactions
Importing historical statements
Importing payment instructions
Send registration flows

Importing account notes

Use this endpoint to add notes to an account.

Some points to note:

A note must contain at least one of the fields body or document_paths.
A created_at datetime may optionally be provided. Otherwise, it will default to the current local time.
The document_paths refer to the locations in S3 where attached documents are stored. More details on document paths can be found here.
An optional is_pinned boolean can be passed in the payload to control whether this note will be pinned to the top of the Kraken account support site page.

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/notes/create/

The following responses may be returned from the API.

Status code	Description
`201 - Created`	If the payload is valid, a `201 Created` response will be returned containing a list of the posted notes and their creation status. A new note will only be created if a note on the account with the same body (and `created_at`, if provided) does not already exist. `[ { "created_at": "2020-01-01T12:00:00Z", "body": "Something very important to import.", "status": "NOTE_CREATION_SUCCESS" }, { "created_at": "2020-02-01T12:00:00Z", "body": "Something else very important to import.", "status": "NOTE_ALREADY_EXISTS" } ]`
`400 - Bad Request`	If there are validation errors, a `400 Bad Request` response will be returned, detailing the errors. To resolve the error, refer to the field definitions and validation rules.
`404 - Not Found`	If an account is not found, then a `404 Not Found` response will be returned. To resolve the error, check that the account has been imported (not just staged) and that the `import_supplier` code and `external_account_number` are correct.

{
    "import_supplier": "TENTACLE_ENERGY",
    "external_account_number": "EXTERNAL-1234",
    "notes": [
        {
            "body": "Some important pinned note.",
            "is_pinned": true,
            "unpin_at": "2020-06-01T12:00:00Z"
        },
        {
            "created_at": "2020-02-01T12:00:00Z",
            "body": "Some important note with an attachment.",
            "document_paths": [
                {
                    "document_path": "some/path/to/a/document.pdf"
                }
            ]
        }
    ]
}

Importing financial transactions

Use this endpoint to import financial transactions to an account.

The following optional URL params are available to tweak the behaviour of the API:

check_previously_added: boolean flag indicating whether to check if a transaction has already been added. Defaults to true.
force_add_to_current_statement: boolean flag. If set to true and the payload contains a transaction that is outside the currently-open statement period, this will modify the transaction date so that it is within the currently-open statement period. This then allows the transaction to be added to the statement instead of throwing an error. A description is added to the transaction to explain this, and a note is pinned to the account. Defaults to true.

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/transactions/create/

The following responses may be returned from the API.

Status code Description

Status code	Description
`201 - Created`	If the payload is valid, and there were no errors while importing the transactions, a `201 Created` response will be returned containing an object with a list of transactions that were passed in along with their creation statuses. For example: { "results": [ { "status": "TRANSACTION_ALREADY_EXISTS", "transaction_data": { "transaction_id": "1", "transaction_date": "2019-10-01", "amount": "71.00", "type": "PAYMENT", "reason": "GENERAL_CREDIT", "reference": "reference 1", "payment_type": "DEBIT_CARD", "status": "TRANSACTION_IMPORT_SUCCESS" } }, { "status": "TRANSACTION_ADDED_TO_ACCOUNT", "transaction_data": { "transaction_id": "2", "transaction_date": "2019-10-04", "amount": "180.00", "type": "PAYMENT", "reason": "GENERAL_CREDIT", "reference": "reference 2", "payment_type": "DEBIT_CARD" } } ] } The following statuses are available: `TRANSACTION_ADDED_TO_ACCOUNT`: the transaction has been added to both the account import data and the account. `TRANSACTION_ALREADY_EXISTS`: the transaction was added to the account previously, so it has been skipped this time.
`400 - Bad Request`	If there are validation errors, a `400 Bad Request` response will be returned, detailing the errors. To resolve the error, refer to the field definitions and validation rules. The error response contains the following information: The data of the first failing transaction An additional `error_detail` field with the reason for the failure The status `TRANSACTION_IMPORT_ERROR` For example: `{ "status": "TRANSACTION_IMPORT_ERROR", "error_detail": "Transaction is not within the open statement period.", "transaction_data": { "transaction_id": "1", "transaction_date": "2019-09-28", "amount": "71.00", "type": "PAYMENT", "reason": "GENERAL_CREDIT", "reference": "reference 1", "payment_type": "DEBIT_CARD" } }` To resolve the error refer to the reason detailed in the `error_detail` field.

201 - Created

If the payload is valid, and there were no errors while importing the transactions, a 201 Created response will be returned containing an object with a list of transactions that were passed in along with their creation statuses. For example:

{
    "results": [
{
            "status": "TRANSACTION_ALREADY_EXISTS",
            "transaction_data": {
                "transaction_id": "1",
                "transaction_date": "2019-10-01",
                "amount": "71.00",
                "type": "PAYMENT",
                "reason": "GENERAL_CREDIT",
                "reference": "reference 1",
                "payment_type": "DEBIT_CARD",
                "status": "TRANSACTION_IMPORT_SUCCESS"
}
},
{
            "status": "TRANSACTION_ADDED_TO_ACCOUNT",
            "transaction_data": {
                "transaction_id": "2",
                "transaction_date": "2019-10-04",
                "amount": "180.00",
                "type": "PAYMENT",
                "reason": "GENERAL_CREDIT",
                "reference": "reference 2",
                "payment_type": "DEBIT_CARD"
}
}
    ]
}

The following statuses are available:

TRANSACTION_ADDED_TO_ACCOUNT: the transaction has been added to both the account import data and the account.
TRANSACTION_ALREADY_EXISTS: the transaction was added to the account previously, so it has been skipped this time.

400 - Bad Request

If there are validation errors, a 400 Bad Request response will be returned, detailing the errors. To resolve the error, refer to the field definitions and validation rules. The error response contains the following information:

The data of the first failing transaction
An additional error_detail field with the reason for the failure
The status TRANSACTION_IMPORT_ERROR

For example:

{
    "status": "TRANSACTION_IMPORT_ERROR",
    "error_detail": "Transaction is not within the open statement period.",
    "transaction_data": {
        "transaction_id": "1",
        "transaction_date": "2019-09-28",
        "amount": "71.00",
        "type": "PAYMENT",
        "reason": "GENERAL_CREDIT",
        "reference": "reference 1",
        "payment_type": "DEBIT_CARD"
}
}

To resolve the error refer to the reason detailed in the error_detail field.

{
    "import_supplier": "TENTACLE_ENERGY",
    "external_account_number": "EXTERNAL-1234",
    "transactions": [
        {
            "transaction_id": "1",
            "transaction_date": "2019-10-01",
            "amount": 10.0,
            "type": "CHARGE",
            "reason": "IMPORTED_CHARGE",
            "display_note": "Some customer facing note about the charge.",
            "reference": "charge-reference-1",
            "note": "Some internal note about the charge."
        },
        {
            "transaction_id": "2",
            "transaction_date": "2019-10-01",
            "amount": 10.0,
            "type": "CHARGE",
            "reason": "PREPAY_DEBT_ADJUSTMENT",
            "display_note": "Some customer facing note about the prepay charge.",
            "reference": "prepay-charge-reference-1",
            "note": "Some internal note about the prepay charge.",
            "to_prepay_meter_serial_number": "Z16N389556"
        },
        {
            "transaction_id": "3",
            "transaction_date": "2019-10-01",
            "amount": 10.0,
            "type": "CREDIT",
            "reason": "IMPORTED_CREDIT",
            "display_note": "Some customer facing note about the credit.",
            "reference": "credit-reference-1",
            "note": "Some internal note about the credit."
        },
        {
            "transaction_id": "4",
            "transaction_date": "2019-10-01",
            "amount": 10.0,
            "type": "PAYMENT",
            "reason": "ACCOUNT_CHARGE_PAYMENT",
            "reference": "payment-reference-1",
            "payment_type": "DD_REGULAR_COLLECTION",
            "note": "Some internal note about the payment."
        },
        {
            "transaction_id": "5",
            "transaction_date": "2019-10-01",
            "amount": 10.0,
            "type": "REPAYMENT",
            "reason": "FULL_CREDIT_REFUND",
            "reference": "repayment-reference-1",
            "payment_type": "DIRECT_CREDIT",
            "note": "Some internal note about the repayment."
        },
        {
            "transaction_id": "6",
            "transaction_date": "2019-10-01",
            "amount": 10.0,
            "type": "SUPPLY_CHARGE",
            "display_note": "Some customer facing note about the supply charge.",
            "reference": "supply-charge-reference-1",
            "product_code": "SOME-PRODUCT-CODE-4321",
            "line_items": [
                {
                    "rate_band": "CONSUMPTION_STANDARD",
                    "start_date": "2019-10-01",
                    "end_date": "2019-11-01",
                    "number_of_units": 4.0,
                    "net_amount": 44.0,
                    "price_per_unit": 11.0,
                    "units": [
                        4.0,
                        8.0
                    ]
                }
            ],
            "tax_items": [
                {
                    "amount": 9.24,
                    "tax_type": "VAT",
                    "value_taxed": 44.0,
                    "rate": 0.21,
                    "unit_type": "PROPORTION"
                }
            ]
        }
    ]
}

Importing historical statements

Use this endpoint to import historical PDF statements onto an account. The historical statements payload contains an optional statement_path field that points to a location for the PDF statement in S3. For more information on document path parameters, see document paths section.

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/historical-statements/create/

The following responses may be returned from the API.

Status code	Description
`201 - Created`	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 the error, refer to the field definitions and validation rules.

{
    "import_supplier": "TENTACLE_ENERGY",
    "external_account_number": "EXTERNAL-1234",
    "statements": [
        {
            "bill_period_from_date": "2022-01-01",
            "bill_period_to_date": "2022-01-31",
            "statement_id": "1",
            "issued_date": "2022-02-02",
            "number": "1",
            "gross_amount": 100,
            "statement_path": "path/to/statement-1.pdf"
        }
    ]
}

Importing payment instructions

Use this endpoint to create a payment instruction for an account.

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/payment-instruction/create/

The following responses may be returned from the API.

Status code Description

Status code	Description
`201 - Created`	If the payload is valid, a `201 Created` response will be returned containing the Kraken account number and the reference. For example: `{ "kraken_account_number": "A-C90DC431", "reference": "THIS-IS-A-FAKE-REFERENCE" }`
`400 - Bad Request`	If there are validation errors, a `400 Bad Request` response will be returned, detailing the errors. To resolve the error, refer to the field definitions and validation rules. This error can be returned if we have persistent issues communicating with the upstream payment vendor (we call their API to verify the instruction exists, and retrieve the details to store in Kraken). In this case, the request should not be retried in its current form.
`500 - Internal Server Error`	If an unexpected error occurs, a `500 Internal Server Error` response will be returned. This error can be returned if we have intermittent issues communicating with the upstream payment vendor (we call their API to verify the instruction exists, and retrieve the details to store in Kraken). In this case, the request should be retried as-is.

201 - Created

If the payload is valid, a 201 Created response will be returned containing the Kraken account number and the reference. For example:

{
    "kraken_account_number": "A-C90DC431",
    "reference": "THIS-IS-A-FAKE-REFERENCE"
}

400 - Bad Request

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

This error can be returned if we have persistent issues communicating with the upstream payment vendor (we call their API to verify the instruction exists, and retrieve the details to store in Kraken). In this case, the request should not be retried in its current form.

500 - Internal Server Error

If an unexpected error occurs, a 500 Internal Server Error response will be returned.

This error can be returned if we have intermittent issues communicating with the upstream payment vendor (we call their API to verify the instruction exists, and retrieve the details to store in Kraken). In this case, the request should be retried as-is.

{
    "import_supplier": "TENTACLE_ENERGY",
    "external_account_number": "EXTERNAL-1234",
    "vendor": "STRIPE",
    "instruction_reference": "THIS-IS-A-FAKE-REFERENCE",
    "type": "CARD"
}

Send registration flows

Use this endpoint to submit registration flows for meter points on an existing imported account. Note that this endpoint marks meter points to be registered. Kraken will then pick up these meter points and attempt to register them. Given a successful response from this API, it is still possible for the registration process to fail downstream.

The following optional URL params are available to tweak the behaviour of the API:

supply_start_date: date. If provided, this date will be used as the supply start date in the registration flows sent out by Kraken. If omitted, the earliest valid supply start date will be used.

POST https://api.octopus.energy/v1/data-import/send-registration-flows/<import-supplier-code>/<external-account-number>/

The following responses may be returned from the API.

Status code Description

Status code	Description
`200 - OK`	If the request is successful, a `200 OK` response will be returned with an array of objects detailing the status of each of the meter points marked for enrolment. If a meter point was successfully marked for enrolment then a `REGISTRATION_FLOW_SUCCESS` status will be returned along with the MPAN or MPRN (`mpxn`). If there was an error in marking the meter point for enrolment then a `REGISTRATION_FLOW_ERROR` status will be returned along with the MPAN or MPRN and an additional `error_detail` field with more information on the reason for failure. `[ { "import_supplier_code": "TENTACLE_ENERGY", "external_account_number": "EXTERNAL-1234", "meter_points": [ { "mpxn": "1013004420117", "status": "REGISTRATION_FLOW_SUCCESS" }, { "mpxn": "3406086401", "error_detail": "TEN not current supplier", "status": "REGISTRATION_FLOW_ERROR" } ] } ]`
`404 - Not Found`	If an account is not found, or no meter points are found on the account to register, then a `404 Not Found` response will be returned. To resolve the error, check that the account has been imported (not just staged) and that the `import_supplier` code and `external_account_number` in the request are correct. An example `404` response is shown below: `[ { "error_detail": "Account not found for EXTERNAL-1234.", "import_supplier_code": "TENTACLE_ENERGY", "external_account_number": "EXTERNAL-1234" } ]`

200 - OK

If the request is successful, a 200 OK response will be returned with an array of objects detailing the status of each of the meter points marked for enrolment. If a meter point was successfully marked for enrolment then a REGISTRATION_FLOW_SUCCESS status will be returned along with the MPAN or MPRN (mpxn). If there was an error in marking the meter point for enrolment then a REGISTRATION_FLOW_ERROR status will be returned along with the MPAN or MPRN and an additional error_detail field with more information on the reason for failure.

[
{
        "import_supplier_code": "TENTACLE_ENERGY",
        "external_account_number": "EXTERNAL-1234",
        "meter_points": [
{
                "mpxn": "1013004420117",
                "status": "REGISTRATION_FLOW_SUCCESS"
},
{
                "mpxn": "3406086401",
                "error_detail": "TEN not current supplier",
                "status": "REGISTRATION_FLOW_ERROR"
}
        ]
}
]

404 - Not Found

If an account is not found, or no meter points are found on the account to register, then a 404 Not Found response will be returned. To resolve the error, check that the account has been imported (not just staged) and that the import_supplier code and external_account_number in the request are correct. An example 404 response is shown below:

[
{
        "error_detail": "Account not found for EXTERNAL-1234.",
        "import_supplier_code": "TENTACLE_ENERGY",
        "external_account_number": "EXTERNAL-1234"
}
]

Octopus Energy

Customer Migrations Guide: Post Account Import

API Endpoints

Importing account notes

Overview

Schema

Field definitions

Responses

Payloads

Example payload

Importing financial transactions

Overview

Schema

Field definitions

Responses

Payloads

Example payload

Importing historical statements

Overview

Schema

Field definitions

Responses

Payloads

Example payload

Importing payment instructions

Overview

Schema

Field definitions

Responses

Payloads

Example payload

Send registration flows

Overview

Responses