All (production) API requests should use a base URL of: https://api.st.kraken.tech/

Note, all API requests must be made over HTTPS.

Authentication is required for some API end-points. This is performed via HTTP Basic Auth.

Provide your API key as the Basic Auth username value. You do not need to provide a password, eg:

Note the colon after $API_KEY which prevents cURL from asking for a password.

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

Request:

The body must be a single JSON object describing the account. See the sections below specifying what to include in the payload.

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

Use this endpoint to create or update an account import process. An account import process is an entity that can later be processed and transformed into a Kraken account. An account import process can be uniquely identified by the import_supplier_code and external_account_number passed in the payload.

Request:

The expected payload is the same as a single account from the validate account end-point.

If there are validation errors, a 400 Bad Request response will be returned, detailing the errors, the same as the validate account end-point.

If the payload is valid and an account import process does not already exist then a 201 Created response will be returned with the newly created account import process external_account_number and import_supplier_code.

If the payload is valid and an account import process does already exist then a 200 OK response will be returned with the updated account import process external_account_number and import_supplier_code.

The response payload looks like:

Use this end-point to get the data of an existing account import process.

Request:

If an account import process cannot be found for the given import supplier code and external account number, a 404 Not Found response will be returned.

If the account import process exists, a 200 OK response will be returned with the account import process data as its body.

Use this end-point to get the status and Kraken account number (if it exists) for a given migrated account.

Request:

If an account import process cannot be found for the given import supplier code and external account number, a 404 Not Found response will be returned.

If the account import process exists, a 200 OK response will be returned with the Kraken account number, if applicable. The response has the following format

where the status 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.

If the import process is configured to return user data for created users, the 200 response will be returned with the account user emails and ids for any of the active users assigned to the account.

Use this end-point to list all existing account import process external account numbers.

Request:

If any account import processes are found for the given import supplier code, a 200 OK response will be returned with a list of the existing import process external account numbers and Kraken account numbers (or null if the import process has not been imported yet).

Use this end-point to list all account import process external account numbers that are pending import.

Request:

If any pending account import processes are found for the given import supplier code, a 200 OK response will be returned with a list of the existing import process external account numbers. For consistency with the other APIs, the Kraken number field is also returned but will always be null.

Use this end-point to list all account import process external account numbers that have been imported and now have Kraken accounts.

Request:

If any imported account import processes are found for the given import supplier code, a 200 OK response will be returned with a list of the existing import process external account numbers and Kraken account numbers.

Use this end-point to create a new account from an existing account import process.

Request:

Sample payload:

The expected payload contains the primary key of an account import process, which is composed by an external account number and an import supplier code, and the operations team name where the account portfolio is meant to be created. In order for this to work, an import process with the given external_account_number and import supplier and an operations team with the given name must exist.

If there are validation errors, a 400 Bad Request response will be returned, detailing the errors. In the case of an account having already been imported, two additional fields will be present in the response detailing the external_account_number and kraken_account_number:

If the import process is configured to return user data for created users, the 400 response will be returned with the account user emails and ids for any of the active users assigned to the account.

If the payload is valid, a 201 Created response will be returned with the newly created account number.

If the import process is configured to return user data for created users, the response will be returned with the account user emails and ids for any of the active users assigned to the account.

Use this end-point to add notes to an account.

Request:

Sample payload:

The expected payload contains the primary key of an account import process, which is composed of an external account number and an import supplier code, and a list of objects containing the note information. A note must contain at least one of a body or document_paths` and an optional created_at datetime. The document_paths` refer to the locations in S3 where attached documents are stored, for example documents/note_attachments/attachment.pdf. The notes bucket is stored as a Kraken setting meaning that the full path would resolve to s3://notes_bucket/documents/note_attachments/attachment.pdf. If a created_at datetime is not provided, this will default to the current localtime. An optional is_pinned boolean can be passed in the payload to denote whether this note will be pinned to the top of the Kraken account support site page.

Note that document_path (singular) is being deprecated, please use document_paths (plural) which is a list of document_path elements.

If there are validation errors, a 400 Bad Request response will be returned, detailing the errors. If an account import process or account is not found then a 404 Not Found response will be returned.

If the payload is valid, a 201 Created response will be returned containing a list of the posted notes and their creation status. A new note will only be created if a note on the account with the same body (and created_at if provided) does not already exist.

Possible validation errors are:

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

Sample payloads:

Domestic metered account

Domestic unmetered account

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_attention_of (string, optional)

Extra recipient information for when this account represents a large organisation (e.g. “The Bursar” or “Accounts Payable”). Can’t be longer than 256 characters.

billing_customer_reference (string, optional)

Customer-specified reference to use in communications with them (e.g. “Energy supply”). Can’t be longer than 256 characters.

billing_sub_name (string, optional)

The name displayed on the bill but not on the account. This can be different from the billing name . Can’t be longer than 256 characters.

billing_address (string, required)

The billing address for the account. This is the address to which postal comms are sent. Assumes GBR address. International addresses are not yet supported.

street (string, required)

The full street address of the property. Separate items with a comma and a space. e.g. “Flat 1, 2 Avenue Road”, “39 Cambridge Road”, “Seagull Cottage, Seashell Drive”

borough (string, optional)

London borough, if applicable (only for London addresses).

town (string, required)

The town or city e.g. “London”, “Ipswich”

county (string, optional)

The county of the supply address e.g. “Greater London”, “Somerset”

postcode (string, required)

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

is_business (bool, optional)

Whether the account is a business account.

is_vat_exempt (bool, optional)

Whether a business account is exempt from VAT.

is_vacant (bool, optional)

Where the account is vacant (no one lives at the property).

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.

last_statement_balance (decimal, optional)

The balance of the account at the point of the latest issued statement, in pounds.

Credit balances must be positive, debit balances must be negative.

This value, along with the total value of current_statement_transactions, must equal the transfer_balance.

last_billed_to_date (date, optional)

Date up to which consumption has been billed to.

Required if the account has been billed in the past.

Optional if the account has never been billed before, provided no other data related to transactions or statements are filled in. The transfer_balance must also be equal to 0.00.

The following must be true in order for this field to be optional:

• transfer_balance should be equal to 0.00

The following should not be passed in in order for this field to be optional:

• last_statement_closing_date

• last_statement_issue_date

• current_statement_transactions

• historical_statement_transactions

• last_statement_balance

• debt

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.

If this value is provided, 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.

dd_reference (string, optional)

Reference to the currently active Direct Debit Instruction on the account. Can’t be longer than 512 characters.

next_bill_due_date (date, optional)

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

has_open_complaint (bool, optional)

If an account has an open complaint, the validation stage will raise an error saying it should be sorted out before importing the account.

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

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 or BESPOKE.

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.

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.

Their value, plus the last_statement_balance, must add up to the transfer_balance.

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 or SUPPLY_CHARGE.

The amount of a CHARGE, SUPPLY_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:

• BALANCE_TRANSFER

• BALANCE_ADJUSTMENT

• DATA_IMPORT_BALANCE_TRANSFER

• CUSTOMER_SERVICE_GESTURE

• BANK_TRANSFER

… and any client-configured reasons.

If the transaction is of CHARGE type, one of the following:

• DEFAULT

• BALANCE_TRANSFER

• SUPPLEMENTARY_LEDGER_BALANCE_TRANSFER

• DATA_IMPORT_BALANCE_TRANSFER

• IMPORTED_CHARGE

• REVERSED_ACCOUNT_CREDIT

• BALANCE_TRANSFER_FOR_FINAL_BILLED_ACCOUNT

… and any client-configured reasons.

reference (string, optional)

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

payment_type (string, optional)

If the transaction is of PAYMENT type, one of the following:

• DD_FIRST_COLLECTION

• DD_REGULAR_COLLECTION

• DD_RE_PRESENTATION

• DD_FINAL_COLLECTION

• CREDIT_CARD

• DEBIT_CARD

• CHEQUE

• BACS_DEPOSIT

• ALLPAY_CASH

• ALLPAY_CARD

• ALLPAY_CHEQUE

• PAYPOINT_CASH

• PAYPOINT_CARD

• PAYPOINT_CHEQUE

• PAYZONE

• POST_OFFICE_CASH

• POST_OFFICE_CHEQUE

• POST_OFFICE_SAVINGS_STAMPS

• POST_OFFICE_CARD

• DCA_COLLECTION

• BRISTOL_POUND

• CASH

If the transaction is of REPAYMENT type, one of the following:

• DIRECT_CREDIT

• CARD_REFUND

• BACS

• CHEQUE

display_note (string, optional)

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

product_code (string, optional)

For SUPPLY_CHARGE transactions only. Code of the product (i.e. tariff). Must match an existing code of a product. Account must have an agreement for this product for period covers all billing periods of line items.

line_items (array, optional)

For SUPPLY_CHARGE transactions only, line items contain details about the charge, e.g. standing/consumption charge, billing period, number of units etc.

rate_band (string, required)

Rate of the product this charge is for. Must match an existing rate of a product product_code. Rate must be active from start_date to end_date.

start_date (date, required)

Start date of the billing period, inclusive.

end_date (date, required)

End date of the billing period, inclusive.

number_of_units (decimal, required)

E.g. cubic meters consumed for the period, days on supply for fixed charges or RV proportion for period for unmetered RV charges.

net_amount (decimal, required)

Charge amount for the line item. Number to 2 decimal places (pounds).

units (array, optional)

For metered accounts only. List of two decimal numbers representing the meter readings for the billing period.

params (dict, optional)

Extra details.

tax_items (array, optional)

For SUPPLY_CHARGE transactions only, tax items contain details about the tax. If not provided will be set to default zero tax.

amount (decimal, required)

Amount of the tax. Number to 2 decimal places (pounds).

tax_type (string, required)

Tax type, e.g. VAT, CCL, Sales tax.

rate (decimal, required)

The rate at which tax has been applied.

value_taxed (decimal, required)

The value that has been taxed.

unit_type (string, optional)

Tax unit type, e.g. PROPORTION.

params (dict, optional)

Extra details.

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.

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.

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.

alternative_phone_numbers (array, optional)

Array of customer’s alternative phone numbers

psr (array, optional)

internal_code (string, required)

PSR record’s internal code. The internal code and the description should be referring to the same PSR record type.

description (string, required)

PSR record’s description. The internal code and the description should be referring to the same PSR record type.

effective_to (date, optional)

Date when the PSR record is effective to. It is a required field for temporary PSR record type.

params (dict, optional)

Extra information in relation to PSR record type PSR Nominee and Requires Password.

nominee_name (string, optional)

The PSR nominee name. It is a required field for the PSR record type PSR Nominee.

nominee_relationship (string, optional)

The PSR nominee relationship. It is an optional field for the PSR record type PSR Nominee.

nominee_phone_number (string, optional)

The PSR nominee phone number. It is an optional field for the PSR record type PSR Nominee.

password (string, optional)

It is a required field for the PSR record type Requires Password.

import_source (string, optional)

The PSR import source. Defaults to DATA_IMPORT if not provided.

Must be one of the following: * AUTO_ENROL * CUSTOMER_LETTER * DOORSTEP * EMAIL * ELECTRICITY_NORTH_WEST * FACE_TO_FACE * FACEBOOK * HELP_WHEN_YOU_NEED_IT * LEAFLET_APPLICATION * NATIONAL_GRID * NORTHERN_POWER_GRID * SCOTTISH_POWER_ENERGY_NETWORKS * TELEPHONE * TWITTER * WEBFORM * WESTERN_POWER_DISTRIBUTION * WEB_SELF_SERVICE

…and any client-configured statuses.

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_whatsapp (bool, optional)

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

marketing_preferences (dict, optional)

A dict of booleans for storing marketing preferences to an account user.

is_opted_in_to_marketing (bool, optional)

Whether user has opted to receive generic marketing.

is_opted_in_to_plumbing_offer (bool, optional)

Whether the user has opted to receive messages offering plumbing discounts or other services (home serve) not directly related to the services the client provides.

is_opted_in_to_company_survey (bool, optional)

Whether user has opted to receive company surveys.

is_opted_in_to_regulatory_survey (bool, optional)

Whether user has opted to receive regulatory surveys.

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.

details (dict, optional)

A dict of addtional customer details.

middle_name (string, optional)

Can’t be longer than 255 characters.

employment_status (string, optional)

One of the following: * EMPLOYED * NOT_ON_BENEFITS * RETIRED * SELF_EMPLOYED * STUDENT * UNEMPLOYED

…and any client-configured statuses.

homeownership_status (string, optional)

One of the following: * HOMEOWNER * RENTED_HOUSING_ASSOCIATION * RENTED_LOCAL_COUNCIL * RENTED_PRIVATELY * RENTED_STUDENT_HOUSE * RENTED_BUT_NOT_KNOWN

…and any client-configured statuses.

benefit_status (list, optional)

List of benefits the customer is receiving.

Must be one or more of the following: HOUSING_BENEFIT, INCOME_SUPPORT, WORKING_TAX_CREDIT, CHILD_TAX_CREDIT, PENSION_CREDIT, UNIVERSAL_CREDIT, JOBSEEKERS_ALLOWANCE, EMPLOYMENT_AND_SUPPORT_ALLOWANCE, DISABILITY_LIVING_ALLOWANCE, PERSONAL_INDEPENDENCE_PAYMENT, ATTENDANCE_ALLOWANCE.

…and any client-configured statuses.

sap_id (string, optional)

Unique ID for this user in the external system (SAP).

national_insurance_number (string, optional)

National Insurance number of the customer.

historical_statement_transactions (array, optional)

If historical transactions are given, their value must add up to the given last_statement_balance.

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 or FOUR_WEEKLY or SIX_MONTHLY or ANNUALLY.. 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, REGULAR or PLAN. 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. A PLAN triggered schedule must be migrated with instalments.

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.

instalments (array, optional)

List of payments instalments to migrate. Required if trigger is PLAN.

payment_date (date, required)

The payment date.

amount (decimal, required)

Positive number with 2 decimal places (pounds).

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.

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

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

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 (string, optional)

The statement gross amount, in pence.

supply_addresses (array, optional)

List of active supply addresses linked to the account.

supply_address (string, required)

The address of the property that is on supply. Assumes GBR address. International addresses are not yet supported.

street (string, required)

The full street address of the property. Separate items with a comma and a space. e.g. “Flat 1, 2 Avenue Road”, “39 Cambridge Road”, “Seagull Cottage, Seashell Drive”

borough (string, optional)

London borough, if applicable (only for London addresses).

town (string, required)

The town or city e.g. “London”, “Ipswich”

county (string, optional)

The county of the supply address e.g. “Greater London”, “Somerset”

postcode (string, required)

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

external_property_reference (string, optional)

Unique identifier of the property from an external system.

property_detail (dict, optional)

Detailed information about a property.

strategic_metered_area (String, Optional):

Strategic Metered Area, Provides the ability to identify which SMA area a property is located within.

district_metered_area (String, Optional): District Meter Area, Provides ability to identify which DMA area a property is located within.

small_area_monitor (String, Optional): Small Area Monitor, Provides ability to identify which SAM area a property is located within.

water_quality_zone (String, Optional): Provides ability to identify which Water Quality Zone a property is located within.

water_reservoir_zone (String, Optional): Provides ability to identify which Reservoir Zone a property is located within.

pressure_managed_zone (String, Optional): Provides ability to identify which PRV zone a property is located within.

waste_meter_area (String, Optional): Provides ability to identify which metered area a property is located within.

easting (Integer, Optional): The easting coordinate of the property location.

northing (Integer, Optional): The northing coordinate of the property’s location.

address_identifier (String, Optional): 3rd Party data to identify a specific property location.

traffic_sensitive (Boolean, Optional): Indicates whether the area is traffic-sensitive.

lane_rental_street (Boolean, Optional): If a street is part of rental street/lane scheme.

low_pressure_risk (Boolean, Optional): Flags if there is a risk of low water pressure.

water_pressure_min (Float, Optional): Internal data on minimum water pressure in the location.

water_pressure_max (Float, Optional): Internal data on maximum water pressure in the location.

water_hardness (String, Optional): Internal data on water hardness in the location.

One of

VERY_SOFT, SOFT, MODERATELY_HARD, HARD, VERY_HARD.

water_hardness_mg_per_l (Float, Optional): Internal data on water hardness in the location measured in milligrams per liter.

uprn (Integer, Optional): Unique Property Reference Number. National geographical identifier, providing the ability to uniquely identify a property.

uprn_reason_code (String, Optional): Code explaining the absence or duplication of a UPRN. One of:

• ME - No number - missing entry from the NLPG

• SR - No number - fish farms, fishing, and sporting rights

• MT - Multiple UPRNs at the same eligible premises

• IP - No number - infrastructure project

• PL - No number - not yet issued by planning

• BW - No number - construction site

• SP - No number provided - use number from other SPID

• OT - Other

building_water_status (Boolean, Optional): Boolean flag to indicate if the site is a building construction site.

fluid_category_risk (Integer, Optional): Value between 1 and 5, with 5 being high risk.

water_interruption_sensitivity (Integer, Optional): Value between 1 and 4, with 1 being high sensitivity to interruption of potable water.

customer_classification_sensitive (String, Optional): For identification of Non-Household customer as a Sensitive Customer (to supply of potable water). One of:

• SEMDV - Sensitive customer

• NA - Not applicable

clean_water_delivery_point (Integer, Optional): External property reference used by GIS.

water_pipe_id (Integer, Optional): Value used to map assets to a property and stored with SAP.

property_functional_location (String, Optional): The water pipe that is connected to the property.

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.

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)

Landlord’s email address. Can’t be longer than 254 characters.

mobile (string, optional)

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

landline (string, optional)

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

role (string, optional)

How the portfolio relates to its accounts/properties. One of LANDLORD or PROPERTY_DEVELOPER.

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)

Landlord’s email address. Can’t be longer than 254 characters.

mobile (string, optional)

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

landline (string, optional)

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

role (string, optional)

How the portfolio relates to its accounts/properties. One of LANDLORD or PROPERTY_DEVELOPER.

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

supply_points (array, required)

List of supply points linked to the property.

identifier (string, optional)

A unique identifier for a domestic supply point. If not provided, Kraken will generate one for internal use.

spid (string, optional)

The unique supply point identifier. Commercial sites only.

supply_type (string, required)

One of FRESH or WASTE.

supply_start_date (date, required)

The date at which supply started for this property.

pipe_size (integer, optional)

The size of pipe at this property in millimetres.

property_type (string, optional)

Leave empty if it is not applicable to the supply point. One of:

• DETACHED

• SEMI_DETACHED

• TERRACED

• FLAT

inset_reference (string, optional)

The inset reference of the property that the supply point belongs to.

wholesaler_code (string, required)

The wholesaler of the supply point. One of the following:

• AFFINITY (Affinity Water)

• ANGLIAN (Anglian Water)

• BRISTOL (Bristol Water)

• BOURNEMOUTH (Bournemouth Water)

• DWR_CYMRU_WELSH (Dwr Cymru Welsh Water)

• ESSEX_AND_SUFFOLK (Essex & Suffolk Water)

• PORTSMOUTH (Portsmouth Water)

• SES (Sutton and East Surrey Water)

• SEVERN_TRENT (Severn Trent Water)

• SOUTH_EAST (South East Water)

• SOUTH_STAFFORDSHIRE (South Staffordshire Water)

• THAMES (Thames Water)

• UNITED_UTILITIES (United Utilities)

• WESSEX (Wessex Water)

• YORKSHIRE (Yorkshire Water)

• SOUTHERN (Southern Water)

• ICOSA (Icosa Water)

• ALBION (Albion Water)

area_code (string, optional)

The area code that the property is in.

rateable_value (integer, optional)

The rateable value of the property. Required only for unmetered properties.

is_billable (bool, optional)

Set to false if the supply point does not require billing, all supply point details will be stored for information only. If set to false, agreement details must not be provided.

services (array, optional)

A list of (unmetered) services for the property. Only for unmetered waste supply points.

name (string, required)

The name of the service. One of:

• FRESH (Fresh water)

• WASTE (Waste water)

• HIGHWAY_DRAINAGE (Highway drainage)

• SURFACE_DRAINAGE (Surface drainage)

• COMBINED_DRAINAGE (Highway and surface drainage)

• COMBINED_DRAINAGE_ABATED (Abated highway and surface drainage)

• COMBINED_WASTE (Waste water, highway and surface drainage combined)

• COMBINED_WASTE_ABATED (Abated waste water, highway and surface drainage combined)

NB: COMBINED_WASTE & COMBINED_WASTE_ABATED are mutually exclusive and you may only have one of them. The same is true for COMBINED_DRAINAGE & COMBINED_DRAINAGE_ABATED.

active_from (date, required)

The date from which this service was active.

active_to (date, optional)

The date from which this service was terminated.

agreements (array, required)

A list of agreements / contracts that the customer has been on. Historical ones may be included, but there must be no gaps or overlaps on their effective dates.

product_code (string, required)

Code of the product (i.e. tariff). Must match an existing 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 (inclusive).

is_watersure (bool, optional)

Set to true to put the account onto WaterSure (this is stored at the agreement level). If not provided, it will be assumed to be false.

special_rate (string, optional)

Agreement special rate if applicable. One of:

• WATERSURE

• ASSESSED

• SOCIAL

should_ignore_meters (bool, optional)

Set to true when the supply points have a meter but the account has an agreement for an unmeasured product. If set to false or omitted, submitting an unmeasured product for a supply point with a meter(s) returns an error.

meters (array, optional)

List of active and exchanged meters on the meter point.

serial_number (string, required)

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

external_reference (string, required)

Unique identifier of the meter from an external system.

installed_on (date, required)

Meter installation date.

removed_on (date, optional)

Meter removal date, if this was an exchanged meter.

number_of_digits (integer, required)

Number of digits of the meter.

size (integer, required)

The size of the meter in millimetres.

status (string, optional)

The status of the meter. One of:

• IN_USE (default)

• NOT_IN_USE

• REMOVED

• COMPANY_USE

• TURNED_OFF

• CONSUMPTION_SURVEY

make (string, required)

The make of the meter. Can’t be longer than 255 characters.

model (string, required)

The model of the meter. Can’t be longer than 255 characters.

location (string, required)

Where the meter is located in the property. Can’t be longer than 255 characters.

easting (decimal, optional)

Where the meter is located based on OSGB system. Value taken from south-west corner of SV square. Can be up to one decimal place.

northing (decimal, optional)

Where the meter is located based on OSGB system. Value taken from south-west corner of SV square. Can be up to one decimal place.

outreader_easting (decimal, optional)

Where the meter outreader is located based on OSGB system. Value taken from south-west corner of SV square. Can be up to one decimal place.

outreader_northing (decimal, optional)

Where the meter outreader is located based on OSGB system. Value taken from south-west corner of SV square. Can be up to one decimal place.

outreader_location_code (string, optional)

Where the meter outreader is located, one of:

• I - Inside building

• O - Outside building

outreader_location_free_descriptor (string, optional)

Retailer’s free descriptor for the location of the outreader.

capability_type (string, required)

The capability type of the meter. One of:

• MANUAL

• AMR

• AMI

• SMART

category (string, optional)

The category of the meter. Default value is NORMAL. One of:

• NORMAL (not high or low meter)

• HIGH

• LOW

radio_serial_number (string, optional)

The radio serial number associated with a meter.

route_id (string, optional)

The route ID associated with a meter, reflecting the route a meter belongs to.

non_return_to_sewage_allowance (decimal, optional)

The non-return to sewage allowance percentage for this particular meter, if applicable. Can be a decimal.

reading_months (array, required)

The months of the year in which an actual reading is taken from the meter by whatever means. Each month is represented by an integer, with January being 1 i.e. [3, 9] means March and September.

estimation_months (array, optional)

The months of the year in which a reading is estimated for the meter. Each month is represented by an integer, with January being 1, i.e. [3, 9] means March and September.

never_estimate (array, optional)

To prevent the generation of estimated readings for this meter, set this to true. Any values in estimation_months will be ignored.

access_information (string, optional)

Information about accessing the meter, for example, hazardous conditions near the meter.

address_identifier (string, optional)

3rd party data to identify a specific meter location.

services (array, required)

A list of services associated to the meter. Includes both fresh and waste services.

name (string, required)

The name of the service. One of:

• FRESH (Fresh water)

• WASTE (Waste water)

• HIGHWAY_DRAINAGE (Highway drainage)

• SURFACE_DRAINAGE (Surface drainage)

• COMBINED_DRAINAGE (Highway and surface drainage)

• COMBINED_DRAINAGE_ABATED (Abated highway and surface drainage)

• COMBINED_WASTE (Waste water, highway and surface drainage combined)

• COMBINED_WASTE_ABATED (Abated waste water, highway and surface drainage combined)

active_from (date, required)

The date from which this service was active.

active_to (date, optional)

The date from which this service was terminated.

readings (array, required)

List of historical readings.

reading_date (date, required)

Date of the reading.

reading_type (string, required)

One of:

• ESTIMATE

• SMART

• OPS

• CUSTOMER

• METER_READER

reading_value (decimal, required)

Value of the reading in cubic metres.

reading_reason (string, optional)

Reason for this reading. One of:

• ROUTINE (default)

• MOVE_IN

• MOVE_OUT

• INITIAL

• FINAL

billed (bool, optional)

Whether the reading has been billed.

leakage_allowance (decimal, optional)

Value of any associated leakage allowance in cubic metres.

non_household_reading_detail (dict, optional)

Additional detail about a non-household reading.

read_type (string, optional)

The type of NHH reading. One of:

• I - Initial

• F - Final

• X - Temporary disconnection

• Y - Reconnection (following temporary disconnection)

• C - Regular cyclic

• T - Transfer

• P - Pre-loaded

• G - Central systems generated

• W - Wholesaler

estimated_read_reason_code (string, optional)

Reason for a transfer of final read being estimated. One of:

• IML - Cannot locate meter

• OBST - Meter temporarily obstructed

• OBSP - Meter permanently obstructed

• DAM - Meter damaged

• DOR - Out-reader or AMR not working

• DNV - Dials not visible

• MB - Meter buried

• MR - Meter removed

• NMS - New meter in-situ

• NAP - Cannot access premises

• NTA - No transfer read attempted

• HSM - Health and safety issues accessing meter

• LOCP - Cannot locate premises

• CT - Customer read is incorrect or not provided within the agreed timescale

estimated_read_remedial_work_indicator (bool, optional)

Identifies whether remedial action has been obtained for a meter associated with a transfer, when a transfer has been estimated. This is required if estimated_read_reason_code is provided.

non_household_meter_detail (dict, optional)

Additional details about non-household meter.

minimum_reading_frequency (string, required)

One of:

• M - Monthly

• B - Bi-annually (Twice-yearly)

location_code (string, optional)

Where the meter is located, one of:

• I - Inside building

• O - Outside building

has_wholesaler_datalogger (bool, optional)

Specifies the presence of a Wholesaler datalogger. false by default.

has_non_wholesaler_datalogger (bool, optional)

Specifies the presence of a non-Wholesaler datalogger. false by default.

physical_size (int, required)

Nominal size of the meter in mm e.g. for a DN15 meter the Physical Meter Size is 15.

non_household_supply_point_detail (dict, optional)

Additional detail about a non-household supply point.

yearly_volume_estimate (integer, optional)

An estimate of the annual volume supplied in m3.

has_public_health_arrangements (bool, optional)

Whether the supply point has site specific management plan for public health related reasons. false by default.

has_non_public_health_arrangements (bool, optional)

Whether the supply point has site specific management plan for non public health related reasons. false by default.

non_public_health_arrangements_description (string, optional)

Description of the non public health related arrangements.

metered_potable_water_tariff_code (string, optional)

unmeasured_tariff_code (string, optional)

connection_status (string, optional)

The connection status of the supply point. One of:

• REC - Reconnection (default)

• TDISC - Temporary disconnection

• PDISC - Permanent disconnection

• SPERR - SPID exists in error

• NOSP - Supply Point no longer exists

• EXIT - Exit change of use

service_component_types (array, optional)

The service component types of a supply point. Can be:

• MPW - Metered potable water services

• MNPW - Metered non-potable water services

• AW - Assessed water services

• UW - Unmeasured water services

• MS - Metered sewerage services

• AS - Assessed sewerage services

• US - Unmeasured sewerage services

• SW - Surface water drainage services

• HD - Highway drainage services

• TE - Trade effluent services

• WCA - Water charge adjustment service component

• SCA - Sewerage charge adjustment service component

non_household_periods (array, optional)

List of non-household periods for the supply point.

active_from (date, required)

The start date of the non-household period.

active_to (date, optional)

The last inclusive date of the non-household period.

retailer_periods (array, optional)

List of retailer periods for the supply point.

active_from (date, required)

The start date of the retailer period.

active_to (date, optional)

The last inclusive date of the retailer period.

retailer_code (string, required)

The retailer code. Examples:

• ADSM-R

• CASTLE-R

• SMARTA-R

non_household_account_business_detail (dict, required)

A json object containing information about non-household specific business details.

customer_name (string, required)

The customer name.

customer_banner_name (string, optional)

The trading name of the customer at a given eligible premises.

industrial_classification_code (string, optional)

Standard Industrial Classification Code (SIC Code).

industrial_classification_code_type (string, optional)

Identifies the version of the Standard Industrial Classification Code provided. One of:

• 1980

• 1992

• 2003

• 2007

voa_ba_reference (string, optional)

Valuation Office Agency Billing Authority reference number.

voa_ba_reference_reason_code (string, optional)

Code to explain the absence or duplication of a VOA BA reference. One of:

• NR - No number - property not yet rated

• ME - No number - missing entry from the VOA

• AG - No number - agricultural land and buildings

• SR - No number - fish farms, fishing, and sporting rights

• MT - Multiple VOA BA references at the same eligible premises

• IP - No number - infrastructure project

• SP - No number provided - use number from other SPID

• OT - Other

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:

TBC…

Sample payloads:

The request payload can be a list of product objects or a single product object. The product object has the following fields:

brand (string, required)

The brand of the product. The brand will be provided to you.

market_name (string, required)

The market name of the product. The market name is the name of the market that the product is associated with. The market name will be provided to you.

code (string, required)

The code of the product. The code must be unique within the market.

full_name (string, required)

The full name of the product. The full name will be visible on the support site.

display_name (string, required)

The display name of the product. The display name will be shown to customer.

description (string, required)

The description of the product. The description will be shown to customer.

available_from_date (date, required)

The date from which the product is available. The date must be in the format YYYY-MM-DD.

available_to_date (date, optional)

The date until which the product is available. The date must be in the format YYYY-MM-DD.

supply_type (string, required)

The supply type of the product. The supply type must be one of the following values:

• FRESH

• WASTE

is_metered (bool, required)

Whether the product is metered or not.

wholesaler_code (string, required)

The code of the wholesaler. The code must be one of the following values:

• ANGLIAN (Anglian Water)

• BRISTOL (Bristol Water)

• DWR_CYMRU_WELSH (Dwr Cymru Welsh Water)

• ESSEX_AND_SUFFOLK (Essex & Suffolk Water)

• PORTSMOUTH (Portsmouth Water)

• SES (Sutton and East Surrey Water)

• SEVERN_TRENT (Severn Trent Water)

• SOUTH_EAST (South East Water)

• SOUTH_STAFFORDSHIRE (South Staffordshire Water)

• THAMES (Thames Water)

• UNITED_UTILITIES (United Utilities)

• WESSEX (Wessex Water)

• YORKSHIRE (Yorkshire Water)

• SOUTHERN (Southern Water)

applies_to_all_meter_sizes (bool, optional)

Does metered product applies to all meter sizes or not. Default is false, so meter_size must be provided in each standing charge.

consumption_rates (list, required)

The list of consumption rates. The list must contain at least one item.

band (string, required)

Product rate identifier. The band must be unique for a given product and datetime range.

price_per_unit (decimal, required)

Price per unit of consumption. Max decimal places is 5.

valid_from_date (date, required)

The date from which the rate is valid. The date must be in the format YYYY-MM-DD.

valid_to_date (date, optional)

The date until which the rate is valid. The date must be in the format YYYY-MM-DD.

area_code (string, required)

The area code of the rate. Use ALL for all areas.

rate_type (string, required)

The rate type must be one of the following values:

• WHOLESALE

• RETAIL

• COMBINED

property_type (string, required)

The property type of the product. The property type must be one of the following values:

• DETACHED

• SEMI_DETACHED

• TERRACED

• FLAT

• ALL

standing_charges (list, required)

The list of standing charges. The list must contain at least one item.

band (string, required)

Product rate identifier. The band must be unique for a given product and datetime range.

price_per_unit (decimal, required)

Price per unit of consumption. Max decimal places is 5.

valid_from_date (date, required)

The date from which the rate is valid. The date must be in the format YYYY-MM-DD.

valid_to_date (date, optional)

The date until which the rate is valid. The date must be in the format YYYY-MM-DD.

area_code (string, required)

The area code of the rate. Use ALL for all areas.

rate_type (string, required)

The rate type must be one of the following values: - WHOLESALE - RETAIL - COMBINED

meter_size (int, optional)

Meter size for metered product that does not apply to all meter sizes.

property_type (string, required)

The property type of the product. The property type must be one of the following values:

• DETACHED

• SEMI_DETACHED

• TERRACED

• FLAT

• ALL

waste_service_charges (list, optional)

The list of waste service charges. For waste product only.

band (string, required)

Product rate identifier. The band must be unique for a given product and datetime range.

service_name (string, required)

The name of the service. The service name must be one of the following values:

• HIGHWAY_DRAINAGE (Highway drainage)

• SURFACE_DRAINAGE (Surface drainage)

• COMBINED_DRAINAGE (Highway and surface drainage)

• COMBINED_DRAINAGE_ABATED (Abated highway and surface drainage)

• COMBINED_WASTE (Waste water, highway and surface drainage combined)

• COMBINED_WASTE_ABATED (Abated waste water, highway and surface drainage combined)

price_per_unit (decimal, required)

Price per unit of consumption. Max decimal places is 5.

valid_from_date (date, required)

The date from which the rate is valid. The date must be in the format YYYY-MM-DD.

valid_to_date (date, optional)

The date until which the rate is valid. The date must be in the format YYYY-MM-DD.

area_code (string, required)

The area code of the rate. Use ALL for all areas.

rate_type (string, required)

The rate type must be one of the following values:

• WHOLESALE

• RETAIL

• COMBINED

meter_size (int, optional)

Meter size for metered product that does not apply to all meter sizes.

property_type (string, required)

The property type of the product. The property type must be one of the following values:

• DETACHED

• SEMI_DETACHED

• TERRACED

• FLAT

• ALL

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:

Use this end-point to create a payment instruction.

Request:

Sample payload:

The request payload is a single object containing the account information, the instruction type, and the reference that is to be used to retrieve the correct bank or card details from the relevant payment vendor.

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.

vendor (str, required)

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

instruction_reference (string, required)

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

type (string, required)

The type of the payment instruction: DIRECT_DEBIT or CARD. This is used to identify the payment vendor to retrieve the instruction details to store in Kraken from.

If there are validation errors, a 400 Bad Request response will be returned, detailing the errors. This will look something like:

Additional errors will be returned like this

where the error can be one of the errors given below. Unexpected errors are returned in the same format but with a 500 Internal Server Error.

If the payload is valid, a 201 Created response will be returned containing the Kraken account number and the reference:

Possible errors are:

• An account import process with the account number {external_account_number} does not exist for the import supplier {import_supplier_code}.

• Account not found for {external_account_number}

• {external_account_number} has no users - cannot create a payment instruction

• Account already has an active instruction

In addition there could be errors relating to the communication with the payment vendor. We will call their API to verify the instructions existence and retrieve its details to store in Kraken. These will return a 400 Bad Request if they are final, and the request should not be retried in its current form. If they are intermittent, they are returned with a with a 500 Internal Server Error, which means the request should be retried.

Create product rates from csv file. Product rates might be created in bulk by uploading a csv file on the support site /products/{product_code}/rates/batch-create/. Product must already exist in the system.

Csv file is a list of product rates. Each row represents a product rate.

product_code

The product code. Product must already exist in the system.

band

Product rate identifier. The band must be unique for a given product and datetime range.

band_category

The band category must be one of the following values:

• STANDING_CHARGE

• CONSUMPTION_CHARGE

valid_from

The date from which the rate is valid. The date must be in the format YYYY-MM-DD.

valid_to

The date until which the rate is valid. The date must be in the format YYYY-MM-DD.

price_in_pence

Price per unit of consumption. Max decimal places is 5.

area_code

The area code of the rate. Use ALL for all areas.

service

The name of the service. The service name must be one of the following values:

• FRESH (Fresh water)

• WASTE (Waste water)

• HIGHWAY_DRAINAGE (Highway drainage)

• SURFACE_DRAINAGE (Surface drainage)

• COMBINED_DRAINAGE (Highway and surface drainage)

• COMBINED_DRAINAGE_ABATED (Abated highway and surface drainage)

• COMBINED_WASTE (Waste water, highway and surface drainage combined)

• COMBINED_WASTE_ABATED (Abated waste water, highway and surface drainage combined)

meter_size_in_mm

Meter size for metered product that does not apply to all meter sizes. Standing charge only.

property_type

The property type of the product. The property type must be one of the following values:

• DETACHED

• SEMI_DETACHED

• TERRACED

• FLAT

• ALL

rate_type

The rate type must be one of the following values:

• WHOLESALE

• RETAIL

• COMBINED

If there are validation errors, a list or errors will be returned.