# EDF Energy (EDF GB) Kraken Customer Migration / Data Import REST API — OpenAPI 3.0.3, harvested verbatim.
# Source URL : https://api.edfgb-kraken.energy/data-import/schema/
# Documented : https://developer.edfgb-kraken.energy/rest/guides/data-import/
# HTTP status : 200, Content-Type application/vnd.oai.openapi; charset=utf-8
# Fetched : 2026-07-27, anonymously, no API key, no account
# Provenance : first-party EDF-hosted document. Nothing was added, removed or altered;
# these comment lines are the only addition and do not change the parsed document.
openapi: 3.0.3
info:
title: Kraken
version: v1
paths:
/v1/data-import/account-import-process/create-or-update/:
post:
operationId: V1 Create Or Update Account Import Process
description: 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.
summary: Use this endpoint to stage account data before creating an account.
tags:
- account_import
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnergyAccount'
required: true
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrUpdateAccountImportProcess'
examples:
SuccessfulImportProcessModification.:
value:
external_account_number: '1234'
import_supplier_code: TENTACLE_ENERGY
summary: Successful import process modification.
description: 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`.
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrUpdateAccountImportProcess'
examples:
SuccessfulImportProcessModification.:
value:
external_account_number: '1234'
import_supplier_code: TENTACLE_ENERGY
summary: Successful import process modification.
description: 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`.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadCreateOrUpdateAccountImportProcess'
examples:
PostcodeFieldMissingFromBillingAddress:
value:
billing_address:
postcode:
- postcode field is required.
summary: Postcode field missing from billing address
AccountProcessAlreadyImported.:
value:
external_account_number: EXTERNAL-1234
kraken_account_number: A-E8981832
non_field_errors:
- The account import process with the account number EXTERNAL-1234
has already been imported.
summary: Account process already imported.
description: |2
If account data fails to be staged, then the details of the validation errors will
be returned in the response. 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).
x-doc-alerts:
- 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.
/v1/data-import/account-import-process/process/:
post:
operationId: V1 Process Account Import Process
description: 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.
summary: Use this endpoint to process staged account data into an account in
Kraken.
tags:
- account_import
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessAccountImportProcess'
required: true
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessAccountImportProcessCreation'
examples:
SuccessfulAccountCreationFromAnExistingProcess.:
value:
external_account_number: '00001234'
kraken_account_number: A-E8981832
account_number: A-E8981832
summary: Successful account creation from an existing process.
description: If the payload is valid and an account has been created, the
newly created Kraken account number will be returned in the response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadProcessAccountImportProcess'
examples:
AccountProcessAlreadyImported.:
value:
external_account_number: EXTERNAL-1234
kraken_account_number: A-E8981832
non_field_errors:
- The account import process with the account number EXTERNAL-1234
has already been imported.
summary: Account process already imported.
AccountCreationInDry-runMode.:
value:
detail: Account would successfully import. Rolled back due to
Dry Run.
code: '400'
summary: Account creation in dry-run mode.
description: |2
If there are validation errors, they will be detailed in the body of the response.
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 successful, then the response will also be returned.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 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. These requests should be retried
once other ongoing accounts have finished processing.
x-doc-alerts:
- Before an account is created, it is validated according to the same rules
as the validate endpoint above. This is an extra safety check to make sure
nothing has changed between creating the data and submitting it for account
creation in Kraken.
- The referenced team must already exist in Kraken and the account data must
already have been staged.
/v1/data-import/account-transfer-status/{import_supplier_code}/{external_account_number}/:
get:
operationId: V1 Get Account Transfer Status
description: Use this endpoint to find out the status of a single account import
process.
summary: Find out the status of a single account import process
parameters:
- in: path
name: external_account_number
schema:
type: string
description: The account number in the source system.
required: true
- in: path
name: import_supplier_code
schema:
type: string
description: The code of an existing Import Supplier.
required: true
tags:
- account_import
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTransferStatus'
examples:
FoundAccountTransferStatus:
value:
status: COMPLETED
account_number: A-12AB34CD
kraken_account_number: A-12AB34CD
summary: Found account transfer status
description: If the account import process exists (whether an account has
been created or not), the `status` and `kraken_account_number` will be
returned in the body of the response. If an account has not yet been created
from the import data, then the `kraken_account_number` will be an empty
string.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/AccountNotFoundError'
description: |2
If an account cannot be found for the given `import_supplier` and
`external_account_number`, this response will be returned.
To resolve the error, check that the account has been imported and that the
`import_supplier` and `external_account_number` are correct.
x-doc-alerts: []
/v1/data-import/all-account-import-processes/{import_supplier_code}/:
get:
operationId: V1 Get All Account Import Processes
description: 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.
summary: List all accounts for import
parameters:
- in: path
name: import_supplier_code
schema:
type: string
description: The code of an existing Import Supplier.
required: true
tags:
- query
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ImportProcess'
examples:
AllAccountImportProcesses:
value:
- - 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'
summary: All account import processes
description: If any pending or imported accounts are found for the given
`import_supplier_code`, they will be returned in the response. If the
account is pending import then the `kraken_account_number` and `account_created_at
will` be null.
x-doc-alerts: []
/v1/data-import/historical-statements/create/:
post:
operationId: V1 Create Historical Statements
description: Use this endpoint to import historical PDF statements onto an account.
summary: Use this endpoint to import historical PDF statements onto an account.
tags:
- post_account_import
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalStatements'
examples:
ExamplePayload:
value:
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
summary: Example payload
required: true
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/NonFieldErrors'
examples:
AccountNumberOrExternalAccountNumberMustBeProvided:
value:
non_field_errors:
- Either account_number or external_account_number must be provided.
summary: account_number or external_account_number must be provided
description: Validation error.
'404':
description: The account import process or account have not been found.
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.
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalStatements'
description: If the payload is valid, the validated data will be returned
in the body of the response.
x-doc-alerts: []
/v1/data-import/imported-account-import-processes/{import_supplier_code}/:
get:
operationId: V1 Get Imported Accounts
description: Use this endpoint to list all accounts that have been imported
and now have a Kraken account.
summary: List all accounts that have been imported
parameters:
- in: path
name: import_supplier_code
schema:
type: string
description: The code of an existing Import Supplier.
required: true
tags:
- query
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ImportProcess'
examples:
SuccessfullyImportedImportProcesses:
value:
- - external_account_number: '5678'
kraken_account_number: A-56785678
account_created_at: '2020-01-01T12:00:00Z'
summary: Successfully imported import processes
description: If any imported accounts are found for the given `import_supplier_code`,
they will be returned in the response.
x-doc-alerts: []
/v1/data-import/meterpoint-statuses-for-account/{import_supplier_code}/{external_account_number}/:
get:
operationId: V1 Get Meter Point Statuses For Account
description: Use this endpoint to list all meter point statuses by import supplier
code and external account number.
summary: List meter point statuses for an account
parameters:
- in: path
name: external_account_number
schema:
type: string
description: The account number in the source system.
required: true
- in: path
name: import_supplier_code
schema:
type: string
description: The code of an existing Import Supplier.
required: true
tags:
- query
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GbrMeterPointStatus'
examples:
StatusOfAMeterPoint:
value:
- - mpxn: '9349409806'
status: PRE_REGISTRATION
summary: Status of a meter point
description: List of meter points and their status for given account & supplier.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/GbrMeterPointStatusError'
examples:
NoMeterPointFound:
value:
error: No meterpoints found for A-1234.
summary: No meter point found
description: Error fetching meter points
x-doc-alerts: []
/v1/data-import/notes/create/:
post:
operationId: V1 Create Account Notes
description: |-
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.
- 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.
summary: Use this endpoint to add notes to an account.
tags:
- post_account_import
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AccountNote'
examples:
ExamplePayload:
value:
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
summary: Example payload
required: true
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/NonFieldErrors'
examples:
AccountNumberOrExternalAccountNumberMustBeProvided:
value:
non_field_errors:
- Either account_number or external_account_number must be provided.
summary: account_number or external_account_number must be provided
description: Validation error.
'404':
description: The account import process or account have not been found.
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.
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAccountNotesResponse'
examples:
CreateNoteSuccessExample:
value:
- 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
summary: Create note success example
description: If the payload is valid, a list of the posted notes and their
creation status will be returned in the response. 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.
x-doc-alerts: []
/v1/data-import/payment-instruction/create/:
post:
operationId: V1 Create Payment Instruction
description: Create a payment instruction.
summary: Create a payment instruction.
tags:
- post_account_import
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LegacyPaymentInstruction'
examples:
ExamplePayload:
value:
import_supplier: TENTACLE_ENERGY
external_account_number: EXTERNAL-1234
vendor: STRIPE
reference: THIS-IS-A-FAKE-REFERENCE
type: CARD
summary: Example payload
required: true
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentInstructionResponse'
examples:
CreatedPaymentInstruction.:
value:
kraken_account_number: A-C90DC431
reference: THIS-IS-A-FAKE-REFERENCE
summary: Created payment instruction.
description: If the payload is valid, the Kraken account number and the
reference will be returned.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentInstructionError'
examples:
AccountAlreadyHasAnActiveInstructionError.:
value:
error_detail: Account already has an active instruction
external_account_number: '7654321'
import_supplier: SOME_IMPORT_SUPPLIER
reference: THIS-IS-A-FAKE-REFERENCE
summary: Account already has an active instruction error.
description: |2
If there are validation errors, the errors will be detailed in the body of the response. 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':
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentInstructionError'
description: |2
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**.
x-doc-alerts: []
/v1/data-import/pending-account-import-processes/{import_supplier_code}/:
get:
operationId: V1 Get Pending Account Import Processes
description: Use this endpoint to list all accounts pending import (their data
has been staged).
summary: List all accounts pending import
parameters:
- in: path
name: import_supplier_code
schema:
type: string
description: The code of an existing Import Supplier.
required: true
tags:
- query
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ImportProcess'
examples:
PendingAccountImportProcesses:
value:
- - external_account_number: '1234'
kraken_account_number: null
account_created_at: null
summary: Pending account import processes
description: If any accounts pending import are found for the given
`import_supplier_code`, they will be returned in the response.
For consistency with the other APIs the `kraken_account_number`
and `account_created_at` fields will be returned but will always
be `null`.
description: Pending import processes matching request parameters.
x-doc-alerts: []
/v1/data-import/send-registration-flows/{import_supplier_code}/{external_account_number}/:
post:
operationId: V1 Send Registration Flows
description: 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.
summary: Submit registration flows for meter points
parameters:
- in: path
name: external_account_number
schema:
type: string
description: The account number in the source system.
required: true
- in: path
name: import_supplier_code
schema:
type: string
description: The code of an existing Import Supplier.
required: true
tags:
- post_account_import
security:
- DataImportViewerAPIKeyAuthentication: []
- DRFKrakenTokenAuthentication: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GbrMeterPointRegistrationStatuses'
examples:
SuccessfulRegistrationFlowRequest:
value:
external_account_number: A-1234
import_supplier_code: TENTACLE_ENERGY
meter_points:
- mpxn: '1013004420117'
status: REGISTRATION_FLOW_SUCCESS
- mpxn: '3406086401'
status: REGISTRATION_FLOW_ERROR
error_detail: TEN not current supplier
summary: Successful Registration Flow Request
description: 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.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/GbrRegistrationFlowError'
examples:
AccountNotFound:
value:
external_account_number: A-1234
import_supplier_code: TENTACLE_ENERGY
error_detail: Account not found for A-1234.
summary: Account not found
description: 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.
x-doc-alerts: []
/v1/data-import/transactions/create/:
post:
operationId: V1 Create Transactions
description: Use this endpoint to import financial transactions to an account.
summary: Use this endpoint to import financial transactions to an account.
parameters:
- in: query
name: check_previously_added
schema:
type: boolean
default: true
description: Boolean flag indicating whether to check if a transaction has
already been added.
- in: query
name: force_add_to_current_statement
schema:
type: boolean
default: true
description: 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.
tags:
- post_account_import
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Transactions'
examples:
ExamplePayload:
value:
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
# --- truncated at 32 KB (553 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/edf-energy/refs/heads/main/openapi/edf-energy-kraken-data-import-openapi.yml