Origin 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.origin-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/OriginAccount'
        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/OriginAccount'
        required: true
      security:
      - DataImportViewerAPIKeyAuthentication: []
      - DRFKrakenTokenAuthentication: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OriginAccount'
          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:
              ExampleElectricityPayload:
                value:
                  import_supplier: TENTACLE_ENERGY
                  external_account_number: EXTERNAL-1234
                  unknown_occupier: false
                  communication_preference: ONLINE
                  document_accessibility: LARGE_PRINT
                  customers:
                  - given_name: Homer
                    family_name: Simpson
                    email: homer@simpson.com
                    mobile: 0488008221
                    landline: '+61280082213'
                    date_of_birth: '1959-01-01'
                    title: Mr
                    salutation: Hi
                    address:
                      administrative_area: NSW
                      country: AU
                      delivery_point_identifier: '51234567'
                      locality: Sydney
                      postal_code: '3000'
                      structured_street_address:
                        flat_or_unit_type: TNHS
                        house_number_1: '11'
                        street_name: CITY
                        street_type: RD
                  - given_name: Marge
                    family_name: Simpson
                    email: marge@simpson.com
                    mobile: 0488008221
                    landline: '+61288008221'
                    date_of_birth: '1960-01-01'
                    title: Mrs
                    salutation: Oh hai
                    deceased: Reported
                    unable_to_read_meters: true
                  - given_name: Lisa
                    family_name: Simpson
                    email: marge@simpson.com
                    mobile: 0488008221
                    landline: '+61388008221'
                    title: Miss
                    salutation: Hello
                  billing_name: The Simpsons
                  billing_sub_name: Fourth of their name
                  billing_customer_reference: Energy Supply
                  billing_attention_of: The Bursar
                  billing_address1: 11 Queen's Road
                  billing_address2: FLAT 1
                  billing_address3: ''
                  billing_address4: ''
                  billing_address5: NSW
                  billing_postcode: '3000'
                  billing_delivery_point_identifier: '51234567'
                  sales_channel: DIRECT
                  sales_subchannel: Disney
                  date_of_sale: '1989-12-17'
                  supply_addresses:
                  - supply_address:
                      administrative_area: NSW
                      country: AU
                      delivery_point_identifier: '51234568'
                      locality: Sydney
                      postal_code: '3070'
                      structured_street_address:
                        flat_or_unit_type: TNHS
                        house_number_1: '11'
                        street_name: CITY
                        street_type: RD
                    is_landlord: true
                    property_administrators:
                    - given_name: Mick
                      family_name: Jagger
                      email: mick.jager@rollingstones.com
                      mobile: 0488008221
                      landline: 0212345678
                    customer_at_supply_address_from_date: '2019-04-01'
                    meter_points:
                    - mpxn: '4103445577'
                      supply_start_date: '2019-01-01'
                      supply_end_date: null
                      access_details: Customer reports no access issues
                      hazard_details:
                      - Dog
                      meters:
                      - meter_serial_number: 12KD
                        installed_on: '2001-01-01'
                        removed_on: '2014-01-01'
                        registers:
                        - register_id: '1'
                        - register_id: '2'
                      - meter_serial_number: AB1234
                        installed_on: '2014-01-01'
                        removed_on: '2016-01-01'
                      - meter_serial_number: Z16N389556
                        registers:
                        - register_id: '1'
                          last_billed_to_date: '2019-08-01'
                        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: ESTIMATE
                          billed: true
                        - register_id: '1'
                          reading_date: '2019-04-20'
                          reading_value: '950.00'
                          reading_type: ROUTINE
                          billed: true
                      agreements:
                      - tariff_code: ELECTRICITY_PRODUCT
                        effective_from: '2019-04-01'
                        effective_to: '2019-06-01'
                        agreed_at: '2019-04-01T10:00:00Z'
                      - tariff_code: ELECTRICITY_PRODUCT
                        effective_from: '2019-06-01'
                  transfer_balance: 50.0
                  ledgers:
                  - current_statement_transactions:
                    - transaction_id: '1'
                      transaction_date: '2019-08-04'
                      amount: 10.0
                      type: REPAYMENT
                      reason: FULL_CREDIT_REFUND
                      payment_type: CHEQUE
                    - transaction_id: '2'
                      transaction_date: '2019-08-03'
                      amount: 20.0
                      type: PAYMENT
                      reason: ACCOUNT_CHARGE_PAYMENT
                      payment_type: DD_FINAL_COLLECTION
                    - transaction_id: '3'
                      transaction_date: '2019-08-02'
                      amount: 20.0
                      type: CREDIT
                      reason: IMPORTED_CREDIT
                    historical_statement_transactions:
                    - transaction_id: '4'
                      transaction_date: '2019-06-01'
                      amount: 10.0
                      type: PAYMENT
                      reason: ACCOUNT_CHARGE_PAYMENT
                      payment_type: CREDIT_CARD
                    - transaction_id: '5'
                      transaction_date: '2019-07-01'
                      amount: 10.0
                      type: PAYMENT
                      reason: ACCOUNT_CHARGE_PAYMENT
                      payment_type: DEBIT_CARD
                    last_statement_closing_date: '2019-07-31'
                    last_statement_issue_date: '2019-08-01'
                    last_statement_balance: 20.0
                    ledger_balance: 50.0
                  last_billed_to_date: '2019-08-01'
                  payment_instructions:
                  - vendor: WESTPAC
                    type: CARD
                    reference: SUPPLIER-179680385
                    valid_from: '2022-06-15'
                    card:
                      card_payment_network: VISA
                      card_type: CREDIT
                      last_digits: '1234'
                      expiry_month: 3
                      expiry_year: 2030
                  - vendor: WESTPAC
                    reference: SUPPLIER-142755174
                    type: DIRECT_DEBIT
                    valid_from: '2022-06-15'
                    bank_account:
                      account_holder: Chris Johnson
                      account_number: '12345678'
                      bsb: '111111'
                  payment_schedules:
                  - amount: 6.0
                    day_of_month: 10
                    frequency: MONTHLY
                    means: DD
                    start_date: '2018-01-01'
                    is_debt_repayment_plan: true
                  - amount: 60.0
                    day_of_month: 2
                    frequency: MONTHLY
                    means: DD
                    start_date: '2018-01-01'
                    is_debt_repayment_plan: false
                  notes:
                  - created_at: '2018-10-10T10:20:00Z'
                    body: This is a note
                    document_paths:
                    - document_path: /notes/1234/attachment.jpg
                  - created_at: '2018-10-10T10:20:00Z'
                    body: This is a pinned note
                    document_paths:
                    - document_path: /notes/1234/attachment.jpg
                    is_pinned: true
                  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: '1'
                    average_daily_usage: 18.44
                    is_reversed: true
                    total_consumption: 1045.3626354
                    total_consumption_cost: 250.88
                    total_supply_cost: 40.24
                    total_feed_in_energy: 303.35038
                    total_feed_in_cost: 33.3685418
                  - 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: '2'
                    average_daily_usage: 20.2
                    is_reversed: false
                    total_consumption: 123.456789
                    total_consumption_cost: 333.33
                    total_supply_cost: 20.2
                    total_feed_in_energy: 222.22222
                    total_feed_in_cost: 77.7777777
                  last_payment_review_date: '2019-06-01'
                  next_bill_due_date: '2019-11-20'
                  events:
                  - event_type: BEST_OFFER_CHECKED_IN_SAP
                    category: communications
                    subcategory: best_offer
                    occurred_at: '2011-05-12T13:33:22Z'
                    description: Best offer process ran for 2000179998952.
                  - event_type: MIXED_COMMS_PREF_IN_SAP
                    category: communications
                    subcategory: mixed_comms_preference
                    occurred_at: '2021-11-15T13:33:22Z'
                    description: Customer with mixed comms preferences in SAP.
                  - event_type: PRICE_CHANGE_SENT_IN_SAP
                    category: communications
                    subcategory: price_change
                    occurred_at: '2021-11-15T13:33:22Z'
                    description: July 2022 price change comm sent in SAP for 2000179998952.
                  - event_type: SHARED_EMAIL_7
                    category: communications
                    subcategory: mixed_comms_preference
                    occurred_at: '2021-11-15T13:33:22Z'
                    description: Customer with shared email scenario - PRINT for Account Level and EMAIL for Invoice.
                  - event_type: SUPPRESS_MIGRATION_COMMS
                    category: communications
                    subcategory: migration_comms
                    occurred_at: '2021-11-15T13:33:22Z'
                    description: Suppress migration comms for the account
                summary: Example electricity payload
              ExampleGasPayload:
                value:
                  import_supplier: TENTACLE_ENERGY
                  external_account_number: EXTERNAL-1234
                  unknown_occupier: false
                  supply_addresses:
                  - supply_address:
                      administrative_area: NSW
                      country: AU
                      delivery_point_identifier: '51234568'
                      locality: Sydney
                      postal_code: '3070'
                      structured_street_address:
                        flat_or_unit_type: TNHS
                        house_number_1: '11'
                        street_name: CITY
                        street_type: RD
                    customer_at_supply_address_from_date: '2019-04-01'
                    meter_points:
                    - mpxn: '5240459904'
                      supply_start_date: '2019-01-01'
                      supply_end_date: null
                      address:
                        flat_or_unit_type: F
                        flat_or_unit_number: '1'
                        floor_or_level_type: ''
                        floor_or_level_number: ''
                        building_or_property_name: Residential Wheke Energy Green Octopus with name = 60  chars
                        location_descriptor: ''
                        house:
                        - house_number: '11'
                          house_number_suffix: ''
                        lot_number: ''
                        street:
                        - street_name: QUEEN'S
                          street_type: RD
                          street_suffix: ''
                        suburb_or_place_or_locality: SYDNEY
                        state_or_territory: NSW
                        postcode: '2000'
                        delivery_point_identifier: '51234568'
                        melway_grid_reference: 277 H 10
                      access_details: Customer reports no access issues
                      hazard_details:
                      - Dog
                      dog_code: Savage
                      master_data:
                        customer_characterisation: Metropolitan Residential
                        customer_classification_code: RES
                        distribution_tariff: Volume
                        mirn_status: Commissioned
                        network_id: NSWWILTON
                        transmission_zone: 16
                        heating_value_zone: ABC
                        customer_classification_threshold: null
                        market: NSWACTGAS
                        baseload: null
                        temperature_sensitivity_factor: null
                      meters:
                      - meter_serial_number: 12KD
                        installed_on: '2001-01-01'
                        removed_on: '2014-01-01'
                        meter_status: No meter
                      - meter_serial_number: OTHER
                        installed_on: '2014-01-01'
                        removed_on: '2016-01-01'
                        billing_method: null
                        kpa_value: null
                        meter_installation_type: null
                        meter_multiplier: null
                        meter_measurement_unit: null
                        meter_position: BA
                        meter_read_frequency: null
                        meter_status: No meter
                        meter_type: G
                        meter_type_size_code: ABC
                        supply_point_code: Basic
                        supply_point_id: '1234567890123'
                        next_scheduled_read_date: null
                        number_of_dials_on_device: null
                      - meter_serial_number: NSWACT
                        billing_method: O
                        kpa_value: '12345.6789'
                        meter_installation_type: O
                        meter_multiplier: '123.45'
                        meter_measurement_unit: M
                        meter_position: BA
                        meter_read_frequency: Bi Monthly
                        meter_status: Turned on
                        meter_type: G
                        meter_type_size_code: null
                        supply_point_code: Basic
                        supply_point_id: '1234567890123'
                        next_scheduled_read_date: '2021-12-02'
                        number_of_dials_on_device: 4
                        transfer_readings:
                        - reading_date: '2019-08-01'
                          reading_value: '980.00'
                          reading_type: ROUTINE
                          prev_reading_date: '2019-06-20'
                          gas_meter_units: M
                          volume_flow: '20.00'
                          average_heating_value: '38.2'
                          pressure_correction_factor: '1.24'
                          consumed_energy: '400'
                          estimation_substitution_type: null
                          estimation_substitution_reason_code: null
                        reading_history:
                        - reading_date: '2019-06-20'
                          reading_value: '980.00'
                          reading_type: CUSTOMER
                          prev_reading_date: '2019-05-20'
                          gas_meter_units: M
                          volume_flow: '20.00'
                          average_heating_value: '38.2'
                          pressure_correction_factor: '1.24'
                          consumed_energy: '400'
                          estimation_substitution_type: null
                          estimation_substitution_reason_code: null
                          billed: true
                        - reading_date: '2019-05-20'
                          reading_value: '960.00'
                          reading_type: ESTIMATE
                          prev_reading_date: '2019-04-20'
                          gas_meter_units: M
                          volume_flow: '20.00'
                          average_heating_value: '38.2'
                          pressure_correction_factor: '1.24'
                          consumed_energy: '400'
                          estimation_substitution_type: null
                          estimation_substitution_reason_code: null
                          billed: true
                        - reading_date: '2019-04-20'
                          reading_value: '950.00'
                          reading_type: ROUTINE
                          prev_reading_date: null
                          gas_meter_units: null
                          volume_flow: null
                          average_heating_value: null
                          pressure_correction_factor: null
                          consumed_energy: null
                          estimation_substitution_type: null
                          estimation_substitution_reason_code: null
                          billed: true
                      meter_position: null
                      role_assignments:
                      - party: AGLGNNWO
                        role: DB
                      - party: ORIGINUSR
                        role: FRO
                      agreements:
                      - tariff_code: GAS_PRODUCT
                        effective_from: '2019-04-01'
                  last_billed_to_date: '2019-08-01'
                summary: Example gas payload
              ExampleUnmeteredElectricityPayload:
                value:
                  import_supplier: TENTACLE_ENERGY
                  external_account_number: EXTERNAL-1234
                  unknown_occupier: false
                  supply_addresses:
                  - supply_address:
                      administrative_area: NSW
                      country: AU
                      delivery_point_identifier: '51234568'
                      locality: Sydney
                      postal_code: '3070'
                      s

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