Customer Migrations Guide
Welcome to the Kraken Migration API documentation. Our REST APIs offers a comprehensive set of endpoints to migrate accounts from other source systems into the Kraken platform. Our API streamlines the import process, ensuring a smooth transition for both clients and customers.
Process overview: A breakdown of the process so that you know what to expect along the way.
Preparation and Prerequisites: Essential information you need to know before using the API, including authentication methods and datetime formats.
Product Creation Guide: Step-by-step instructions for validating product data and creating products in Kraken, along with expected responses.
Account Import Guide: Step-by-step instructions for validating, staging, and creating accounts, along with expected responses.
Post-Import Actions: Instructions for adding or updating information in existing accounts, covering actions like adding financial records or account notes.
Additional Endpoints: Run through of other useful endpoints for retrieving information during the account import process, such as import statuses.
If you’re new to REST API’s, or you’d just like a quick refresher, check out this page here for a brief explanation of what it is and how it functions, including definitions of key terminology that you will come across throughout the process.
In this section we will explain each stage of the process so you know what to expect along the way.
Before using our API, there are a few things you must do in preparation:
Segment into cohorts: First, you must group accounts into cohorts to facilitate the import process. Coordinate with the Kraken team as required.
Prepare the data: Next you must prepare the data for import, aligning it with Kraken's API structure. While you are responsible for this part of the process, we can offer guidance based on past successful implementations. To help you prepare the data, you can refer to the section on validating data where you will find a comprehensive tables containing all field definitions and validation rules necessary for successful import. Make use of this resource to ensure your data is prepared correctly.
Set up an import supplier: You will have at least one import supplier where we group your imported accounts in Kraken. Speak with the Kraken team to determine the suitable configuration. See section on import suppliers for more information.
Once the data is prepared, and before you begin the account migration process, you must create your products in Kraken.
The product creation process is divided into 2 stages, each corresponding to its own endpoint:
Validate product data: first you must ensure that the data is prepared correctly so that it aligns with our API structure.
Create product in Kraken: once the data is validated you can go ahead and create the product within Kraken.
After you’ve prepared the data correctly, coordinated the set-up of an import supplier with us, and created your products in Kraken, it is time to import an account into Kraken.
The process to import an account is divided into 3 steps, each of which has its own endpoint.
Validate: First you must validate the data by calling the validation endpoint. In this step you will be able to check that the data is prepared correctly. If you receive an error response, just refer back to the field definitions table and check that the data has been inputted correctly. Run this endpoint as many times as required until you’ve received a successful response.
Stage: Once the data has been successfully validated, you must stage the account in Kraken. This step is not the same as creating an account. Before you do that you must first transfer the data to Kraken so that it’s ready for you to create the account. You can also update staged data before an account is created.
Create: Once the data has been staged, you can go ahead and create the account. This should be done as close to the previous step as possible to ensure that the data has not changed and become stale.
Additional actions: We offer an additional set of endpoints which might come in handy at different steps throughout the process. The purpose of these endpoints is to retrieve information. See section on Requesting Data for more information.
Once you’ve completed these steps and have successfully created an account in Kraken, there are a number of post-import actions you can take to add additional data to an account that has already been created.
These are:
Add account notes
Add financial transactions
Add historical statments
Add payment instructions
And voilà! By now you should have a clear idea of the process, so let's dive into any prerequisites you should be aware of before you begin.
The Kraken data-import REST APIs are authenticated using a token obtained using the
ObtainKrakenToken
GraphQL Mutation
. This can be authenticated with the Organisation API key provided to you by the Kraken
Tech team. When you have your token, you can set the Authorization header in
the client you are using to make the request. The header should be set to the value of your
token. For example, if your token is 12345, you would set the
Authorization header to 12345:
curl -H "Authorization: Token 12345" "https://api.octopus.energy/v1/data-import/..."Some fields in the payload are optional, as specified in the field definitions tables.
If a field is optional and you do not wish to provide data for it, then it should be omitted from the payload entirely.
If an optional object or array field is provided, the fields within the object/array must be provided if they are required.
If an optional field is provided, it must adhere to its relevant validation rules, and the validation rules of any sub-objects in the case of nested fields.
Certain endpoints accept dates or datetimes as fields in the payload. These should adhere to the ISO 8601 format.
For example:
YYYY-MM-DD (2023-11-25 - November 25, 2023)
YYYY-MM-DDTHH:MM:SSZ (2023-11-25T08:30:00Z - November 25, 2023, 8:30 AM UTC)
Some endpoints allow for the inclusion of document paths as fields in the payload. These paths are used to reference documents stored in Amazon S3 (Kraken's storage backend). Paths in the payload should be provided relative to the path specified in the data-import configuration. The data-import config is set on a per import supplier basis. See section on import suppliers for more information.
Each instance of Kraken is set up with an S3 bucket for storing production files. For the
sake of this example, let's say your production files are stored in a bucket called
tentacle-production-files. If the import config specifies a root location of
sftp/migratedfiles and the payload points to a path like:
{"path": "/path/to/document.pdf"}
then the document would be expected to be located at
s3://tentacle-production-files/sftp/migratedfiles/path/to/document.pdf.
This method of specifying document paths allows for flexibility in splitting up documents into different "folders" in S3. For example, you could have a path each for note documents and PDF statements, each split by date.
If you are unsure of the path root for your instance of Kraken, please speak to the Kraken team.
Many of the APIs detailed in this guide perform detailed validation on the payloads they
receive. If a payload fails validation, the API will return a 400 Bad Request
response detailing what went wrong. 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"
}
]
}
Each item in the errors array corresponds to an error object with
the same three keys:
detailis a human-readable description of the error. The exact wording may change over time, so please don't parse it or build any logic around it.codeis a machine-readable identifier for the error type. It will not change over time, so feel free to use in data analytics or other logic.attris a dot-delimited path that specifies which part of the input data caused the error. String components of the path refer to the names of fields within an object, while numeric components refer to the index of an item within an array, with0representing the first item in the array.
This API will evolve over time. Future updates to the API may include new endpoints or additions to existing endpoints. In order to preserve backward compatibility, the behaviour and return values of existing endpoints will not change without notice. The exception to this is fields that are currently undocumented, which may be given specific meaning in the future. Care should be taken when constructing payloads and requests to ensure that only documented fields are included.
The import supplier is used to group migrated accounts, allowing for the configuration of specific behaviours during account migration, such as sending automated customer emails upon migration. We will set up an initial import supplier for you and together determine your desired configuration.
Additional import suppliers for specific customer cohorts may also be created, addressing unique needs like migrating long-standing debt customers without initial communications. If you think you might need another import supplier, have a chat with us and we’ll assess whether it's the best solution.
An import supplier has one of the following statuses. The status is set by the Kraken team.
| Status | Description |
|---|---|
| Ongoing | The import supplier is currently in use and is accepting new accounts for migration. |
| Paused | Migrations using this import supplier are paused. Accounts attempting to migrate while in this status will receive an error. The difference between this status and the complete status is mostly semantic. Paused means we expect more accounts to be migrated on this import supplier. |
| Complete | Migrations using this import supplier are complete. Accounts attempting to migrate while in this status will receive an error. The difference between this status and the paused status is mostly semantic. Complete means we do not expect any more accounts to be migrated on this import supplier. |
Once you've prepared your data, and coordinated the setup of an import supplier with us, the next step is to create your products in Kraken. This is important as products must already exist in Kraken before accounts can be created that are associated with them.
During this stage, we'll walk you through the process of validating your product data and creating the product within Kraken. Here, you'll find all the fields and validation rules accepted by our API, as well as the various responses you may receive throughout this process.
Use this endpoint to validate product data before creating the products in Kraken.
POST https://api.octopus.energy/v1/data-import/validate-products/The endpoint accepts a JSON payload containing a list of product objects.
Example payload
[
{
"brand": "TENTACLE_ENERGY",
"code": "SUPER-PROD-V1",
"full_name": "Super product - v1",
"display_name": "Super product",
"description": "This product is super",
"available_from_date": "2019-03-26",
"available_to_date": "2019-06-01",
"is_hidden": false,
"is_variable": true,
"is_prepay": false,
"is_green": true,
"is_business": false,
"is_default": false,
"client_params": {
"some_param": "some_value"
},
"tag_codes": [
"domestic.test_tag"
],
"tariffs": [
{
"fuel": "ELECTRICITY",
"gsp": "_A",
"tariff_code": "E-1R-SUPER-PROD-V1-A",
"payment_method": "DD",
"tariff_type": "STANDARD",
"unit_rates": [
{
"value": "1000",
"valid_from_date": "2019-03-26",
"rate_type": "STANDARD"
}
],
"standing_charges": [
{
"value": "500",
"valid_from_date": "2019-03-26"
}
]
},
{
"fuel": "ELECTRICITY",
"gsp": "_B",
"tariff_code": "E-2R-SUPER-PROD-V1-B",
"payment_method": "DD",
"tariff_type": "ECONOMY7",
"unit_rates": [
{
"value": "1000",
"valid_from_date": "2019-03-26",
"rate_type": "ECO7_DAY"
},
{
"value": "500",
"valid_from_date": "2019-03-26",
"rate_type": "ECO7_NIGHT"
}
],
"standing_charges": [
{
"value": "500",
"valid_from_date": "2019-03-26"
}
]
},
{
"fuel": "ELECTRICITY",
"gsp": "_B",
"tariff_code": "E-FLAT2R-SUPER-PROD-V1-B",
"payment_method": "DD",
"tariff_type": "FLAT_ECONOMY7",
"unit_rates": [
{
"value": "1000",
"valid_from_date": "2019-03-26",
"rate_type": "ECO7_DAY"
},
{
"value": "1000",
"valid_from_date": "2019-03-26",
"rate_type": "ECO7_NIGHT"
}
],
"standing_charges": [
{
"value": "500",
"valid_from_date": "2019-03-26"
}
]
},
{
"fuel": "GAS",
"gsp": "_C",
"tariff_code": "G-1R-SUPER-PROD-V1-B",
"payment_method": "DD",
"unit_rates": [
{
"value": "1000",
"valid_from_date": "2019-03-26"
}
],
"standing_charges": [
{
"value": "500",
"valid_from_date": "2019-03-26"
}
]
}
]
}
]The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the payload is valid, a |
400 - Bad Request |
If there are validation errors a |
Now that your data has been validated, you can go ahead and create the products in Kraken using the following endpoint.
POST https://api.octopus.energy/v1/data-import/products/The endpoint accepts a JSON payload containing a list of product objects, the same as the validate endpoint.
The following responses may be returned from the API.
| Status code | Description |
|---|---|
201 - Created |
If the payload is valid, and a product has been created, a {"code": "SUPER-PROD-V1"} |
400 - Bad Request |
If there are validation errors, a |
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.
Use this endpoint to validate account data before staging and creating an account.
POST https://api.octopus.energy/v1/data-import/validate-account/The endpoint accepts a JSON payload containing an object representing a single account.
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": "Customer refund",
"payment_type": ""
},
{
"transaction_id": "2",
"transaction_date": "2019-08-05",
"amount": "20.00",
"type": "PAYMENT",
"reason": "Card payment"
}
],
"historical_statement_transactions": [
{
"transaction_id": "3",
"transaction_date": "2018-08-05",
"amount": "10.00",
"type": "PAYMENT",
"reason": "Card 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"
}
}
]
}The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the payload is valid, a |
400 - Bad Request |
If there are validation errors, a {
"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. |
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.
POST https://api.octopus.energy/v1/data-import/account-import-process/create-or-update/Just as with the validation endpoint, this one accepts a JSON payload containing an object representing a single account.
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the payload is valid, and the request is updating data for an account that has been
staged previously, then a {"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 {"import_supplier": "TENTACLE_ENERGY", "external_account_number": "1234"} |
400 - Bad Request |
If account data fails to be staged, then a
|
Use this endpoint to process staged account data into an account in Kraken.
POST https://api.octopus.energy/v1/data-import/account-import-process/process/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 following responses may be returned from the API.
| Status code | Description |
|---|---|
201 - Created |
If the payload is valid and an account has been created, a {"kraken_account_number": "A-E8981832"} |
400 - Bad Request |
If there are validation errors, a
If an account has already been imported then two additional fields will be present
in the response:
If the API request was run with the 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 The concurrency limit is currently: 100. |
In the previous section, we walked through the steps of validating, staging, and creating an account in Kraken. Throughout this process, you may find it necessary to retrieve information about the ongoing state of the migration, such as which accounts have been successfully imported, which are pending import etc. For such inquiries, the following endpoints are at your disposal.
Use this endpoint to find out the status of a single account import process.
GET https://api.octopus.energy/v1/data-import/account-transfer-status/<import-supplier-code>/<external-account-number>/
GET https://api.octopus.energy/v1/data-import/account-transfer-status/TENTACLE_ENERGY/1234/
UNKNOWN- No account found in Kraken for the external account number and import supplier code. Either a previous process attempt has failed, or the import has never been attempted to be processed.COMPLETED- An account has been created in Kraken for the external account number and import supplier code.IN_PROGRESS- There is currently a migration process attempting to create this account.
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the account import process exists (whether an account has been created
or not), a For example: {
"status": "COMPLETED",
"kraken_account_number": "A-12AB34CD"
} |
404 - Not Found |
If an account cannot be found for the given
To resolve the error, check that the account has been imported and that the
|
Use this endpoint to list all accounts for import, whether they are pending (their data has been staged) or have had a Kraken account created.
GET https://api.octopus.energy/v1/data-import/all-account-import-processes/<import-supplier-code>/
GET https://api.octopus.energy/v1/data-import/all-account-import-processes/TENTACLE_ENERGY/
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If any pending or imported accounts are found for the given
[
{
"external_account_number": "1234",
"kraken_account_number": null,
"account_created_at": null
},
{
"external_account_number": "5678",
"kraken_account_number": "A-56785678",
"account_created_at": "2020-01-01T12:00:00Z"
}
] |
Use this endpoint to list all accounts pending import (their data has been staged).
GET https://api.octopus.energy/v1/data-import/pending-account-import-processes/<import-supplier-code>/<external-account-number>/
GET https://api.octopus.energy/v1/data-import/pending-account-import-processes/TENTACLE_ENERGY/1234/
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If any accounts pending import are found for the given [
{
"external_account_number": "1234",
"kraken_account_number": null,
"account_created_at": null
}
] |
Use this endpoint to list all accounts that have been imported and now have a Kraken account.
GET https://api.octopus.energy/v1/data-import/imported-account-import-processes/<import-supplier-code>/<external-account-number>/
GET https://api.octopus.energy/v1/data-import/imported-account-import-processes/TENTACLE_ENERGY/1234/
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If any imported accounts are found for the given [
{
"external_account_number": "5678",
"kraken_account_number": "A-56785678",
"account_created_at": "2020-01-01T12:00:00Z"
}
] |
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.
Use this endpoint to add notes to an account.
POST https://api.octopus.energy/v1/data-import/notes/create/Example payload
{
"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"
}
]
}
]
}Some points to note:
-
A note must contain at least one of the fields
bodyordocument_paths. -
A
created_atdatetime may optionally be provided. Otherwise, it will default to the current local time. -
The
document_pathsrefer to the locations in S3 where attached documents are stored. More details on document paths can be found here. -
An optional
is_pinnedboolean can be passed in the payload to control whether this note will be pinned to the top of the Kraken account support site page.
The following responses may be returned from the API.
| Status code | Description |
|---|---|
201 - Created |
If the payload is valid, a [
{
"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 |
404 - Not Found |
If an account is not found, then a |
Use this endpoint to import financial transactions to an account.
POST https://api.octopus.energy/v1/data-import/transactions/create/
POST https://api.octopus.energy/v1/data-import/transactions/create/?check_previously_added=true&force_add_to_current_statement=true
Example payload
{
"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"
}
]
}
]
}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.
The following responses may be returned from the API.
| Status code | Description |
|---|---|
201 - Created |
If the payload is valid, and there were no errors while importing the transactions,
a {
"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:
|
400 - Bad Request |
If there are validation errors, a
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 |
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 here.
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 |
Use this endpoint to create a payment instruction for an account.
POST https://api.octopus.energy/v1/data-import/payment-instruction/create/Example payload
{
"import_supplier": "TENTACLE_ENERGY",
"external_account_number": "EXTERNAL-1234",
"vendor": "STRIPE",
"instruction_reference": "THIS-IS-A-FAKE-REFERENCE",
"type": "CARD"
}The following responses may be returned from the API.
| Status code | Description |
|---|---|
201 - Created |
If the payload is valid, a {
"kraken_account_number": "A-C90DC431",
"reference": "THIS-IS-A-FAKE-REFERENCE"
} |
400 - Bad Request |
If there are validation errors, a 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 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. |
This section details additional endpoints that are available to you and might be used during the course of the migration.
Use this endpoint to submit registration flows for meter points on an existing imported account. Note that this endpoint <i>marks</i> 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.
POST https://api.octopus.energy/v1/data-import/send-registration-flows/<import-supplier-code>/<external-account-number>/
POST https://api.octopus.energy/v1/data-import/send-registration-flows/TENTACLE_ENERGY/1234/
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.
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the request is successful, a [
{
"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 [
{
"error_detail": "Account not found for EXTERNAL-1234.",
"import_supplier_code": "TENTACLE_ENERGY",
"external_account_number": "EXTERNAL-1234"
}
] |
Use this endpoint to list the status of all meter points for an already imported account in Kraken.
GET https://api.octopus.energy/v1/data-import/meterpoint-statuses-for-account/<import-supplier-code>/<external-account-number>/
GET https://api.octopus.energy/v1/data-import/meterpoint-statuses-for-account/TENTACLE_ENERGY/EXTERNAL-1234/
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the request is valid, a [
{"mpxn":"9349409806","status":"PRE_REGISTRATION"}
] |
404 - Not Found |
If an account is not found, or no meter points are found on the account, then a
[
{"error": f"No meterpoints found for EXTERNAL-1234"}
] |