Some API end-points accept datetime strings as parameters. These should be passed in ISO 8601 format. Eg:

We strongly recommend that timezone information is included on all datetime parameters. If no timezone information is included, the “Europe/London” timezone will be assumed and results may vary between GMT and British Summer Time.

Return a list of energy products.

By default, results will be public energy products but if the authenticated organisations will also see products available to their organisation.

Authentication: public and authenticated.

Request:

Parameters:

is_variable (boolean, optional)

Show only variable products.

is_green (boolean, optional)

Show only green products.

is_tracker (boolean, optional)

Show only tracker products.

is_prepay (boolean, optional)

Show only pre-pay products.

is_business (boolean, default: false)

Show only business products.

available_at (datetime, default: now)

Show products available for new agreements on the given datetime. Defaults to current datetime, effectively showing products that are currently available.

Response:

A 200 OK response of form:

Notes:

The key term is the number of months that a product lasts for if it is fixed length.

Retrieve the details of a product (including all its tariffs) for a particular point in time.

Request:

Arguments:

product_code

The code of the product to be retrieved, for example VAR-17-01-11.

Parameters:

tariffs_active_at (datetime, default: now)

The point in time in which to show the active charges. Defaults to current datetime.

Responses:

A 200 OK response with:

Notes:

• The key term is the number of months that a product lasts for if it is fixed length.

• Each *_tariffs object will have up to 14 keys; one for each GSP. For each GSP the applicable tariffs are listed under their associated payment method, e.g. direct_debit_monthly.

• Tariff charges are calculated for the tariffs_active_at datetime parameter.

• The keys standard_unit_rate_* are listed in p/kWh (pence per kilowatt hour).

• The keys standing_charge_* are listed in p/day (pence per day).

• The keys annual_cost_* are listed in p (pence).

• Historical charges can be browsed using the URLs contained under the key links.

Return a list of unit rates and standing charges.

Request:

Arguments:

product_code

The code of the product to be retrieved, for example VAR-17-01-11.

tariff_code

The code of the tariff to be retrieved, for example E-1R-VAR-17-01-11-A.

Parameters:

period_from (datetime, optional)

Show charges active from the given datetime (inclusive). This parameter can be provided on its own.

period_to (datetime, optional)

Show charges active up to the given datetime (exclusive). You must also provide the period_from parameter in order to create a range.

page_size (int, optional)

Page size of returned results. Default is 100, maximum is 1,500 to give up to a month of half-hourly prices.

Response:

A 200 OK response with:

Retrieve the details of a meter-point.

This endpoint can be used to get the GSP of a given meter-point.

Request:

Arguments:

mpan

The electricity meter-point’s MPAN.

Response:

A 200 OK response with:

Return a list of consumption values for half-hour periods for a given meter-point and meter.

Unit of measurement:

• Electricity meters: kWh

• SMETS1 Secure gas meters: kWh

• SMETS2 gas meters: m^3

Request:

Arguments:

mpan / mprn

The electricity meter-point’s MPAN or gas meter-point’s MPRN.

serial_number

The meter’s serial number.

Parameters:

period_from (datetime, optional)

Show consumption from the given datetime (inclusive). This parameter can be provided on its own.

period_to (datetime, optional)

Show consumption to the given datetime (exclusive). This parameter also requires providing the period_from parameter to create a range.

page_size (int, optional)

Page size of returned results. Default is 100, maximum is 25,000 to give a full year of half-hourly consumption details.

order_by (string, optional)

Ordering of results returned. Default is that results are returned in reverse order from latest available figure. Valid values: * ‘period’, to give results ordered forward. * ‘-period’, (default), to give results ordered from most recent backwards.

group_by (string, optional)

Aggregates consumption over a specified time period. A day is considered to start and end at midnight in the server’s timezone. The default is that consumption is returned in half-hour periods. Accepted values are: * ‘hour’ * ‘day’ * ‘week’ * ‘month’ * ‘quarter’

Response:

A 200 OK response with:

Return a list of GSP objects, optionally filtered by postcode:

Authentication: public

Request:

Parameters:

postcode (string, optional)

A postcode to filter on.

Response:

A 200 OK response with a list of GSP objects:

Note, if we’re unable to map the passed postcode to a GSP, an empty list will be returned.

Request:

Sample payload:

Sample business products only payload:

Arguments:

electricity_meter_points / gas_meter_points (required)

An array of object with the following members.

At least one electricity or gas meter-point must be included. A maximum of one electricity and one gas meter-point can included at this time. For all meter-points, at least one of gsp or postcode must be included. All meter-points must be based in the UK, excluding Northern Ireland. All meter-points must belong to the same gsp or postcode.

For an electricity meter-point, at least one of consumption_standard or a combination of consumption_day and consumption_night must be included. For three register meters, consumption_day, consumption_night and consumption_off_peak must be included.

For a gas meter-point, consumption_standard must be included.

gsp

The grid supply point.

postcode

The postcode of the property. You only need to provide this if you are unable to provide a gsp.

consumption_standard

The standard consumption of a single register electricity or gas meter-point.

consumption_day

The day consumption of a dual or three register electricity meter-point.

consumption_night

The night consumption of a dual or three register electricity meter-point.

consumption_off_peak

The off-peak consumption of a three register electricity meter-point.

has_smart_meter

Whether a smart meter is installed. The default is false.

mpan

The MPAN of the electricity meter-point, required when creating business quotes.

brand_code (string, optional)

A code to specify the account should be for a particular brand. This is only required when creating an account in an instance with multiple brands and for which the requested brand is not the default brand of that instance.

product_codes (required)

An array of product codes to create quotes for.

business_products_only

Whether to create business quotes instead of domestic. The default is false. When set to true only a single electricity meter-point must be included with an associated mpan.

Responses:

A successful submission will receive a 201 Created response with:

Any validation errors will receive a 400 Bad Request response detailing the errors. The error response payload will take the same field structure as the request payload, eg:

Use this endpoint after quote creation to send a quote summary email to the specified recipients if they wish to enact the quote at a later time. A quote share record is saved to the database for each recipient’s email address.

Request:

where quote_code is the code of a generated quote and product_id is the ID of the quoted product that the customer has selected from the choice of quoted products in the generated quote.

Sample payload:

Arguments:

emails (required)

An array of one or more email addresses to send the quote share email to.

Response:

If a quote with quote_code or quoted product with product_id does not exist, a 404 Not Found response will be returned.

If there are validation errors, a 400 Bad Request response will be returned, detailing the errors in the following format:

If there are no validation errors and a quote and quoted product was found, a 204 No Content response will be returned.

This end-point allows an account to be created.

Request:

Sample payload:

Parameters:

reference (string, max 64 chars, required)

A unique partner reference. The reference provided should be unique per switch. Requests where a duplicate reference has been provided and the existing enrolment has not previously been rejected will receive a 400 Bad Request response.

account_reference (string, max 128 chars, optional)

A unique reference to previous external account number or similar account identifier. The account reference must be in NAMESPACE-VALUE format.

sold_at (string, required)

A datetime of when the account sale was made.

account_type (string, required)

One of DOMESTIC or BUSINESS.

brand_code (string, optional)

A code to specify the account should be for a particular brand. This is only required when creating an account in an instance with multiple brands and for which the requested brand is not the default brand of that instance.

source (string, required)

One of CALL_CENTRE_INBOUND, CALL_CENTRE_OUTBOUND, FACE_TO_FACE or INTERNET.

sales_channel (string, optional)

One of DIRECT, PRICE_COMPARISON, TELESALES, DIGI_TELESALES, EVENTS, FIELD_SALES, AGGREGATOR, PARTNERSHIPS, NEW_TENANT, MOVE_IN, WORKPLACE_POP_UP, BROKER.

sales_subchannel (string, optional)

An optional segmentation of the sales channel, e.g. the names of the specific price comparison site, or the telesales organisation.

affiliate (object, optional)

An object with the following fields.

signup_reward_code (str, optional)

The code of an existing signup reward referral scheme that will be used for giving credit to the created account as a signup reward.

organization_name (str, optional)

The name of an existing organization that will be used to create an account for an affiliate.

quote_code (str, optional)

The code of an existing legacy quote created using the legacy CreatQuote mutation as part of the join supplier journey for this new customer. If the quote was generated as part of an affiliate session, the affiliate link and any query parameters belonging to the session will be associated with the created account.

Note: only one of quote_code and quote_request_code should be provided in the input.

quote_request_code (str, optional)

The code of an existing quote which was created using the QuoteNewMeterPoints mutation as part of the join supplier journey for this new customer. If the quote was generated as part of an affiliate session, the affiliate link and any query parameters belonging to the session will be associated with the created account.

Note: only one of quote_code and quote_request_code should be provided in the input.

is_change_of_tenancy (string, required)

Whether this account is a change of tenancy at the property.

referral_code (string, optional)

The referral code of an existing account linked to a Kraken referral scheme.

smart_meter_read_permission (string, optional)

One of MONTHLY, DAILY or HALF_HOURLY. This is the read permission frequency the occupier grants to meter readings from smart meters.

requires_postal_comms (boolean, optional)

Communication delivery preference, when requires_postal_comms is True, then set to POSTAL, else set to EMAIL, when not provided it will be null.

smart_meter_interest (string, optional)

One of SMETS2_INTEREST_INTERESTED, SMETS2_INTEREST_NOT_AT_THE_MOMENT or SMETS2_INTEREST_NOT_INTERESTED. The occupier’s interest in installing a smart meter.

smart_onboarding_product_type (string, optional)

A code to indicate which type of smart tariff the customer is meant to onboard onto. This is a restricted option. Please get in touch for information on whether this can be enabled and what the allowed options are.

preferred_ssd (string, optional)

A preferred supply start date. Only include this field if the earliest possible supply start date is not preferred.

payment (string, optional)

An object with the following members. The payment details are required when using the method MONTHLY_DIRECT_DEBIT but are optional if all the meters are of type PREPAYMENT. The MONTHLY_DIRECT_PAYMENT method is not available to all users.

method (string, required)

One of MONTHLY_DIRECT_DEBIT or MONTHLY_DIRECT_PAYMENT or BILL_TRIGGERED_DIRECT_DEBIT.

account_name (string, conditional, max 255 chars)

The name associated with the bank account.

account_number (string, conditional)

The bank account number.

account_sort_code (string, conditional)

The bank account sort code.

payment_day (string, conditional)

The preferred day of the month for the payment request. Must be in the range of 1-28. Only required for MONTHLY_DIRECT_DEBIT schedules.

billing_address (string, required)

An object with the following members.

address_line_1 (string, required, max 512 chars)

address_line_2 (string, conditional, max 512 chars)

address_line_3 (string, conditional, max 512 chars)

town (string, required, max 512 chars)

county (string, conditional, max 512 chars)

postcode (string, required, max 8 chars)

users (string, required)

An array of objects with the following members.

A maximum of one user can be included at this time. At least one of mobile or landline must be included.

title (string, optional, max 255 chars)

given_name (string, required, max 255 chars)

family_name (string, required, max 255 chars)

date_of_birth (string, optional)

email (string, required, max 512 chars)

Cannot be a email already in use for an existing account.

mobile (string, conditional, max 64 mobile)

landline (string, conditional, max 64 mobile)

opted_in_for_marketing (string, required)

opted_in_to_third_parties (bool, optional)

credit_score_data (Optional)

An optional object but if present in the users structure it has to have the following required fields.

score (int, required)

risk_bracket (string, required)

One of LOW, MID, HIGH, or UNKNOWN.

psr (conditional)

An object with the following optional members describing Priority Services Register (PSR) details for the user.

requires_signup (boolean, conditional)

A boolean to indicate that the user should be signed up to the PSR but the categories are unknown. Therefore the user requires contacting to determine which categories.

electricity_meter_points / gas_meter_points (required)

An array of objects with the attributes specified below.

Note:

• At least one electricity or gas meter-point must be included.

• A maximum of two electricity and one gas meter-point can be included.

• All meter-points must be based in the Great Britain.

• All meter-points must belong to the same address.

For an electricity meter-point, at least one of mpan or address must be included. At least one of consumption_standard (standard tariff) or a combination of consumption_day and consumption_night (two-rate tariff) or consumption_day, consumption_night and consumption_off_peak (three-rate tariff) must be included depending on the type of tariff specified.

For a gas meter-point, at least one of mprn or address must be included, as well as consumption_standard.

tariff_code (string, max 255 chars, required if no ``quote_request_code``)

The tariff code as stored by the supplier. Must match an available tariff on the sold_at datetime for the authenticating partner. Required if no quote_request_code is supplied.

quoted_product_id (int, required if ``quote_request_code`` is supplied)

The ID of the market supply quoted product returned by the QuoteNewMeterPoints or QuoteNewMeterPointsOnBespokeProducts mutation which was selected by the customer for this meter point. Required if a quote_request_code is supplied.

quote (required)

An object with the following members.

annual_payment (int, required)

The estimated annual payment for this meter-point based on consumption. This value must be provided in pence. For business quotes, the price is exclusive of VAT, while for non-business quotes, it should be inclusive of VAT.

consumption_standard (int, required if standard tariff)

The expected annual consumption for the standard register in kWh.

consumption_day (int, required if eco7 or three-rate tariff)

The expected annual consumption for the day/peak register in kWh.

consumption_night (int, required if eco7 or three-rate tariff)

The expected annual consumption for the night/off-peak register in kWh.

consumption_off_peak (int, required if three-rate tariff)

The expected annual consumption for the additional off-peak register in kWh.

mpan / mprn (string, conditional, max 13 chars)

The meter-point identifier.

address (conditional)

An object with the following members.

address_line_1 (string, conditional, max 512 chars)

address_line_2 (string, optional, max 512 chars)

address_line_3 (string, optional, max 512 chars)

town (string, conditional, max 512 chars)

county (string, optional, max 512 chars)

postcode (string, conditional, max 8 chars)

meter_type (string, optional)

One of CREDIT or PREPAYMENT. The default is CREDIT, which represents any kind of traditional credit meter or smart meter. This field is mandatory for traditional prepay meters, for which the value PREPAYMENT should be used.

has_smart_meter (boolean, optional)

Whether a smart meter is installed. The default is false.

current_supplier_name (string, optional, max 255 chars)

current_supplier_tariff (string, optional, max 255 chars)

metadata (list, 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.

To create business accounts, business details are also required.

business (required)

An object with the following members.

name (string, required)

The name of the business.

number (string, optional)

The registered number of the business. This field is required for LIMITED businesses.

business_type (string, required)

One of SOLE_TRADER, LIMITED, PARTNERSHIP, CHARITY, or GOVERNMENT.

is_ccl_exempt (string, required)

Whether the business is excempt from paying CCL (Climate Change Levy).

is_vat_exempt (string, required)

Whether the business is excempt from paying VAT.

head_count (int, optional)

The head count of the business, i.e. number of staff.

annual_turnover (int, optional)

The estimated annual turnover in pounds £ (GBP).

unit_rate_uplift (float, optional)

The amount to be added to the unit rate as commission (a string, pence per kWh).

bespoke_tariff_rates (dict, optional)

A json object containing bespoke tariff rates, if applicable. Cannot be used in conjunction with bespoke_pps_tariff_rates.

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.

unit_rates (array, optional)

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

rate_type (string, required)

The rate type of the unit rate. One of: STANDARD or ECO7_DAY or ECO7_NIGHT or OFF_PEAK.

unit_rate (decimal, required)

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

bespoke_pps_tariff_rates (array, optional)

An array of json objects containing bespoke PPS tariff rates, if applicable. If supplied, the array must contain exactly 2 objects, one for direct debit bespoke rates and another for non-direct debit bespoke rates. Cannot be used in conjunction with bespoke_tariff_rates.

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 rate. One of: DD (Direct debit) or NDD (Non-direct debit).

unit_rates (array, optional)

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

rate_type (string, required)

The rate type of the unit rate. One of: STANDARD or ECO7_DAY or ECO7_NIGHT or OFF_PEAK.

unit_rate (decimal, required)

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

Responses:

A successful submission will receive a 201 Created response with a payload of form:

A submission which has incurred an error, but requires further investigation from a member of our team in order to complete the request, will receive a 202 Accepted response with a payload:

Submissions that incur validation errors that cannot be fixed by a member of our team will receive a 400 Bad Request response detailing the errors.

Note that all serializers in this file that raise a ValidationError should first save an AccountEnrolmentEvent. To do this simply call one of:

• _raise_enrolment_validation_error_not_for_manual_investigation(…)

• _raise_enrolment_validation_error(…)

As opposed to passing validators directly into serializer fields, we should write a custom validate method which returns _validate_field(…), e.g:

This end-point allows a new agreement to be created for an existing account. It is restricted to business accounts.

Request:

Sample payload:

Parameters:

agreements (array, required)

List of all agreements to be created to the given account.

mpxn (string, required)

MPRN or MPAN of the meter point getting a new agreement.

tariff_code (string, required)

Tariff code for the new agreements.

valid_from_date (date, required)

Date (inclusive) the new agreement is valid from. The format should be “%Y-%m-%d”.

valid_to_date (date, optional)

Date (exclusive) the new agreement is valid to. The format should be “%Y-%m-%d”.

bespoke_tariff_rates (array, optional)

Bespoke tariff rates for the new agreement, if applicable.

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

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

registers (array, optional)

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

register_identifier (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_identifier is not provided, the rate type must be provided instead.

unit_rate (decimal, required)

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

commission (dict, optional)

Commission applicable to this tariff renewal.

affiliate_organisation_name (string, required)

Name of the affiliate organisation due the commission for this agreement.

affiliate_link_subdomain (string, optional)

Sub-domain of the affiliate link due the commission for this agreement.

unit_rate_uplift (decimal, required)

Uplift in pence to be paid to the affiliate.

Responses:

A successful submission will receive a 201 Created response with the original payload and an additional field for the account number, e.g. the below for a simple original payload.

Any validation or domain errors will receive a 400 Bad Request response detailing the errors, such as

If the account does not exist, a 404 Not Found response is returned.

If incorrect authentication is used, a 401 Unautharized response is returned.

If the caller has insufficient permissions for this action, a 403 Forbidden response is returned.

In case of an intermittent error, a 500 Internal Server Error response is returned. If the error persists, please get in touch with the support team.

Possible validation errors are: * Affiliate organisation {name} does not exist. * Electricity meter point with MPAN {mpxn} does not exist. * Gas meter point with MPRN {mpxn} does not exist. * Unknown meter point type for {mpxn}. * No {fuel_type} tariff found for the tariff code {tariff_code}. * Agreement valid_to_date {valid_to_date} cannot be earlier than agreement valid_from_date {valid_from_date} * A register with identifier {register_identifier} does not exist on meter {meter_serial_number} on meter point {mpxn}. * A meter with serial number {meter_serial_number} does not exist on meter point {mpxn}. * If commission data is provided the agreement needs to have an end date. * One of register_identifier and rate_type must be provided for bespoke electricity rates. * Duplicate bespoke rates received for {mpxn}. * Bespoke tariff rates are not currently supported.

Possible domain errors are: * Account with number {account_number} does not exist * Account is not a business account * Current agreement on meter point is not for the same account * Current agreement already has a follow on agreement * Current agreement does not end at new agreement start date * More than one contract in place for meter point * Current meter point contract terminates after new agreement start date * More than one future agreement in place