Quote API

Your customers could get an instant savings quote with this integration. Getting access to this API allows you to retrieve three different sets of information:

  1. List of all energy suppliers (through the ‘Get Supplier API’)
  2. List of all tariffs provided by a chosen supplier (through the ‘Get Tariff API’)
  3. Estimated savings quote for switching with us (through the ‘Get Quote API’)

1) Get Supplier API

This API returns the full list of energy suppliers. We also show who the most common suppliers are, which allows for a default selection to the largest suppliers. This list can be fed into a form on your platform so the customer can select the supplier they are currently with.

It does not require you to send any information to us. You can find the details on the information we’d pass to you in the ‘Response JSON’ in the ‘Technical information’ section.

Code Query (PHP)


This query is retrieving the getsupplier URL whilst passing the API key to get access. We can provide additional language support, just contact us at team@switchd.co.uk to request another language.


$curl 	= curl_init();
curl_setopt_array($curl, array(
	CURLOPT_URL => "https://api.switchd.co.uk/get_suppliers.php",
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_ENCODING => "",
	CURLOPT_MAXREDIRS => 10,
	CURLOPT_TIMEOUT => 30,
	CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
	CURLOPT_CUSTOMREQUEST => "GET",
	CURLOPT_HTTPHEADER => array(
		"Api-Key: YOURAPIKEY",
		"content-type: application/json",
	)
));

$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if($err) {
	echo $err;
}
else {
	echo $response;
}

Response JSON


Variable Description Possible Values
supplier_name Supplier name that can be used for quote API or passed into sign up API (supplier text string)
most_common This denotes the largest six suppliers by customer base. This facilitates defaulting to the largest suppliers. 1 (most common)
0

2) Get Tariff API

This API returns the full list of tariffs for a given supplier. This list can be fed into a form on your platform so the customer can select the tariff they are currently on. It requires you to send a few pieces of information to allow us to send over the correct list of tariffs.The more information you can give, the more accurate the savings will be.

Required information:

  • Current supplier (chosen from list sent by ‘Get Supplier API’)
  • Postcode
  • Fuel type (dual fuel, single electricity or single gas supply)
See list of recommended and optional information you could pass to us under ‘Post Variables’ in the Technical information section. You can also find the details on the information we’d pass to you in the ‘Response JSON’ in the Technical information section.

Post Variables


Variable Description Possible Values Required Variable
supplier The supplier to retrieve tariff list for. (Suppliers retrieved from supplier API) Required
postcode The postcode of the customer. This will define which of the 14 UK regions the customer lives in. (UK postcode, excludes Northern Ireland). Required
tariff_type Type of tariff the customer is on, identifying if the tariff is electricity only, only gas or both gas and electricity. DualGasAndElectricity (default)
SingleElectricity
SingleGas
Required
economy_7 The customer can select to have an Economy 7 meter (dual-rate meter). This allows us to retrieve tariffs for those who have a dual rate-meter, where they pay different rates during the day and at night. 0 (default)
1 (is economy 7)
Recommended
payment_method How the customer currently pays for their energy. monthly_direct_debit (default)
receipt_of_bill
quarterly_direct_debit
prepay
Optional
error_code Error code if tariff call fails api_key_not_valid (invalid API key)

Code Query (PHP)


This query is retrieving the gettariff URL whilst passing the API key to get access and relevant variables. We can provide additional language support, just contact us at team@switchd.co.uk to request another language.


$curl 	= curl_init();

$data = array(
	'supplier' => 'British Gas',
	'postcode' => 'W39JD',
	'tariff_type' => 'DualGasAndElectricity',
	'economy_7' => '1',
	'payment_method' => 'monthly_direct_debit'
);
$json = json_encode($data);

curl_setopt_array($curl, array(
	CURLOPT_URL => "https://api.switchd.co.uk/get_tariffs.php",
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_ENCODING => "",
	CURLOPT_MAXREDIRS => 10,
	CURLOPT_TIMEOUT => 30,
	CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
	CURLOPT_CUSTOMREQUEST => "POST",
	CURLOPT_POSTFIELDS => $json,
	CURLOPT_HTTPHEADER => array(
		"Api-Key: YOURAPIKEY",
		"content-type: application/json",
	)
));

$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if($err) {
	echo $err;
}
else {
	echo $response;
}

Response JSON


Variable Description Possible Values
tariff_id Tariff unique identifier that should be passed into the quote API. (numerical unique identifier)
tariff_name Tariffs (provided by current supplier) that can be displayed to the customer to choose their current tariff. (tariff text string)
most_common This denotes the most common tariff for a given supplier. This can be used as the default tariff returned to improve signup flow. 1 (most common)
0
need_end_date Some tariffs do not have a defined end date. For a completely accurate quote we can ask for this from the customer. 1 (end date required)
0
error_code Error code if tariff call fails api_key_not_valid (invalid API key) postcode_not_supported (invalid postcode)
no_tariffs_supplier (there are no tariffs for the supplier provided)

3) Get Quote API

This API returns the savings quote for switching to the cheapest energy supplier. It requires you to send a few pieces of information to allow us to send over the correct quote.

The more information you can give, the more accurate the savings will be.

See the list of required, recommended and optional pieces of information you should pass to us under ‘Post Variables’ in the Technical information section. You can also find the details on the information we’d pass to you in the ‘Response JSON’ in the Technical information section.

Post Variables


Variable Description Possible Values Required Variable
gas This tells us if customer uses gas. 1 (gas included, default)
0 (no gas)
Required
dual If customer uses gas, is the gas supply with the same supplier as the electricity? 1 (both suppliers the same, default)
0
Required
postcode The postcode of the customer. This will define which of the 14 UK regions the customer lives in. (UK postcode, excludes Northern Ireland). Required
elec_tariff_details_unique_identifier The unique identifier of the electricity tariff a customer is currently on. (unique identifier from tariff api) Required
gas_tariff_details_unique_identifier The unique identifier of the gas tariff a customer is currently on (unique identifier from tariff api) Required (if gas = 1 and dual = 0)
usage_type This is the type of usage value a customer provides for their quote. low (1-2 people)
medium (3-4 people, default)
high (5+ people)
spend (if you know monthly spend)
kwh (if you know annual kwh usage)
Required
electricity_day_kwh A customer’s annual electricity usage in kWh. (numerical value) Required (if usage_type = kwh)
electricity_night_kwh A customer’s annual night electricity usage in kWh. (numerical value) Required (if usage_type = kwh and economy_7 = 1)
gas_kwh A customer’s annual gas usage in kWh. (numerical value) Required (if usage_type = kwh and gas = 1)
electricity_spend Monthly electricity spend. (numerical value) Required (if usage_type = spend)
night_percentage Monthly electricity spend at night. (numerical value) Required (if usage_type = spend and economy_7 = 1)
gas_spend Monthly gas spend. (numerical value) Required (if usage_type = spend and gas = 1)
economy_7 The customer can select to have an Economy 7 meter (dual-rate meter). This allows us to retrieve tariffs for those who have a dual rate-meter, where they pay different rates during the day and at night. 0 (default)
1 (is economy 7)
Recommended
elec_tariff_end_date If need end date from tariff API is 1, the end date of the electricity tariff. (date format dd/mm/yyyy) Recommended
gas_tariff_end_date If need end date from tariff API is 1, the end date of the gas tariff. (date format dd/mm/yyyy) Recommended (if gas = 1 and dual = 0)
green Customer selects whether they want green-only tariffs. 1 (green only)
0 (either green or not, default)
Optional
payment_method How the customer wants to pay for their energy in the future. direct_debit (default)
receipt_of_bill
prepay
Optional

Code Query (PHP)


This query is retrieving the getquote URL whilst passing the API key to get access and relevant variables. We can provide additional language support, just contact us at team@switchd.co.uk to request another language.


$curl 	= curl_init();

$data = array(
	'gas' => '1',
	'dual' => '1',
	'postcode' => 'W39JD',
	'elec_tariff_details_unique_identifier' => '20558',
	'gas_tariff_details_unique_identifier' => '20558',
	'usage_type' => 'spend',
	'electricity_day_kwh' => '',
	'electricity_night_kwh' => '',
	'gas_kwh' => '',
	'electricity_spend' => '50',
	'night_percentage' => '',
	'gas_spend' => '40',
	'economy_7' => '0',
	'elec_tariff_end_date' => '',
	'gas_tariff_end_date' => '',
	'fixed_variable' => '',
	'green' => '',
	'payment_method' => '',
);
$json = json_encode($data);

curl_setopt_array($curl, array(
	CURLOPT_URL => "https://api.switchd.co.uk/get_quote.php",
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_ENCODING => "",
	CURLOPT_MAXREDIRS => 10,
	CURLOPT_TIMEOUT => 30,
	CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
	CURLOPT_CUSTOMREQUEST => "POST",
	CURLOPT_POSTFIELDS => $json,
	CURLOPT_HTTPHEADER => array(
		"Api-Key: YOURAPIKEY",
		"content-type: application/json",
	)
));

$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if($err) {
	echo $err;
}
else {
	echo $response;
}

Response JSON


Variable Description Possible Values
should_switch_exit Is it worth switching today. This takes into account whether it's worth paying exit fees or should wait until tariff ends. 1 (should switch today), 0
electricity_day_kwh The electricity kwh assumed through the quote API (numerical value, in kwh)
electricity_night_kwh The electricity night kwh assumed through the quote API (numerical value, in kwh)
gas_kwh The gas kwh assumed through the quote API (numerical value, in kwh)
elec_tariff_end_date Date when the current electricity tariff will come to an end (date dd/mm/yyyy)
gas_tariff_end_date Date when the current gas tariff will come to an end (date dd/mm/yyyy)
total_exit_fee_price The amount the customer will need to pay to end their current tariff (numerical value, in pounds)
saving The amount saved over 12 months in accordance with Ofgem personal projection saving calculation. This may include saving by avoiding a tariff price increase. (numerical value, in pounds)
new_supplier The supplier name for the deal found. (text string)
new_supplier_image_link Image location of the new supplier. (url)
new_tariff_name The tariff name for the deal found. (text string)
new_tariff_fixed_variable Details of whether the new tariff will be fixed or variable. Fixed
Variable
new_elec_annual_standing_charge The fee paid per year for electricity regardless of energy consumption. (numerical value, in pounds p.year)
new_elec_day_price_per_kwh Unit rate per kwh for electricity used in the day (all day if economy_7 = 0). (numerical value, in pence p. kwh)
new_elec_night_price_per_kwh Unit rate per kwh for electricity used in the night (for economy_7 = 1 only). (numerical value, in pence p. kwh)
new_gas_annual_standing_charge The fee paid per year for gas regardless of energy consumption. (numerical value, in pounds p.year)
new_gas_price_per_kwh Unit rate per kwh for gas used. (numerical value, in pence p. kwh)
free_saving Saving available for commission only tariffs, as provided on our free plan. (numerical value, in pounds)
variable_fixed_difference The difference in cost between being on a fixed tariff vs a variable tariff. (numerical value, in pounds p.year)
error_code Error code if tariff call fails. api_key_not_valid (invalid API key)
postcode_not_supported (invalid postcode) electricity_tariff_incorrect (incorrect elec tariff) gas_tariff_incorrect (incorrect gas tariff)