EDF Energy Account Import API

openapi: 3.2.0
info:
  title: Kraken Account Import API
  version: v1
  description: APIs for importing accounts.
servers:
- url: https://api.edfgb-kraken.energy/v1/
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: account_import
  x-title: Account Import
  description: APIs for importing accounts.
  x-documentation-order: 5
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: "\nIf account data fails to be staged, then the details of the validation errors will\nbe returned in the response. In this scenario, check that:\n- The payload is valid (refer to the field definitions and validation rules table).\n- The account has not been imported already, or marked to be skipped.\n- The migration for the `import_supplier` is still ongoing (if you receive an error\n  indicating it is paused or complete, get in touch with the Kraken team).\n"
      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: '

            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: '

            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/validate-account/:
    post:
      operationId: V1 Validate Account
      description: Use this endpoint to validate account data before staging and creating an account.
      summary: Use this endpoint to validate account data before staging and 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/EnergyAccount'
          description: If the payload is valid, the validated data will be returned in the body of the response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadValidateAccountRequest'
              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: 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.
      x-doc-alerts: []
  /v2/data-import/accounts/:
    post:
      operationId: V2 Schedule Account Creation
      description: Use this endpoint to schedule the creation of an account in Kraken. It accepts a request containing the necessary information for account creation, validates the data, and creates an account migration task to be executed asynchronously.
      summary: Schedule the creation of an account in Kraken
      tags:
      - account_import
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleAccountCreation'
            examples:
              ExamplePayload:
                value:
                  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:
                    - identifier: '1200060176720'
                      supply_type: ELECTRICITY
                      agreements:
                      - tariff_code: ELEC-1234-J
                        effective_from: '2019-08-01'
                      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
                    - identifier: '9353824109'
                      supply_type: GAS
                      agreements:
                      - tariff_code: GAS-1234-J
                        effective_from: '2019-08-01'
                      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
                  transfer_balance: '30.00'
                  ledgers:
                  - current_statement_transactions:
                    - transaction_id: '1'
                      transaction_date: '2019-08-04'
                      amount: '10.00'
                      type: REPAYMENT
                      reason: FULL_CREDIT_REFUND
                      payment_type: ''
                    - transaction_id: '2'
                      transaction_date: '2019-08-05'
                      amount: '20.00'
                      type: PAYMENT
                      reason: ACCOUNT_CHARGE_PAYMENT
                    historical_statement_transactions:
                    - transaction_id: '3'
                      transaction_date: '2018-08-05'
                      amount: '10.00'
                      type: PAYMENT
                      reason: ACCOUNT_CHARGE_PAYMENT
                    - transaction_id: '4'
                      transaction_date: '2018-07-05'
                      amount: '10.00'
                      type: CREDIT
                      reason: DIRECT_DEBIT_DISCOUNT
                    last_statement_closing_date: '2019-07-31'
                    last_statement_balance: '20.00'
                    last_statement_issue_date: '2019-08-01'
                    ledger_balance: '30.00'
                  last_billed_to_date: '2019-08-01'
                  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'
                  debts:
                  - 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
                summary: Example payload
        required: true
      security:
      - DataImportViewerAPIKeyAuthentication: []
      - DRFKrakenTokenAuthentication: []
      responses:
        '201':
          description: The payload has been successfully scheduled.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DRFError'
              examples:
                ScheduleAccountCreationErrorResponse(ValidationError):
                  value:
                    code: import_process_failed_validation
                    detail: Import process validation failed during account creation. Please validate the import process to get full details of the validation errors.
                    domain: import_process
                  summary: Schedule account creation error response (Validation Error)
                  description: 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.
                ScheduleAccountCreationErrorResponse(AlreadyImportedAccount):
                  value:
                    non_field_errors:
                      detail: The account import process with the account number 1234567890 has already been imported.
                      code: account_import_process_already_imported
                    account_id: A-12345678
                  summary: Schedule account creation error response (Already Imported Account)
                  description: If an account has already been imported, a 400 Bad Request response will be returned with account_id representing existing Kraken account number.
          description: Validation errors occurred while processing the request.
      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.
  /v2/data-import/accounts/{import_supplier_code}/{external_identifier}/:
    get:
      operationId: V2 Account Import Status
      description: Use this endpoint to retrieve the current status of an account import.
      summary: Return the status of an account import process
      parameters:
      - in: path
        name: external_identifier
        schema:
          type: string
        required: true
      - in: path
        name: import_supplier_code
        schema:
          type: string
        required: true
      tags:
      - account_import
      security:
      - DataImportViewerAPIKeyAuthentication: []
      - DRFKrakenTokenAuthentication: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportStatusResponse'
              examples:
                200OK-NoErrorInProcessing:
                  value:
                    status: CANCELLED | DRY_RUN_SUCCEEDED | IN_PROGRESS | PENDING | PROCESSED
                    kraken_identifier: null
                    created_at: '2025-10-07T09:00:21.179194+02:00'
                    modified_at: '2025-10-07T09:06:38.078396+02:00'
                    latest_event:
                      event: EVENT_ACCOUNT_IMPORT_PROCESS_CREATED
                      occurred_at: '2025-10-07T09:00:21.179194+02:00'
                      data: null
                    latest_error: null
                  summary: 200 OK - No error in processing
                  description: If the account import process exists, a <code>200 OK</code> response will be returned, detailing the <code>status</code>.
                200OK-ImportProcessIsProcessed:
                  value:
                    status: PROCESSED
                    kraken_identifier: INTERNAL-KRAKEN-IDENTIFIER
                    created_at: '2025-10-07T09:00:21.179194+02:00'
                    modified_at: '2025-10-07T09:06:38.078396+02:00'
                    latest_event:
                      event: EVENT_ACCOUNT_IMPORT_PROCESS_PROCESSED
                      occurred_at: '2025-10-07T09:06:38.078396+02:00'
                      data: null
                    latest_error: null
                  summary: 200 OK - Import process is processed
                  description: 'For example when the import process is processed we will have an internal kraken id:'
                200OK-ErrorInProcessing:
                  value:
                    status: ERRORED | DRY_RUN_ERRORED
                    kraken_identifier: null
                    created_at: '2025-10-07T09:00:21.179194+02:00'
                    modified_at: '2025-10-07T09:06:38.078396+02:00'
                    latest_event:
                      event: EVENT_ACCOUNT_IMPORT_PROCESS_ERRORED
                      occurred_at: '2025-10-07T09:06:38.078396+02:00'
                      data:
                        code: some_error_code
                        detail: A detailed error message
                        domain: import_process
                    latest_error:
                      code: some_error_code
                      detail: A detailed error message
                      domain: import_process
                  summary: 200 OK - Error in processing
                  description: 'For example when there is an error in processing:'
          description: The status of the account import.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                404NotFound:
                  value:
                    detail: The requested resource was not found.
                    code: not_found
                  summary: 404 Not Found
                  description: If the account import process does not exist, a 404 Not Found response will be returned.
          description: Import supplier code or external identifier not found.
      x-doc-alerts: []
  /v2/data-import/accounts/validate/:
    post:
      operationId: V2 Validate Account
      description: Use this endpoint to validate the payload for creating an account in Kraken. It accepts a request containing the necessary information for account creation but only performs the validation of that data. Nothing will be created in Kraken through this endpoint.
      summary: Validate the payload for creating an account in Kraken
      tags:
      - account_import
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateAccount'
            examples:
              ExamplePayload:
                value:
                  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:
                    - identifier: '1200060176720'
                      supply_type: ELECTRICITY
                      agreements:
                      - tariff_code: ELEC-1234-J
                        effective_from: '2019-08-01'
                      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
                        r

# --- truncated at 32 KB (479 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/edf-energy/refs/heads/main/openapi/edf-energy-account-import-api-openapi.yml