openapi: 3.2.0
info:
  title: Kraken Query API
  version: v1
  description: APIs for querying import status and retrieving data
servers:
- url: https://api.edfgb-kraken.energy/v1/
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: query
  x-title: Query APIs
  description: APIs for querying import status and retrieving data
paths:
  /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/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/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: []
components:
  schemas:
    GbrMeterPointStatusError:
      type: object
      properties:
        error:
          type: string
          title: Description of the error.
          description: <p>The details of the error.</p>
      required:
      - error
    ImportProcess:
      type: object
      properties:
        account_created_at:
          type: string
          format: date-time
          description: <p>The date and time that the account was created at.</p>
        external_account_number:
          type: string
          description: <p>The account number in the source system. This, along with the <code>import_supplier</code>, will be used to find the account in Kraken.</p>
          maxLength: 128
        kraken_account_number:
          type: string
          description: Account number
          maxLength: 128
      required:
      - external_account_number
    GbrMeterPointStatus:
      type: object
      properties:
        mpxn:
          type: string
          title: MPRN or MPAN of the meter point
          description: <p>The MPAN or MPRN of the meter point.</p>
        status:
          enum:
          - PRE_REGISTRATION
          - UNABLE_TO_REGISTER
          - AREGI_SENT
          - NOMINATION_SENT
          - NOMINATION_REJECTED
          - OFFER_RECEIVED
          - OFFER_REJECTED
          - REGISTRATION_REQUESTED
          - REGISTRATION_ACCEPTED
          - REGISTRATION_REJECTED
          - WITHDRAWAL_REQUESTED
          - REGISTRATION_WITHDRAWN
          - OBJECTION_RECEIVED
          - REGISTRATION_OBJECTED
          - MTD_RECEIVED
          - ON_SUPPLY
          - OPENING_READ_DISPUTED
          - MTD_DISPUTED
          - METER_EXCHANGE_REQUESTED
          - ERRONEOUS_GAIN_PROPOSED
          - ERRONEOUS_GAIN_ACCEPTED
          - ERRONEOUS_GAIN_REJECTED
          - ERRONEOUS_GAIN_CANCELLED
          - LOSS_REQUESTED_ERRONEOUS_GAIN
          - LOSS_PENDING_ERRONEOUS_GAIN
          - LOST_ERRONEOUS_GAIN
          - ERRONEOUS_LOSS_PROPOSED
          - ERRONEOUS_LOSS_ACCEPTED
          - ERRONEOUS_LOSS_REJECTED
          - ERRONEOUS_LOSS_CANCELLED
          - ET_REQUESTED
          - ET_ACCEPTED
          - ET_LOSS_PENDING
          - ET_COMPLETED
          - ET_CANCELLED
          - LOSS_REQUESTED
          - LOSS_PENDING
          - LOST
          - DISCONNECTED
          - ERRONEOUS_LOSS
          - LOSS_OBJECTION_REQUESTED
          - LOSS_OBJECTION_REMOVAL_REQUESTED
          - LOSS_OBJECTION_ACCEPTED
          - CLOSING_READ_DISPUTE
          - DE-ENERGISED
          - UNDERGOING_REGISTRATION
          - REGISTRATION_AT_RISK
          - GAIN_PENDING_DAP
          - LOSS_PENDING_DAP
          type: string
          x-spec-enum-id: fd4bdf1c2ccdefa1
          title: Kraken status of the meter point
          description: <p>The status of the meter point.</p>
          x-enum-descriptions:
            PRE_REGISTRATION: Pre-Registration
            UNABLE_TO_REGISTER: Unable to Register
            AREGI_SENT: AREGI Sent
            NOMINATION_SENT: Nomination Sent
            NOMINATION_REJECTED: Nomination Rejected
            OFFER_RECEIVED: Offer Received
            OFFER_REJECTED: Offer Rejected
            REGISTRATION_REQUESTED: Registration Requested
            REGISTRATION_ACCEPTED: Registration Accepted
            REGISTRATION_REJECTED: Registration Rejected
            WITHDRAWAL_REQUESTED: Withdrawal Requested
            REGISTRATION_WITHDRAWN: Registration Withdrawn
            OBJECTION_RECEIVED: Objection Received
            REGISTRATION_OBJECTED: Registration Objected
            MTD_RECEIVED: Meter Details Received
            ON_SUPPLY: On Supply
            OPENING_READ_DISPUTED: Opening Read Disputed
            MTD_DISPUTED: Meter Details Disputed
            METER_EXCHANGE_REQUESTED: Meter Exchange Requested
            ERRONEOUS_GAIN_PROPOSED: Erroneous Gain Proposed
            ERRONEOUS_GAIN_ACCEPTED: Erroneous Gain Accepted
            ERRONEOUS_GAIN_REJECTED: Erroneous Gain Rejected
            ERRONEOUS_GAIN_CANCELLED: Erroneous Gain Cancelled
            LOSS_REQUESTED_ERRONEOUS_GAIN: Loss Requested (Erroneous Gain)
            LOSS_PENDING_ERRONEOUS_GAIN: Loss Pending (Erroneous Gain)
            LOST_ERRONEOUS_GAIN: Lost (Erroneous Gain)
            ERRONEOUS_LOSS_PROPOSED: Erroneous Loss Proposed
            ERRONEOUS_LOSS_ACCEPTED: Erroneous Loss Accepted
            ERRONEOUS_LOSS_REJECTED: Erroneous Loss Rejected
            ERRONEOUS_LOSS_CANCELLED: Erroneous Loss Cancelled
            ET_REQUESTED: Erroneous Transfer Requested
            ET_ACCEPTED: Erroneous Transfer Accepted
            ET_LOSS_PENDING: Erroneous Transfer Loss Pending
            ET_COMPLETED: Erroneous Transfer Completed
            ET_CANCELLED: Erroneous Transfer Cancelled
            LOSS_REQUESTED: Loss Requested
            LOSS_PENDING: Loss Pending
            LOST: Lost
            DISCONNECTED: Disconnected
            ERRONEOUS_LOSS: Erroneous Loss
            LOSS_OBJECTION_REQUESTED: Loss Objection Requested
            LOSS_OBJECTION_REMOVAL_REQUESTED: Loss Objection Removal Requested
            LOSS_OBJECTION_ACCEPTED: Loss Objection Accepted
            CLOSING_READ_DISPUTE: Closing Read Disputed
            DE-ENERGISED: De-Energised
            UNDERGOING_REGISTRATION: Undergoing Registration
            REGISTRATION_AT_RISK: Registration At Risk
            GAIN_PENDING_DAP: Gain Pending (Debt Assignment Protocol)
            LOSS_PENDING_DAP: Loss Pending (Debt Assignment Protocol)
      required:
      - mpxn
      - status
  securitySchemes:
    DRFKrakenTokenAuthentication:
      type: apiKey
      in: header
      name: Authorization
      description: JWT-based authentication
    DataImportViewerAPIKeyAuthentication:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token "