The Account Import Process is the central unit for an account migrating into Kraken. It contains the payload that is used to generate the account as well as other metadata. Once an account is created from the import payload, a link is stored between the two, so it is always possible to see the original data from which the account was created.

The Import Supplier groups Account Import Process’s together and can be thought of as a representation of the source system, or a cohort of accounts in the source system. The import_supplier field in the import payload maps to the code associated with the Import Supplier.

An Import Supplier has a configuration associated with it that controls certain behaviour to do with the migration, for example, whether an email comm should be sent on account creation to the customer. Kraken devs will work with the client in determining the correct Import Supplier Config for the migration.

Use this end-point to validate a JSON payload of account information.

Request:

Sample payloads:

The request payload must be a single account object containing the following fields:

import_supplier (string, required)

Code of the import supplier where the account is meant to be imported to. The import supplier code will be provided to you.

external_account_number (string, required)

Original customer identifier. Can’t be longer than 128 characters.

unknown_occupier (bool, required)

Whether the account belongs to an unknown occupier. If the value True, no customers will be expected in the payload.

billing_name (string, optional)

Optional billing name to be used in the account. If provided, it’ll be used for producing statements. If not, the customer names will be used. Can’t be longer than 510 characters.

billing_address1 (string, optional)

Customer billing address. Can’t be longer than 512 characters.

billing_address2 (string, optional)

Customer billing address. Can’t be longer than 512 characters.

billing_address3 (string, optional)

Customer billing address. Can’t be longer than 512 characters.

billing_address4 (string, optional)

Customer billing address. Can’t be longer than 512 characters.

billing_address5 (string, optional)

Customer billing address. Can’t be longer than 512 characters.

billing_postcode (string, optional)

Valid UK postcode of the billing address

is_business (bool, optional)

Whether the account is a business account.

account_billing_options (dict, optional)

Billing options for an account. Only available for business customers.

period_start_day (integer, optional)

The day of the month that a billing period starts.

period_length (string, optional)

One of

MONTHLY or QUARTERLY

dunning_path (dict, optional)

Fields related to the dunning path that this account should go onto.

path_name (string, required)

Name of the dunning path to set this account onto. This must be agreed upon before migration and is client specific.

start_date (string, optional)

Date on which to start the dunning path. If no date is provided, the dunning path will be restarted on migration.

debt (dict, optional)

Fields related to debt on the account.

agency_name (string, optional)

Name of the debt agency.

start_date (date, optional)

Start date of the debt proceeding. If an agency_name is provided but no start_date, the migration date is used.

is_insolvent (boolean, optional)

Is the account currently in insolvency.

cais_reference (string, optional)

The CAIS reference for this account.

aged_debt (list, optional)

List of aged debt on this account.

This is essentially the debt position of the account. Typically we report this based on a grouping by date. We can then report on the delinquency at 30+ or 60+ days etc. As such we need to know when the debt was generated.

The data we receive will be converted into a historic record of the debt, which we will continue to age within Kraken.

How you report it to Kraken is up to you, the more granular you provide it, the more accurate the debt ageing will be. If you group debt, it will result in sharp changes as the group transitions across a reporting boundary. But if that’s all you can provide, it is better than nothing.

For example, if debt is £150 and the customer has not paid us £50 a month then we could expect the following:

• £50 - 2022-11-01

• £50 - 2022-10-01

• £50 - 2022-09-01

We would aggregate in our reporting to:

• £50 (0-30 days)

• £50 (31-60 days)

• £50 (61-365 days)

• £0 (365+ days)

In 2 months time (assuming they continue to not pay) this would be:

• £50 (0-30 days)

• £50 (31-60 days)

• £150 (61-365 days)

• £0 (365+ days)

debt_amount (decimal, optional)

Value of the aged debt.

due_date (date, optional)

Date on which the aged debt is due.

sales_channel (string, optional)

If provided must be one of:

DIRECT or PRICE_COMPARISON or TELESALES or DIGI_TELESALES or EVENTS or FIELD_SALES or AGGREGATOR or PARTNERSHIPS or NEW_TENANT or WORKPLACE_POP_UP or BROKER or PARENT_POWER or SUPPLIER_OF_LAST_RESORT or ACQUISITION

A default sales_channel can also be set on the import supplier - this is done by a member of the Kraken tech team when setting up an import supplier. These are the rules around how the sales channel gets assigned:

• If a default is set on the import supplier, and the import supplier is configured to override the value in the payload, the override will be used.

• If a default is provided on the import supplier, but the import supplier is configured not to override the value in the payload, then default will only be used if the sales_channel value in the payload is not provided or is an empty string.

• If no default sales channel is set on the import supplier and the import supplier is set to override the value in the payload, then we default to using ACQUISITION as the sales_channel.

• If a default is not set on the import supplier and the import supplier is not set to override the value in the payload and there is no value in the payload, then the sales channel will be set to an empty string.

sales_subchannel (string, optional)

Free text to be used as sales information of the account.

If the import supplier is set to override the value in the payload, then the import supplier name will be used as the value for the sales_subchannel.

transfer_balance (decimal, optional)

The balance that will be transferred over to Kraken, in pounds. Credit balances must be positive, debit balances must be negative. Note that any transactions related to a prepay meter (i.e. those with a to_prepay_meter_serial_number) should not be included in this balance.

last_statement_balance (decimal, optional)

The balance of the latest statement, in pounds, issued by the previous supplier. Credit balances must be positive, debit balances must be negative. Note that, as for the transfer_balance, any transactions related to a prepay meter should not be included in this balance.

last_billed_to_date (date, optional)

Date up to which consumption has been billed to. This is optional but must appear at either the account level or for all on-supply (i.e. don’t have a removed_on date on the meter) individual gas meters and electricity registers, or both. If a value is provided on both the account and the meter/register then the meter/register last_billed_to_date’s will be used for the purposes of validating consumption against the meter point.

If the account has never been billed before, this should be the supply start date for the account and Kraken will bill from then.

This value is also used for the last_statement_closing_date and last_statement_issue_date when those values are not provided. In that case, if it is provided at the meter and register level, the earliest such value is used.

last_statement_closing_date (date, optional)

Date when the last statement was closed.

Kraken will create an initial closed statement for all historical transactions, and will use this value for its closing date. This also means that Kraken will bill any transactions (but not necessarily consumption) from the day after this date.

For backwards compatibility, when this value is omitted the importer will tolerate either current or historical transactions (but not both!) being on the last_billed_to_date and adjust appropriately. However, if last_statement_closing_date is supplied, historical transactions can be on or before this date, but any current transactions must be strictly after this date.

last_statement_issue_date (date, optional)

Date when the last statement was issued. If this date is not given, last_billed_to_date will be used as the issue and close date of the initial statement. This field is required if historical transactions are supplied

next_bill_due_date (date, optional)

Date of when it’s expected to issue the next bill.

smart_read_frequency (string, optional)

One of MONTHLY or DAILY or HALF_HOURLY or DENIED.

smart_read_cycle_day (integer, optional)

Smart meter billing day of the month. Values between 1 to 28.

complaints (array, optional)

Open complaints that have been raised by the customer.

created_at (datetime, required)

The datetime the complaint was created at.

type_of_complaint (string, required)

The type of the complaint. One of: B10_FEED_IN, B11_PAYMENT, B12_PRICING, B13_BILLING_METER_UNRELATED, B14_BILLING_SMART_METER, B15_SWITCHING_METER_UNRELATED, B16_SWITCHING_SMART_CREDIT, B17_SWITCHING_SMART_PREPAY, B18_METER_CLASSIC_CREDIT, B19_METER_SMART_CREDIT, B20_METER_CLASSIC_PREPAY, B21_METER_SMART_PREPAY, B22_OTHER, B5_DEBT_NON_PREPAY, B6_DEBT_PREPAY, B7_SALES_DIRECT, B8_SALES_THIRD_PARTY, B9_CUSTOMER_SERVICE

subtype_of_complaint (string, required)

The subtype of the complaint. One of: B10_DELAY_IN_PAYMENT, B10_DELAY_IN_REGISTRATION, B10_DISPUTED_READING, B11_DD_INSTRUCTIONS, B11_DD_SCHEDULE, B11_MISSED_DD, B11_ONE_OFF_PAYMENT, B11_OUTGOING_PAYMENTS, B11_PAYMENT_ADEQUACY, B11_REFERRAL, B12_TARIFF_FLEX_INCREASE, B12_TARIFF_INCORRECT, B12_TARIFF_RENEWAL, B13_ACQUISITION_BILLING, B13_BACK_BILLING, B13_CATCH_UP_BILLING, B13_DISPUTED_READING, B13_ESTIMATED, B13_FINAL_BILL, B13_INCORRECT_BILLING, B13_LATE_BILL, B13_NO_BILLS_ISSUED, B13_REFUND, B13_WHD, B14_BACK_BILLING, B14_CATCH_UP_BILLING, B14_DISPUTED_READING, B14_ESTIMATED, B14_FINAL_BILL, B14_INCORRECT_BILLING, B14_LATE_BILL, B14_NO_BILLS_ISSUED, B14_REFUND, B14_SMART_READINGS_NOT_TAKEN, B14_WHD, B15_CANCELLED_CONTRACT_NOT_ACTIONED, B15_CROSSED_METER, B15_DISPUTED_READING, B15_ERRONEOUS_TRANSFER, B15_INCORRECT_MPAN, B15_INCORRECT_MPRN, B15_OBJECTED, B15_REJECTION, B15_SWITCH_NOT_ACTIONED, B16_CANCELLED_CONTRACT_NOT_ACTIONED, B16_DISPUTED_READING, B16_ERRONEOUS_TRANSFER, B16_INCORRECT_MPAN, B16_INCORRECT_MPRN, B16_INCORRECT_MTD, B16_OBJECTED, B16_REJECTION, B16_SWITCH_NOT_ACTIONED, B17_CANCELLED_CONTRACT_NOT_ACTIONED, B17_DISPUTED_READING, B17_ERRONEOUS_TRANSFER, B17_INCORRECT_MPAN, B17_INCORRECT_MPRN, B17_INCORRECT_MTD, B17_OBJECTED, B17_REJECTION, B17_SWITCH_NOT_ACTIONED, B18_METER_FAULT_ACCURACY, B18_METER_READINGS_INCORRECT, B18_METER_READINGS_TMA, B18_NEW_CONNECTION, B18_SITEWORKS_APPOINTMENT_ERROR, B18_SITEWORKS_CUSTOMER_SERVICE, B18_SITEWORKS_METER_FAULT, B18_SITEWORKS_MISSED_APPOINTMENT_MOP, B18_SITEWORKS_MISSED_APPOINTMENT_OPS, B19_IN_HOME_DISPLAY, B19_METER_FAULT_ACCURACY, B19_METER_READINGS_INCORRECT, B19_METER_READINGS_TMA, B19_NEW_CONNECTION, B19_OUTGOING, B19_SITEWORKS_APPOINTMENT_ERROR, B19_SITEWORKS_CUSTOMER_SERVICE, B19_SITEWORKS_METER_FAULT, B19_SITEWORKS_MISSED_APPOINTMENT_MOP, B19_SITEWORKS_MISSED_APPOINTMENT_OPS, B19_SMART_READINGS_NOT_TAKEN, B19_SMART_TARIFF, B20_KEY_CARD_NOT_RECEIVED, B20_KEY_CARD_NOT_WORKING, B20_METER_FAULT_ACCURACY, B20_METER_READINGS_INCORRECT, B20_METER_READINGS_TMA, B20_NEW_CONNECTION, B20_SITEWORKS_APPOINTMENT_ERROR, B20_SITEWORKS_CUSTOMER_SERVICE, B20_SITEWORKS_METER_FAULT, B20_SITEWORKS_MISSED_APPOINTMENT_MOP, B20_SITEWORKS_MISSED_APPOINTMENT_OPS, B21_IN_HOME_DISPLAY, B21_KEY_CARD_NOT_RECEIVED, B21_KEY_CARD_NOT_WORKING, B21_METER_FAULT_ACCURACY, B21_METER_READINGS_INCORRECT, B21_METER_READINGS_TMA, B21_NEW_CONNECTION, B21_SITEWORKS_APPOINTMENT_ERROR, B21_SITEWORKS_CUSTOMER_SERVICE, B21_SITEWORKS_METER_FAULT, B21_SITEWORKS_MISSED_APPOINTMENT_MOP, B21_SITEWORKS_MISSED_APPOINTMENT_OPS, B21_SMART_READINGS_NOT_TAKEN, B22_OTHER, B5_ACQUISITION_DEBT, B5_DEBT_RECOVERY, B5_DISCONNECTIONS, B5_DISPUTING_DEBT, B5_PAYMENT_PLAN, B6_ACQUISITION_DEBT, B6_DEBT_RECOVERY, B6_DISCONNECTIONS, B6_DISPUTING_DEBT, B6_DISPUTING_DEBT_LIABILITY, B6_PAYMENT_PLAN, B6_PPM_WARRANT_ISSUES, B6_PP_REMOTE_SWITCH, B6_SELF_DISCONNECTION, B7_MIS_SELLING_ONLINE, B7_MIS_SELLING_PHONE, B8_CUSTOMER_SERVICE, B8_MIS_SELLING_FACE_TO_FACE, B8_MIS_SELLING_ONLINE, B8_MIS_SELLING_PHONE, B9_CUSTOMER_SERVICE, B9_GDPR_BREACH, B9_WAIT_TIME, B9_WEBSITE_ISSUES,

official_reference_number (string, optional)

The official reference number of the complaint if it is an official complaint.

official_entity (string, optional)

The official entity of the complaint if it is an official complaint. One of: EHU, OMBUDSMAN

official_status (string, optional)

The official status of the complaint if it is an official complaint. One of: CASE CLOSED, CASE CLOSED (FCR), DECISION ACCEPTED, DECISION APPEALED, DECISION ISSUED, DECISION ISSUED (CUSTOMER RESPONSE NEEDED), DISPUTE RAISED, PREPARE CASE, PROPOSAL ACCEPTED (FCR), PROPOSAL ISSUED (FCR), SUCCESSFUL DISPUTE, UNDER INVESTIGATION

complainant_name (string, required)

The name of the complainant. This should be the name of a customer related to the account unless the complaint was raised by another person.

complainant_email (string, required)

The email address of the complainant. This should be the email address of a customer related to the account unless the complaint was raised from a different email address.

has_chsr_letter_been_sent (bool, required)

Whether the customer has been sent a CHSR letter for the complaint.

has_eight_week_letter_been_sent (bool, required)

Whether the customer has been sent an eight week letter for the complaint.

complaint_contacts (array, required)

The customer contacts related to the complaint.

created_at (datetime, required)

The datetime the complaint contact was created at.

communication_method (string, required)

The method of communication used to contact regarding the complaint. One of LANDLINE, MOBILE, EMAIL, POST

communication_source (string, required)

The source of communication used to contact regarding the complaint. One of TELEPHONE, ONLINE, PERSON, POST, SOCIAL_MEDIA, CUSTOMER_SURVEY

status (string, required)

The status of the complaint at the time the contact was made to track status changes, e.g. resolution. One of OPEN, NO_CONTACT, REOPENED, DEADLOCK

body (string, required)

The body of text or a summary of the contact regarding the complaint.

company_number (string, optional)

Company number for a business account. Can’t be longer than 8 characters.

business_type (string, optional)

Business type of a business account. One of SOLE_TRADER or LTD or PARTNERSHIP or CHARITY or PLC or LLP or TRUST or TRADING_AS or GOVERNMENT or NON_PROFIT or CHURCH

communication_preference (string, optional)

One of ONLINE or PRINT. The default is ONLINE.

document_accessibility (string, optional)

One of LARGE_PRINT or BRAILLE or SPOKEN.

account_campaigns (array, optional)

Campaign to add to an account. This is a category an account can be in which will be highlighted on the main account view.

campaign_name (string, required)

Name of the campaign. Options need to be passed to the Kraken Technologies team beforehand.

campaign_note (string, optional)

This will create an account note, and will link it from the account campaign.

expiry_date (date, optional)

Date from which the campaign is no longer valid.

contracts (array, optional)

Only contracts valid since last billed (including future ones where notified).

Given historical contracts will only be imported into Kraken as “import agreements” if there are no gaps or overlaps on their effective dates.

mpxn (string, required)

MPAN or MPRN of the meter point this contract is for.

tariff_code (string, required)

Code of the contract tariff. Must match an existing tariff code of an active product.

effective_from (date, required)

Date the contract is valid from (inclusive).

effective_to (date, optional)

Date the contract is valid to (exclusive).

agreed_at (datetime, optional)

Datetime the contract was agreed at.

is_hh (bool, optional)

Set to true if the contract is billed half-hourly

bespoke_tariff_rates (array, optional)

Details on a bespoke tariff, if applicable. Usually only relevant for business accounts.

meter_serial_number (string, required)

Meter serial number to which the bespoke tariff applies

standing_charge (decimal, required)

The value in pence per day of the charge (excluding VAT).

unit_rate (decimal, optional)

The value in pence per kWh of the charge (excluding VAT). This field should be used for gas meters.

payment_method (string, optional)

The payment method for the bespoke rate. Only used for payment price switching enabled bespoke rates. One of DD (Direct debit) or NDD (Non-direct debit) or PP (Prepayment).

registers (array, optional)

For elec meters, the unit rates are provided on a per register basis in this array

register_id (string, optional)

The identifier of the register to which this unit rate applies.

rate_type (string, optional)

The rate type of the unit rate. One of STANDARD or ECO7_DAY or ECO7_NIGHT. If the register_id is not provided, the rate type must be provided instead.

unit_rate (decimal, required)

The value in pence of the charge (excluding VAT).

start_time (time, optional)

The time of day at which this rate comes into force for HH billed contracts. N/A for NHH and optional for single rate HH.

commission_contracts (array, optional)

Commission contract (TPI) per meter point.

mpxn (string, required)

MPAN or MPRN of the meter point this contract is for.

effective_from (date, required)

Date the contract is valid from (inclusive).

effective_to (date, required)

Date the contract is valid to (exclusive).

affiliate_organisation_name (string, required)

Name of the affiliate organisation this contract is with.

commission_type (str, optional)

Type of commission. Defaults to UNIT_RATE_UPLIFT.

value (decimal, required)

The value of the commission (e.g. unit rate uplift) in pence.

status (string, required)

Whether a contract is fully paid up or still needs payment (is payable). One of PAID or PAYABLE

current_statement_transactions (array, optional)

Transactions that are meant to be billed by Kraken. These could be the transactions that took place after the last statement was issued or all of the transactions that have taken place since the account was created if it has never been billed before.

The value of these transactions, plus the last_statement_balance, must add up to the transfer_balance. Note that any transactions related to a prepay meter are not included in the above check.

A note on prepay consumption charges:

Transactions of type CHARGE with a consumption reason (Electricity or Gas) that are marked as being “to a prepay meter” indicate a consumption charge that is known to have been carried out _by_ the prepay meter (i.e. a meter-driven charge); Such a transaction definition is _not_ appropriate for migrating a consumption charge carried out by the supplier that was/will be reconciled against the meter’s behaviour (i.e. an account-driven charge). The latter are not expected to be explicitly migrated, as they should always be included in both an issued bill and the balances reported in the set of prepay_details for the relevant prepay meter.

transaction_id (string, required)

Unique internal identifier for this transaction.

transaction_date (date, required)

Date when the transaction was effective.

amount (decimal, required)

Number to 2 decimal places (pounds) e.g. if the customer has a consumption charge worth £23.43, this equates to a transaction of type CHARGE of £23.43. Payments and repayments must be positive numbers. Generally charges and credits are also positive, but may be negative to represent reversed charges or credits, or if an incorrect estimated reading has resulted in a negative consumption charge.

type (string, required)

One of CHARGE or CREDIT or PAYMENT or REPAYMENT or TRANSFER.

The amount of a CHARGE or REPAYMENT transaction is subtract from the last_statement_balance when validating the transfer_balance.

The amount of a CREDIT or PAYMENT transaction is added to the last_statement_balance when validating the transfer_balance.

TRANSFER transactions are neutral, as they represent transfers between different ledgers in a single (Kraken) account; they have no impact on the validation of the transfer_balance.

reason (string, optional)

If the transaction is of PAYMENT type, one of the following: ACCOUNT_CHARGE_PAYMENT or BALANCE_ADJUSTMENT or GENERAL_CREDIT or SSD_PAYMENT or DEBT_REPAYMENT.

If the transaction is of REPAYMENT type, one of the following: FULL_CREDIT_REFUND or PARTIAL_CREDIT_REFUND or ET_REFUND or FINAL_BALANCE_SETTLEMENT or MISTAKEN_PAYMENT_TAKEN or COMPLAINT_COMPENSATION or INDEMNITY_CLAIM or FAILED_PAYMENT.

If the transaction is of CREDIT type, one of the following: ACCURACY_TEST_ADJUSTMENT or CUSTOMER_SERVICE_GESTURE or DISC_WARM_HOME_DISCOUNT or EXIT_FEE_REFUND or FEED_IN_TARIFF_PAYMENT or GAS_NETWORK_COMPENSATION or JOINING_REWARD or LOYALTY_REWARD or MISSED_SAVINGS or REFERRAL_REWARD or RETURNED_BUSINESS_PREPAYMENT or SALES_COMPENSATION or EXPORT_TARIFF_PAYMENT or WRITE_OFF_BANKRUPTCY or WRITE_OFF_DECEASED or WRITE_OFF_DRO or WRITE_OFF_IVA or WRITE_OFF_NEGLIGIBLE_VALUE or WRITE_OFF_UNRECOVERABLE_DEBT or WRITE_OFF_PAST_BILLABLE or WRITE_OFF_RECOVERY_DISCOUNT or WITHDRAWAL_NOT_ACTIONED or STAFF_DISCOUNT or DIRECT_DEBIT_DISCOUNT or STANDARDS_OF_PERFORMANCE_ET_COMMS_OVERDUE or STANDARDS_OF_PERFORMANCE_ET_LOSS_UNRESOLVED or STANDARDS_OF_PERFORMANCE_ET_GAIN_UNRESOLVED or STANDARDS_OF_PERFORMANCE_CUSTOMER_NOT_RETURNED or ADDITIONAL_SOP_PAYMENT_ET_COMMS_OVERDUE or ADDITIONAL_SOP_PAYMENT_ET_LOSS_UNRESOLVED or ADDITIONAL_SOP_PAYMENT_ET_GAIN_UNRESOLVED or ADDITIONAL_SOP_PAYMENT_CUSTOMER_NOT_RETURNED or STANDARDS_OF_PERFORMANCE_APPOINTMENTS_STANDARD_VISIT_ELEC or STANDARDS_OF_PERFORMANCE_APPOINTMENTS_FAULTY_METER_ELEC or STANDARDS_OF_PERFORMANCE_APPOINTMENTS_PREPAY_METER_ELEC or STANDARDS_OF_PERFORMANCE_APPOINTMENTS_RECONNECTION_ELEC or STANDARDS_OF_PERFORMANCE_APPOINTMENTS_STANDARD_VISIT_GAS or STANDARDS_OF_PERFORMANCE_APPOINTMENTS_FAULTY_METER_GAS or STANDARDS_OF_PERFORMANCE_APPOINTMENTS_PREPAY_METER_GAS or STANDARDS_OF_PERFORMANCE_APPOINTMENTS_RECONNECTION_GAS or STANDARDS_OF_PERFORMANCE_REFUND_ISSUED_LATE or STANDARDS_OF_PERFORMANCE_FINAL_BILL_ISSUED_LATE or ADDITIONAL_SOP_PAYMENT_APPOINTMENTS or BALANCE_ADJUSTMENT or BALANCE_TRANSFER or BANK_TRANSFER or CUSTOMER_REIMBURSEMENT or DISPUTED_CARD_PAYMENTS or IMPORTED_CREDIT or MARKET_RESEARCH_CLUB_REWARD or OFFSET or PREPAY_DEBT_ADJUSTMENT or REINSTATED_DIRECT_DEBIT or REVERSED_ACCOUNT_CHARGE or DATA_IMPORT_BALANCE_TRANSFER or BALANCE_TRANSFER_FOR_FINAL_BILLED_ACCOUNT or SUPPLEMENTARY_LEDGER_BALANCE_TRANSFER or SHARE_OF_PROFITS or GOODWILL_PAYMENT or DEPOSIT_REFUND or ERRONEOUS_TRANSFER_REFUND or DEBIT_BALANCE_TRANSFER or TARIFF_PRICE_ADJUSTMENT_GOODWILL or ECONOMY_7_DIFFERENCE or WRITE_OFF_BACK_BILLING or WRITE_OFF_MISSED_PAYMENT_DELETION or TARIFF_DISCOUNT or STANDARDS_OF_PERFORMANCE_ERRONEOUS_TRANSFER or ADDITIONAL_SOP_PAYMENT_ERRONEOUS_TRANSFER or EBSS_CREDIT

If the transaction is of CHARGE type, one of the following: DEFAULT or BALANCE_TRANSFER or SUPPLEMENTARY_LEDGER_BALANCE_TRANSFER or CREDIT_BALANCE_DONATED_TO_CHARITY or DIRECT_DEBIT_REFUND_BALANCING or METERING_JOB_BUSINESS or METERING_JOB_NATIONAL_GRID or METERING_JOB_SMS or NEST_LEARNING_THERMOSTAT_RENTAL or PENALTY_CHARGE or PREPAY_DEBT_ADJUSTMENT or REVERSED_ACCOUNT_CREDIT or BUSINESS_PREPAYMENT or WRITE_BACK or EARLY_EXIT_FEE or DCA_CHARGE or EBSS_CHARGE_REVERSAL or Electricity or Gas.

If the transaction is of TRANSFER type, one of the following: PREPAY_DEBT_ADJUSTMENT

If a reason other than the above is given for transaction types CHARGE and CREDIT, this will be displayed in Kraken and to the customer.

reference (string, optional)

Transaction reference. Could be an external id to help identify this transaction

to_prepay_meter_serial_number (string, optional)

The serial number of the prepay meter to which this transaction relates. Transactions not related to a prepay meter should not provide this field.

Note that only certain types of prepay-related transactions are valid. These are:

• Prepay vends that occurred since the last statement. These must have a type of PAYMENT and payment type of CASH. Additionally, they may only be included in current_statement_transactions.

• Prepay financial imbalances, which represent any discrepancy between the balance on the meter and the balance in the pre-migration billing system. These must have a type of CREDIT or CHARGE and a reason of DATA_IMPORT_BALANCE_TRANSFER. Additionally, they may only be included in historical_statement_transactions. As an example, if the billing system contains a debt of £100 that has not yet been loaded onto the meter, this should be represented as a charge of £100 (with the reason listed above).

payment_type (string, optional)

If the transaction is of PAYMENT type, one of the following: DD_FIRST_COLLECTION or DD_REGULAR_COLLECTION or DD_RE_PRESENTATION or DD_FINAL_COLLECTION or CREDIT_CARD or DEBIT_CARD or CHEQUE or BACS_DEPOSIT or ALLPAY_CASH or ALLPAY_CARD or ALLPAY_CHEQUE or PAYPOINT_CASH or PAYPOINT_CARD or PAYPOINT_CHEQUE or PAYZONE or POST_OFFICE_CASH or POST_OFFICE_CHEQUE or POST_OFFICE_SAVINGS_STAMPS or POST_OFFICE_CARD or DCA_COLLECTION or BRISTOL_POUND or CASH or FUEL_DIRECT.

If the transaction is of REPAYMENT type, one of the following: DIRECT_CREDIT or CARD_REFUND or BACS or CHEQUE.

If the PAYMENT was a prepayment top-up vend, payment_type should be CASH.

display_note (string, optional)

If the transaction is of CREDIT or CHARGE type, the customer-facing note that can be displayed in a statement or email to the customer.

note (string, optional)

For internal use only. Note is displayed on the support site and not visible in the bills.

customers (array, optional)

given_name (string, optional)

Required for business accounts. Can’t be longer than 255 characters.

family_name (string, optional)

Optional for business accounts but required for domestic accounts. If not provided for Business accounts, Business will be used as a default value. Can’t be longer than 255 characters.

email (string, optional)

Customer’s email they’ll use for logging into the online portal. Can’t be longer than 254 characters.

role (string, optional)

Role for the customer to have on the provided account. For details of the available choices and default value, see Customer roles.

mobile (string, optional)

Customer’s personal mobile number. Can’t be longer than 32 characters.

landline (string, optional)

Customer’s landline phone number. Can’t be longer than 32 characters.

date_of_birth (date, optional)

title (string, optional)

Preferred title by the customer. Can’t be longer than 20 characters.

salutation (string, optional)

Preferred salutation by the customer. Can’t be longer than 128 characters.

deceased (string, optional)

One of Reported or Confirmed.

unable_to_read_meters (bool, optional)

Whether the customer is unable to read their meters themselves. It will be False by default.

credit_score (integer, optional)

A number between 0 and 9999 representing the customers credit score.

credit_risk_bracket (string, optional)

One of LOW, MID, HIGH or UNKNOWN.

psr (array, optional)

Priority service register. Includes fields shown below in green.

elec_industry_code (string, optional)

Must be a valid electricity industry code.

gas_industry_code (string, optional)

Must be a valid gas industry code.

effective_from (date, optional)

Date the PSR entry is effective from.

effective_to (date, optional)

Date the PSR entry is effective to.

additional_information (string, optional)

Additional information for this PSR entry, e.g. a language in case the customer does not speak English.

customer_preferences (dict, optional)

opted_into_sms (bool, optional)

Whether the customer is opted into sms communications. It will be False by default.

opted_into_recommended (bool, optional)

Whether the customer is opted into non-critical such as Direct Debit and meter reading reminders. It will be True by default.

opted_into_updates (bool, optional)

Whether the customer is opted into non-critical emails other than the recommended ones. It will be False by default.

opted_into_third_parties (bool, optional)

Whether the customer is opted into third party partner companies. It will be False by default.

opted_into_offers (bool, optional)

Whether the customer is opt into offers. It will be False by default.

opted_into_associated_companies (bool, optional)

Whether the customer is opted in to messages from associated companies. It will be False by default.

is_user_psr_consent_obtained (bool, optional)

Whether the customer consented to PSR data being used.

partner_password (string, optional)

PSR password for the customer. Cannot be more than 10 characters.

metadata (array, optional)

An array of key value pairs for storing generic metadata relating to a customer.

key (string, required)

Key on which the metadata will be stored on.

value (dict, required)

A json object containing any arbitrary piece of data to store in relation to the customer.

historical_statement_transactions (array, optional)

If historical transactions are given, their value must add up to the given last_statement_balance. Note that any transactions related to a prepay meter are not included in the above check.

For a description of the fields, see current_statement_transactions.

payment_schedules (array, optional)

List of active payment schedules linked to the account.

means (string, required)

One of DD or CARD or MANUAL This corresponds to the 3 different types of payment schedules Kraken supports: Card, Direct Debit, or manual payments, i.e. those where the customer initiates the payment. The actual means are unknown, but could be cash/cheque or bank transfers.

frequency (string, optional)

One of MONTHLY or QUARTERLY or WEEKLY or FORTNIGHTLY. Required for fixed schedules.

start_date (date, required)

The payment schedule start date. If WEEKLY or FORTNIGHTLY is chosen as the frequency the start_date determines the day of the week the payment is taken.

end_date (date, optional)

The payment schedule end date. This field should be empty if the payment schedule is ongoing.

day_of_month (integer, optional)

Integer, between 1 and 28. Defaults to null. Required for fixed schedules.

amount (decimal, optional)

Positive number with 2 decimal places (pounds). Required for schedules with no trigger, or where the trigger is REGULAR. Defaults to "0.0" if not provided.

If a debt_repayment_element is given, the amount must contain the regular schedule amount + the debt_repayment_element.

trigger (string, optional)

Either BILL or REGULAR. If not provided we create a fixed schedule, i.e. trigger = REGULAR. A BILL triggered schedule creates a ledger balance clearing payment when a statement or invoice is issued.

paid_by (string, optional)

FUEL_DIRECT or CUSTOMER. Defaults to the CUSTOMER if not provided.

debt_repayment_element (decimal, optional)

The contribution to the amount in addition to the regular fixed schedule payment amount.

debt_repayment_element = amount - fixed schedule amount

If passed in, debt_repayment_end_date must also be passed in.

debt_repayment_end_date (date, optional)

Date on which the debt repayment will no longer be taken in addition to the regular payment.

payment_instructions (array, optional)

List of payment instructions to create for the account.

vendor (str, required)

Please contact the tech team for the names of the vendors available to you.

reference (str, required)

The reference of the mandate as known by the vendor. Can’t be longer than 512 characters.

customer_reference (str, optional)

Although not required for payment instructions to take payments, if provided it keeps Kraken’s data in sync with customer’s account in the payment vendor’s systems.

type (str, required)

One of DIRECT_DEBIT and CARD.

valid_from (date, optional)

Defaults to today if not provided.

contribution_agreements (array, optional)

Contribution Agreements

scheme (string, required)

Scheme code

interval (string, required)

Charge Interval. Options are: - MONTHLY - QUARTERLY

amount (decimal, required)

Amount as a decimal. Eg. 10.00. The amount to contribute.

active_period_start_date (date, required)

Date the agreement is valid from.

active_period_end_date (date, optional)

Date the agreement is valid to.

periods (array, optional)

Previous and current contribution periods.

start_date (date, required)

Date the period is valid from.

end_date (date, required)

Date the period is valid to.

fulfilled_at (datetime, optional)

Datetime the amount was charged for

deposit_agreements (array, optional)

Deposit Agreements. Only allow to migrate 1 deposit agreement atm

deposit_amount (decimal, required)

Amount as a decimal. Eg. 500.00.

reason (string, required)

Deposit reason.

accepted_at (datetime, optional)

Datetime when the customer accepted to pay the deposit.

fulfilled_at (datetime, optional)

Datetime when the customer fulfilled the deposit.

last_interest_date (date, optional)

Date when the last interest was calculated. Only allowed when agreement is fulfilled. fulfilled_at cannot be greater than last_interest_date.

payment_plans (array, optional)

Active payment plans.

strategy_name (string, required)

The name of the strategy the plan uses. Please discuss with the tech team to determine the strategy to use.

payments (array, required)

The payments that form the payment plan.

payment_date (date, required)

The date the payment should be made.

total_amount (integer, required)

The total amount the payment is for in pence.

amount_components (array, required)

The components of the payment that form the total amount. Can be an empty array if the payment is not broken into components. The amounts must sum up to the total_amount.

component_type (string, required)

The type of the component. The options will depend on the strategy so please discuss with the tech team to determine the correct values.

amount (integer, required)

The amount of the component in pence.

accepted_at (datetime, required)

The datetime (with timezone) the payment plan was accepted.

schedule_means (string, required)

One of DD or CARD or MANUAL. The payment type of the schedule used to generate the planned payments. This corresponds to the 3 different types of payment schedules Kraken supports.

last_payment_review_date (date, optional)

Date when the last payment review took place, must be in the past. If this is provided then payment_adequacy_changes below must not be included in the payload. Providing this date will create a single payment adequacy change against the account for this date. Default values will be entered for the other fields on the payment review as follows:

• last_payment_review_date - 0

• new_direct_debit - 0

• existing_direct_debit_payment - 0

• current_balance - 0

• target_balance - 0

• balance_adjustment - 0

• average_monthly_charge - 0

• average_monthly_elec_charge - 0

• average_monthly_gas_charge - 0

• applied_at - midnight of the last_payment_review_date

• should_not_be_applied_reason - Historical record created as part of the migration of this account into Kraken. No value other that of the last payment review date was provided. This item serves as a historical record that a PA review took place in the previous system.

• created_at - midnight of the last_payment_review_date

payment_adequacy_changes (array, optional)

List of completed payment adequacy reviews for this account. If this is provided then the last_payment_review_date must not be provided.

new_direct_debit (integer, required)

The recommended new credit card or Direct Debit payment amount in pence.

existing_direct_debit_payment = (integer, required)

The credit card or Direct Debit amount in pence at the time of review.

current_balance (integer, required)

Account balance in pence at the date of the payment adequacy run.

target_balance (integer, required)

The target balance for the account in pence after 12 months.

balance_adjustment (integer, required)

The adjustment in pence on top of the average monthly charge, to be used as the new direct debit payment. This can be 0 if the difference between current and target balance is small enough to not act on.

average_monthly_charge (integer, required)

The average monthly charge for this account in pence, if we sum all yearly charges and divide them by 12.

average_monthly_elec_charge (integer, required)

The average monthly electricity charge for this account in pence, if we sum all yearly electricity charges and divide them by 12.

average_monthly_gas_charge (integer, required)

The average monthly gas charge for this account in pence, if we sum all yearly gas charges and divide them by 12.

applied_at (datetime, optional)

The datetime the payment adequacy change was applied and the customer was notified. This should be None if payment adequacy change was not applied.

should_not_be_applied_reason (str, optional)

The reason why this payment adequacy change was not applied. This should be None if it was applied.

created_at (datetime, required)

The datetime the payment adequacy change was created.

references (array, optional)

List of account references for a variety of use cases.

namespace (str, required)

The namespace refers to the particular context the reference exists in. For example, tentacle-energy.allpay-client-reference-numbers.

value (str, required)

The unique identifier for the account.

notes (array, optional)

List of notes linked to the account. A body or a document_path must be provided.

body (string, optional)

Should include who/what created the note if this is required.

document_paths (array, optional)

A list of paths to documents attached to the note.

document_path (string, required)

S3 relative path of document attached to the note.

created_at (datetime, optional)

is_pinned (boolean, optional)

If set to true, this will make the note a pinned note.

unpin_at (datetime, optional)

When the pinned note should be unpinned. Has to be later than created_at` if this is provided. Has no effect if the note is not pinned.

statements (array, optional)

List of historical statements.

statement_path (string, required)

S3 relative path of the statement PDF file.

bill_period_from_date (date, required)

The statement start date.

bill_period_to_date (date, required)

The statement end date.

statement_id (string, required)

The ID of the statement.

number (string, optional)

The external customer facing statement number.

gross_amount (integer, optional)

The statement gross amount, in pence.

warm_home_discount (array, optional)

List of warm home discount related data items.

tax_year (string, optional)

Tax year that the warm home discount was paid. Should be in the format YYYY/YY e.g. 2019/20.

account_type (string, optional)

Type of account for the purpose of paying out the credit. One of CREDIT or PREPAY. Defaults to CREDIT.

group (string, optional)

Whether the customer falls into the core or broader group. One of CORE or BROADER. Defaults to CORE.

supply_addresses (array, optional)

List of active supply addresses linked to the account.

supply_address1 (string, required)

First line of the supply address. Can’t be longer than 512 characters.

supply_address2 (string, optional)

Supply address. Can’t be longer than 512 characters.

supply_address3 (string, optional)

Supply address. Can’t be longer than 512 characters.

supply_address4 (string, optional)

Supply address. Can’t be longer than 512 characters.

supply_address5 (string, optional)

Supply address. Can’t be longer than 512 characters.

supply_postcode (string, required)

Valid UK postcode of the supply address. Can’t be longer than 8 characters.

is_landlord (bool, optional)

Denote that account holder is the landlord of the property.

landlord_details (array, optional) DEPRECATED

This is a legacy field. If possible the property_administrators field below should be used instead.

Details of any persons who are considered administrators of the supply address.

Only one entry is currently permitted - additional users need to be added via the support site.

This user will be granted admin access to all accounts within the same portfolio.

given_name (string, optional)

Required for business accounts. Can’t be longer than 255 characters.

family_name (string, optional)

If not provided for Business accounts, Business will be used as a default value. Can’t be longer than 255 characters.

email (string, optional)

Customer’s email they’ll use for logging into the online portal. Can’t be longer than 254 characters.

mobile (string, optional)

Customer’s personal mobile number. Can’t be longer than 32 characters.

landline (string, optional)

Customer’s landline phone number. Can’t be longer than 32 characters.

date_of_birth (date, optional)

title (string, optional)

Preferred title by the customer. Can’t be longer than 20 characters.

salutation (string, optional)

Preferred salutation by the customer. Can’t be longer than 128 characters.

deceased (string, optional)

One of Reported or Confirmed.

address1 (string, optional)

Landlord address. Can’t be longer than 512 characters.

address2 (string, optional)

Landlord address. Can’t be longer than 512 characters.

address3 (string, optional)

Landlord address. Can’t be longer than 512 characters.

address4 (string, optional)

Landlord address. Can’t be longer than 512 characters.

address5 (string, optional)

Landlord address. Can’t be longer than 512 characters.

postcode (string, optional)

Valid UK postcode of the billing address.

property_administrators (array, optional)

Details of any persons who are considered administrators of the supply address.

Only one entry is currently permitted - additional users need to be added via the support site.

This user will be granted admin access to all accounts within the same portfolio.

given_name (string, optional)

Required for business accounts. Can’t be longer than 255 characters.

family_name (string, optional)

If not provided for Business accounts, Business will be used as a default value. Can’t be longer than 255 characters.

email (string, optional)

Customer’s email they’ll use for logging into the online portal. Can’t be longer than 254 characters.

mobile (string, optional)

Customer’s personal mobile number. Can’t be longer than 32 characters.

landline (string, optional)

Customer’s landline phone number. Can’t be longer than 32 characters.

date_of_birth (date, optional)

title (string, optional)

Preferred title by the customer. Can’t be longer than 20 characters.

salutation (string, optional)

Preferred salutation by the customer. Can’t be longer than 128 characters.

deceased (string, optional)

One of Reported or Confirmed.

address1 (string, optional)

Landlord address. Can’t be longer than 512 characters.

address2 (string, optional)

Landlord address. Can’t be longer than 512 characters.

address3 (string, optional)

Landlord address. Can’t be longer than 512 characters.

address4 (string, optional)

Landlord address. Can’t be longer than 512 characters.

address5 (string, optional)

Landlord address. Can’t be longer than 512 characters.

postcode (string, optional)

Valid UK postcode of the billing address.

effective_from (date, required)

The date at which this person starts being an administrator of the property (inclusive).

effective_to (date, optional)

The date at which this person stops being an administrator of the property (exclusive).

customer_at_supply_address_from_date (date, optional)

The date when the customer started being on supply at the given address.

customer_at_supply_address_to_date (date, optional)

The date when the customer stopped being on supply at the given address, e.g. when they moved out.

meter_points (array, required)

List of meter points linked to the property.

mpxn (string, required)

MPAN or MPRN of this meter point.

mpid (string, required)

The market participant ID for this meter point.

shipper_mpid (string, optional)

The shipper market participant ID for this meter point. This is a gas only field and an error will be thrown if this is provided for electricity meter points.

supply_start_date (date, required)

Supply start date for current supply with source MPID.

supply_end_date (date, optional)

Supply end date for current supply with source MPID.

dc_to_appoint (string, optional)

The data collector to appoint for the meter point. This value can only be set for electricity meter points and should only be provided for an on-market switch.

da_to_appoint (string, optional)

The data aggregator to appoint for the meter point. This value can only be set for electricity meter points and should only be provided for an on-market switch.

mop_to_appoint (string, optional)

The meter operator to appoint for the meter point. This value can only be set for electricity meter points and should only be provided for an on-market switch.

is_customer_appointed (boolean, optional)

Whether agents for this meter point are appointed by the customer. This value can only be set for electricity meter points and should only be provided for an on-market switch.

mam_to_appoint (string, optional)

The meter asset manager to appoint for the meter point. This value can only be set for gas meter points and should only be provided for an on-market switch.

measurement_class (string, optional)

The meter point’s measurement class. Only applicable to electricity meter points.

Can only be one of

• “A” (Non half hourly metered)

• “B” (Non half hourly unmetered)

• “C” (Half hourly metered in 100kW premises)

• “D” (Half hourly unmetered)

• “E” (Half hourly metered in sub-100kW premises)

• “F” (Half hourly metered in sub-100kW domestic premises)

• “G” (Half hourly metered in sub-100kW non-domestic premises)

These codes are defined by the Elexon Market Domain Data (MDD): https://www.elexon.co.uk/glossary/measurement-classes/

export_type (string, optional)

If the meter point is an export meter point, this value indicates whether the meters belonging to it are only used for export or for import as well. If the meter point is not an export meter point, this value should not be provided. It is also only applicable to electricity meter points.

If the meter point contains export-only meters, its export type should be set to EXPORT_ONLY. For import/export meters, it should be set to IMPORT_EXPORT, and the import meters should be provided separately in the payload with the same serial number but belonging to a different meter point (and with no export type provided).

One of IMPORT_EXPORT or EXPORT_ONLY.

et_in_progress (bool, optional)

If an erroneous transfer is in progress, a validation error will be raised saying it should be sorted out before importing the account.

dr_in_progress (bool, optional)

If a disputed reading is in progress, a validation error will be raised saying it should be sorted out before importing the account.

is_deenergised (bool, optional)

If a meter point is de-energised. Defaults to False.

regular_reading_cycle (string, optional)

The regular reading cycle of meter point, as it should be passed to agents via flows. For electricity this can be one of A or or B or D or E or H or M or N or O or Q or S or T or W or Z.

For gas this can be one of CYYY or CYQS or CYSS or CYLM or CYSM or CYNM.

ldz (string, optional)

The Local Distribution Zone code for a gas meter point. This will be superseded by any data received from industry at a later date, but allows faster progress in the short term if provided. Can be one of: SC or LC or LO or LS or LT or LW or NO or NE or NW or WM or EM or EA or WN or WS or NT or SO or SE or SW

Cannot be specified for electricity meter points.

smart_refusal_interest (dict, optional)

type (string, required)

Whether the customer indicated interest or refusal towards a smart meter installation. One of NOT_INTERESTED or INTERESTED or NOT_AT_THE_MOMENT.

date (date, required)

Date the customer informed of interest or refusal of a smart meter install.

refusal_reason (string, optional)

Reason for why a customer refused to have a smart meter installed. One of DO_NOT_OWN_HOME or TECHNOLOGY_SCEPTICAL or WORRIED_SECURITY or WORRIED_HEALTH_SAFETY or NEGATIVE_PUBLICITY or WORRIED_ABOUT_USAGE_COST or ALREADY_HAS_SMART_METER or HOUSE_MOVE_IMMINENT or SWITCH_IMMINENT or MORE_INFORMATION_REQUIRED or IS_LANDLORD or CANNOT_SEE_BENEFIT or WAIT_UNTIL_IT_IS_COMPULSORY or VULNERABILITY or WORRIED_ABOUT_SMART_METERS or WORRIED_ABOUT_INSTALLATION or PROPERTY_NOT_OCCUPIED or CANNOT_ATTEND_APPOINTMENT

source (string, optional)

How the customer got in touch about their interest/refusal. One of WEBSITE or EMAIL or OTHER

ccl_exemptions (array, optional)

List of CCL exemptions for property. Must only be provided for business accounts.

rate (decimal, required)

The normalised proportion of energy use on the meter point that qualifies for CCL exemption. (eg 1.0 for 100% exemption).

effective_from (date, required)

Date this CCL exemption entry is valid from.

effective_to (date, optional)

Date this CCL exemption entry is valid to.

vat_exemptions (array, optional)

List of VAT exemptions for property. Must only be provided for business accounts.

rate (decimal, required)

The normalised proportion of energy use on the meter point that qualifies for VAT exemption. (eg 1.0 for 100% exemption).

effective_from (date, required)

Date this VAT exemption entry is valid from.

effective_to (date, optional)

Date this VAT exemption entry is valid to.

meters (array, optional)

List of active and exchanged meters on the meter point.

meter_serial_number (string, required)

Serial number of the meter. Can’t be longer than 32 characters.

installed_on (date, optional)

Meter installation date.

removed_on (date, optional)

Meter removal date, if this was an exchanged meter.

gas_number_of_digits (integer, optional)

Number of digits of the meter, if it’s a gas meter. Must be between 1 and 15.

units_of_measure (string, optional)

Units of measure for gas meters. Must be either SCMH (Standard Cubic Metres per Hour) or SCFH (Standard Cubic Feet per Hour, in hundreds).

Defaults to SCMH (cubic metres).

smart_type (str, optional)

The type of smart meter, or NONE if it is not a smart meter. Defaults to NONE. SMETS1 meters that have been through the E&A process should be marked as SMETS1_ENROLLED. One of NONE or SMETS1 or SMETS1_ENROLLED or SMETS2.

smart_device_id (str, optional)

Device ID of the smart meter (e.g. “01-23-45-67-89-AB-CD-EF”). Optional if the meter is a smart meter, and should not be provided otherwise.

smart_commissioned_on (date, optional)

Date on which the smart meter was commissioned. Optional if the meter is a smart meter, and should not be provided otherwise.

is_prepay (bool, optional)

Whether the meter is a prepay meter or not. Defaults to false.

prepay_customer_reference_number (string, optional)

Customer reference number for the prepay meter as required for communication with the meter provider. Required if the is_prepay flag is set to True for an electricity meter and migration involves no on-market switch. Max 20 characters.

last_billed_to_date (date, optional)

Date up to which consumption has been billed to for gas meter. This is optional but must appear if not present at the account level or if the meter is not on-supply.

For more info see last_billed_to_date documentation at the account level above.

registers (array, optional)

List of the current registers on the meter. Registers are only required on electricity meters.

register_id (string, required)

This should be the value as provided in MTDs, including leading zeros. Can’t be longer than 32 characters.

tpr (string, required)

Time Pattern Regime code for the register. Can’t be longer than 16 characters.

number_of_digits (integer, required)

Number of digits of the register. Must be between 1 and 15.

last_billed_to_date (date, optional)

Date up to which consumption has been billed to for electricity meter. This is optional but must appear if not present at the account level or if the meter is not on-supply..

For more info see last_billed_to_date documentation at the account level above.

is_settlement (boolean, optional)

Whether the register should be used for billing, and so whether it needs a transfer read, an EAC and “last billed to” date. Defaults to true.

transfer_readings (array, optional)

Only the last reading (or readings, if the meter is ECO7 or ECO10) the account has been billed up to.

If the account has never been billed, the SSD reading(s) must be on this list.

It’s expected that a transfer reading will be given per register on an active meter in the case of electricity and a reading per active gas meter.

It’s expected that all transfer reading dates will match the last_billed_to_date.

register_id (string, optional)

This should be the value as provided in MTDs, including leading zeros. This register id must make reference to an existing register under this meter. This field is required for electricity readings. Can’t be longer than 32 characters.

reading_date (date, required)

Date of the reading.

reading_type (string, required)

One of ESTIMATE or SMART or REGULAR or CUSTOMER.

reading_value (decimal, required)

Value of the reading.

reading_history (array, optional)

List of historical readings. Generally these are readings prior to the one(s) provided under transfer_readings. It is possible to provide readings in the reading_history after the transfer_reading date but these must unbilled.

register_id (string, optional)

This should be the value as provided in MTDs, including leading zeros. This register id must make reference to an existing register under this meter. This field is required for electricity readings. Can’t be longer than 32 characters.

reading_date (date, required)

Date of the reading.

reading_type (string, required)

One of ESTIMATE or SMART or REGULAR or CUSTOMER or ROUTINE.

reading_value (decimal, required)

Value of the reading.

billed (bool, required)

Whether the reading has been billed.

validation_status (string, optional)

One of VALIDATED or UNVALIDATED or FAILED. Defaults to VALIDATED.

prepay_details (dict, optional)

A record of details regarding financial information of the prepayment meter. Applicable only on prepay meters. Not applicable if the below values do not in anyway contribute to the last_statement_balance: This is because, in Kraken, the state of the meter’s ledgers is independent of the account balance, and can be ascertained from the first flows received.

debt_balance (decimal, required)

The meter’s debt balance, in pounds, as of the closing date of the last statement. Must be positive.

credit_balance (decimal, required)

The meter’s credit balance, in pounds, as of the closing date of the last statement.

transfer_vend_read_date (date, required)

The date that the transfer vend read was taken.

It’s expected that this date will be exactly one day earlier than the last_billed_to_date, due to billing occurring as of midnight the day after the final reading on a given bill.

gas_debt_repayment_options (dict, optional)

Debt repayment options that are used when sending SQO1 flows. Optional for gas meters, and not applicable for electricity meters.

weekly_min (decimal, optional)

The minimum amount, in pounds, that a customer needs to pay towards their debt each week. Must be positive. Defaults to "0.0".

weekly_max (decimal, optional)

The maximum amount, in pounds, that a customer needs to pay towards their debt each week. Must be positive. Defaults to "0.0".

eac_history (array, optional)

History of electricity Estimated Annual Consumption entries for this meter point. It’s expected to get an EAC entry per different TPR given in the meter point meter registers.

effective_from (date, required)

Start date of the EAC entry.

tpr (string, required)

Time Pattern Regime code for the EAC entry. Can’t be longer than 16 characters.

consumption (decimal, required)

Value in KWh.

source (string, optional)

Source of the EAC entry. This would ordinarily be from a flow file, in which case this should be the value of the field. In other cases this may have come from another source, in which case that can be entered here too.

aq_history (array, optional)

History of gas Annual Quantity entries for this meter point. It’s expected that at least one AQ entry will be provided for the current period if there’s an active gas meter. Gaps and overlapping on the given entry dates will raise validation errors.

effective_from (date, required)

Start date of the AQ entry.

effective_to (date, optional)

End date of the AQ entry. Leave empty for an open ended AQ entry.

consumption (decimal, required)

Value in KWh.

source (string, optional)

Source of the AQ entry. This would ordinarily be from a flow file, in which case this should be the value of the field. In other cases this may have come from another source, in which case that can be entered here too.

smart_site_visit (array, optional)

A record of site visit appointments on the meter point for installing a smart meter.

reference_number (str, required)

A reference number for the appointment.

date (date, required)

The date the appointment took place.

metering_agent (str, required)

The metering agent performing the appointment. One of OES or AES or SMS or PROVIDOR or EON_METERING or MDS or LOWRI_BECK or METERPLUS or ENTERPRISE_MANAGED or MIDS_ELEC or N_POWERGRID or ELEC_NW or NATIONAL_GRID or the four-character MPID of one of the above or the three-character Short Code of one of the above

status (str, required)

Status of the appointment. One of SUCCESSFUL or ABORTED or CANCELLED.

appointment_notes (str, optional)

Notes on the appointment.

additional_data (dict, optional)

Any additional data to be stored for the appointment, e.g. the asset condition code or additional recorded information on the outcome.

fit (dict, optional)

payment_method (string, required)

One of BACS or CHEQUE. Note that Kraken requires a DD instruction with the payment vendor for carrying out BACS repayments. Please check with the tech team whether CHEQUE is supported for FIT in you Kraken installation if you are considering using it.

vendor_name (string, optional)

Please contact the tech team for the names of the vendors available to you. Required if the payment_method is BACS.

instruction_reference (string, optional)

The reference of the mandate as known by the vendor. Can’t be longer than 512 characters. Required if the payment_method is BACS.

vat_number (string, optional)

Pass this for VAT-registered customers to whom we should pay VAT on export payments.

installations (array, required, min length 1)

Each installation in this list will be imported into Kraken from CFR and attached to the account described by the parent payload. All installations under a single generator in CFR must be in the same payload. The installations here _must_ be accessible by the supplier’s licensee in CFR.

fit_id (string, required)

CFR installation FIT ID.

address (dict, optional)

Use this to override the address we would import from CFR.

line1 (string, required) line2 (string, optional) town (string, optional) county (string, optional) postcode (string, required)

non_eligible_extensions (array, optional)

Use this to tell us that this installation has extensions that aren’t eligible for FIT payments.

reference_number (integer, required)

The number of the extension.

installed_capacity (decimal, optional)

The extension’s installed capacity in kWh.

credit_hold (dict, optional)

Use this to indicate that we should hold payments for this installation.

reason (string, required)

The reason why payments should be held for this installation. One of HAS_NOMINATED_RECIPIENT or INVOLVED_IN_COO or SWITCH_LOSS or LINKED_TO_WRONG_ACCOUNT or PAID_INCORRECTLY or MIGRATED_IN_DISPUTE or NEEDS_MANUAL_PAYMENT or OTHER.

notes (string, optional)

Free text shown in the Kraken UI that can be used to give additional information as to why payments should be held for this installation.

active_from (date, optional)

The date from which the payment hold should apply to this account. Defaults to the time the account is imported.

meters (array, required, min length 1)

Use this to give us information about each of the customer’s meters. Note this sits alongside the installations object because meters can be shared across installations and, although it’s rare, we need to accommodate for that.

type (string, required)

The meter type. Must be one of either GENERATION or EXPORT

mpan (string, optional)

The 13-digit MPAN core. Optional for export and generation meters.

serial_number (string, required)

The meter’s serial number.

make (string, optional)

The make of the meter.

model (string, optional)

The meter model.

extensions (array[string], required, min length 1)

The references of the extensions that this meter is attached to. E.g. [“FIT00123456-1”]. These IDs must match what is found in CFR as this is where we get the extension data from. This list of IDs looks up the existing extensions in Kraken to link to the meter.

transfer_reading (dict, required)

A transfer reading is required for all meters and represents the reading that Kraken will start paying the customer from.

reading_date (date, required)

The date the reading was taken from the meter.

reading_value (decimal, required)

The reading in kWh, with up to 2 decimals.

metadata (array, optional)

An array of key value pairs for storing generic metadata relating to an account.

key (string, required)

Key on which the metadata will be stored on

value (dict, required)

A json object containing any arbitrary piece of data to store in relation to the account.

If the payload is valid, a 200 OK response will be returned with the validated data as its body.

If there are validation errors, a 400 Bad Request response will be returned, detailing the errors.

Sample response of a field being missing from the request:

And the example response:

Non field errors can be presented in the JSON either on the top level, or within certain fields.

Top level validation errors are:

• Given transfer balance: {transfer_balance}; After adding charges and payments ({transactions_value}) to the last statement balance ({last_statement_balance}), the expected transfer balance was: {expected_transfer_balance}.

• A given name is required for each customer

• Account must have at least one billable meter point.

• last_billed_to_date is required.

• Last billed to date not given on either the account or the gas meter for meterpoint {mpxn}. Last billed to date can be either at the account level or must appear on all active gas meters.

• Last billed to date not given on either the account or the electricity register for meterpoint {mpxn}. Last billed to date can be either at the account level or must appear on all active electricity registers.

• Last billed to date for an electricity meter point provided on the meter for meter point {mpxn}. Electricity meter points must have their last_billed_to_date provided on the register or at the top level account.

• There cannot be a current statement transaction that happened before {last_billed_to_date}

• There cannot be a historical transaction on the same day or after a current transaction

• All historical transactions must have a date on or before {last_statement_closing_date} (or {last_billed_to_date} if not provided)

• The final balance of all historical statement transactions, {initial_balance}, must match the last statement balance, {last_statement_balance}.

• All current statement transactions must have a date on or after {last_billed_to_date}

• Prepay meters {to_prepay_meter_serial_numbers} must have initialisation prepayment details in order to also be sent transactions.

• All transfer reading dates must match the last_billed_to_date, {last_billed_to_date}

• The transfer vend read date must precede the last_billed_to_date, {last_billed_to_date}, by one day.

• The billed reading taken on {reading_date} is after the last_billed_to_date, {last_billed_to_date}.

• All supply meter points must be covered by a contract

• All meter points with a contract should be billable.

• Meter point {mpxn} is billable but has no active meters.

• Contract dates on the account don’t match up (there are gaps or overlaps)

• Contract for {mpxn} starts before SSD {supply_start_date}.

• There are multiple open ended payment schedules.

• There are date overlaps in the payment schedules around the dates {start_date} and {expected_start_date}.

• Cannot have multiple payment schedules starting on the same date - {start_date}

• There is a gap in the payment schedules between the dates {predecessor_end_date} and {start_date}.

• statement_id is required.

• There cannot be any customers if the unknown_occupier flag is True.

• A transfer reading is required for active gas meters.

• There should be exactly one transfer reading per register.

• Meter {meter_serial_number} fully billed by a transfer reading on or after its removal. The transfer reading for this case should be the first reading on replacement meter, if there is one; else no transfer reading should be provided.

• Couldn’t find an AQ entry currently valid

• Couldn’t find an EAC entry for the TPRs {tprs}

• Please, resolve the open complaint in progress before proceeding with the import of this account.

• No supplier found with code {import_supplier_code}

• A last_billed_to_date or last_statement_issue_date must be provided if a last_statement_balance is given.

• For debt collection proceedings, both agency name and start date must be provided.

• If a debt collection proceeding start date is given, the agency_name must also be given.

• {tariff} is an {‘import’|’export’} tariff but {mpxn} is an {‘export’|’import’} meter point.

• Meter point {mpxn} has profile class {profile_class} and should therefore be on an Economy 7 tariff.

• Meter point {mpxn} has profile class {profile_class} and SSC {ssc} and should therefore be on a standard tariff.

• Meter point {mpxn} has profile class {profile_class}, SSC {ssc}, and a register with TPR {tpr}, and should therefore be on a {tariff_type} tariff.

• A contract covering the last billed to date must exist for meter point {mpxn}.

• A reason should only be given when the smart interest refusal type is one of NOT_INTERESTED or NOT_AT_THE_MOMENT

• The fields business_type or company_number should only be provided for business accounts

• Bespoke tariff rates can only be provided for business accounts.

• Agents supplied when not performing on-market switch on meter point {mpxn}.

• No campaign found for {campaign_name}

• {path_name} is not a supported dunning path.

• CCL/VAT rates should not be provided for domestic accounts.

• Active prepay meters require an active prepay contract.

• An occupier account should only have a single supply address.

• An account must not have duplicate supply addresses.

• billing_address1 and billing_postcode must be provided for all but occupier accounts.

• Twin fuel accounts should only have a single supply address.

• There are existing customers on different portfolios.

• Existing portfolio has a different brand.

• Metadata cannot have duplicate keys.

• The account cannot be in the process of switching away.

• Expected an import and export meter point for meter {meter_serial_number}.

• Corresponding import meter not found for export meter {meter_serial_number}.

• Duplicate meters with the serial number {meter_serial_number} were provided under different meter points. This is only allowed in the case of an import/export meter with export_type set appropriately.

• The meter point with MPXN {mpxn} is duplicated under different supply addresses.

In other cases, non field errors would be returned nested under certain field. For example, the “meter_points” section would be shown as:

“meter_points” validation errors are:

• Please, resolve the Erroneous Transfer in progress before proceeding with the import of this account.

• Please, resolve the Disputed Read in progress before proceeding with the import of this account.

• Invalid LDZ: {ldz}

• ldz is only expected for gas meter points

• aq_history is only expected for gas meter points

• There is more than one register with the same register id on the meter {serial_number}.

• A register id must be provided for the reading {reading}.

• The register id {reading_register_id} for a given transfer reading is not on the list of given register ids for the meter {serial_number}.

• A register id must be provided for the reading with value {reading_value}.

• There shouldn’t be repeated EAC entries for a TPR with the same effective_from.

• A register id must be provided for the reading {reading}.

• There are multiple open ended AQ entries in the meter point {mprn} aq_history.

• There are gaps or overlaps in the meter point {mprn} aq_history.

• gas_number_of_digits is required for gas meters

• eac_history is only expected for electricity meter points

• Couldn’t find an AQ entry currently valid

• No market participant found with code {value}

• A customer reference number must be provided for an active electricity prepay meter

• Active electricity meter {serial_number} must have at least one register.

• All registers for non-half hourly electricity meter {serial_number} must have a register id.

• All registers for non-half hourly electricity meter {serial_number} must have a TPR.

• Meter point {mpxn} has active meters but not transfer readings

• DC or DA to appoint can only be provided for electricity meter points.

• MAM to appoint can only be provided for gas meter points.

• Gas option for regular_reading_cycle provided for electricity meter point.

• Electricity option for regular_reading_cycle provided for gas meter point.

• Off supply meter points must have a reading for supply end date.

• Meter points must have supply start date in the past.

• Unknown meter point measurement class.

• Gas shipper MPID not allowed for electricity meter point {mpxn}.

• Duplicate meter points with the MPXN {mpxn} were provided.

• Multiple meters with serial number {serial_number} were provided. This is only valid if they are all part of a series of dummy meter exchanges.

“meters” validation errors are:

• Smart meter details should only be provided if the meter is a smart meter.

• prepay_details: {meter_serial_number} is not a prepay meter.

• prepay_customer_reference_number: {meter_serial_number} is not a prepay meter.

“prepay_details” validation errors are: * Gas debt repayment options should only be provided if the meter is a gas meter.

“registers” validation errors are:

• A time pattern regime with id {value} has not been found

“contracts” validation errors are:

• No {fuel_name} tariff found for the tariff code {tariff_code}

• Contract effective_to date {effective_to} cannot be earlier than contract effective_from date {effective_from}

• A bespoke tariff rate for a gas meter needs to have a unit rate provided

• Registers should not be provided for a bespoke tariff for a gas meter

• A bespoke tariff rate for an electricity meter needs to have registers provided

• Unit rates for bespoke tariffs on electricity meters need to be provided in the registers array

• A bespoke half-hourly tariff can only be given on electricity tariffs.

• If multiple bespoke half-hourly rates are provided, all must have start times.

• One of register_id and rate_type must be provided for bespoke electricity

• Duplicate bespoke rates received for {mpxn}

• Contract for variable product cannot start before product is available.

“commission_contracts” validation errors are: * Affiliate organisation with name {name} does not exist

“customer_preferences” validation errors are:

• An answer must be provided for the given question

“customer” validation errors are:

• This email address looks like a test email address - if this is a spaceholder email, please remove it.

• Cannot have contact details with an account identified as The Occupier.

• Metadata cannot have duplicate keys.

“aq_history” validation errors are:

• {effective_from} can’t be later than {effective_to}

“payment_schedules” validation errors are:

• {start_date} can’t be later than {end_date}

• Fixed schedule cannot have an amount of 0.0

• Debt repayment end date of {debt_repayment_end_date} must be before schedule end date.

“debt” validation errors are:

• Storage of CAIS reference not supported at this time. (This needs to be enabled, please contact Kraken.)

• CAIS reference already saved on another account.

• Debt collection agency {debt_collection_agency_name} is not supported.

• If a debt collection proceeding start date is given, the agency_name must also be given.

“psr” validation errors are:

• No electricity PSR record found with code {value}

• No gas PSR record found with code {value}

• No PSR record found with description {value}

“smart_site_visit” validation errors are:

• One of date and site_visit_date must be provided

• Site visit must have an associated metering_agent from the documented list, or their MPID (as a MOP) or short code (as a MAM).

“supply_addresses” validation errors are:

• If customer_at_supply_address_to_date is provided, a from date must also be given

“ccl_exemptions” and “vat_exemptions” validation errors are:

• Effective to date of {effective_to} must be after the effective from date of {effective_from} for VAT and CCL exemptions.

• {tax_type} exemptions should only be provided for business accounts.

• Multiple open ended {tax_type} exemptions provided for meter point.

• Date overlaps in the {tax_type} exemptions provided for meter point.

“transactions” validation errors are:

• The payment_type {payment_type} is not a valid type for a Payment.

• The payment_type {payment_type} is not a valid type for a Repayment.

• Transactions of type {transaction_type} should not have negative values. (NOTE: This would be for payment or repayment transaction types)

• Historical statement transactions provided with no last_statement_issue_date

• Transaction date of {transaction_date} cannot be in the future.

“warm_home_discount” validation errors are:

• Incorrect format for tax_year. Must be YYYY/YY.

“references” validation errors are:

• Not a valid namespace

“notes” validation errors are:

• At least a note body or document path should be given

“dunning_path” validation errors are:

• start date of {start_date} cannot not be earlier than today.

Use this end-point to list all meterpoint statuses by import supplier code and external account number.

Request:

If an account import process, account application or meterpoints cannot be found for the given import supplier code and external account number, a 404 Not Found response will be returned. If the supplied MPxN is invalid a 400 Bad Request response will be returned.

If the request is valid, a 200 OK response will be returned with a list of MPxNs and their Kraken status.

Use this end-point to submit registration flows for meter points on an existing Kraken account.

Request:

If an account import process or an account cannot be found, or if there are no meter points for which to submit registration flows, a 404 Not Found response will be returned like so:

Possible error_detail’s returned for a 404 response are as follows:

• Account import process not found for {external_account_number}

• Account not found for {external_account_number}.

• No meter points found for register for {external_account_number}.

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 en 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.

Possible validation errors are:

• Meter point {mpxn} is already on supply.

• Meter point should have the PRE_REGISTRATION status, but instead has {meter_point_status}.

• Meter point {mpxn} is marked to not send registration flows.

• Meter point {mpxn} has already had registration flows sent.

• No MPID found for meterpoint {mpxn}. MPID must be either supplied as part of the meter point data, or exist on the import supplier.

• Rate limit reached for sending registration flows since 5pm.

• {mpid} not current supplier.

An import process is how we collect data for an account and then create an account within Kraken from that data.

The status returned from the Retrieve status of imported account endpoint can be one of

• UNKNOWN - an account has not been created yet in Kraken

• PENDING - an account has been created in Kraken, but the switch hasn’t started yet

• IN_PROGRESS - registration flows for all meter points have been sent

• REJECTED - change of supplier process rejected by previous supplier

• COMPLETED - change of supplier process successful

If no account has been created in Kraken yet, the status will be UNKNOWN with no kraken_account_number returned.

The role field is not yet configured for this Kraken instance, and should not be provided.