Signup API

Having received a quote for a customer, this API signs a customer up to the Switchd service. This integration allows us to receive information needed for switching a customer’s energy supply. They will receive an email from us confirming this process has been successful.

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
Required
dual If the customer uses gas, this shows whether they are with the same supplier for their electricity supply. 1 (both suppliers the same, default)
0
Required
address The first line of the address of the customer. (address text string). 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 elec tariff a customer is currently on. This can be retrieved from the tariff api. (unique identifier from tariff API) Required
gas_tariff_details_unique_identifier The unique identifier of the gas tariff a customer is currently on. This can be retrieved from the tariff api. (unique identifier from tariff API) Required (if gas = 1 and dual = 0)
elec_tariff_end_date The end date of the electricity tariff. This can be retrieved from the quote API or by asking the customer. (date format dd/mm/yyyy) Required
gas_tariff_end_date The end date of the gas tariff. This can be retrieved from the quote API or by asking the customer. (date format dd/mm/yyyy) Required (if gas = 1 and dual = 0)
electricity_day_kwh A customer’s annual electricity usage in kWh. If the customer only knows their electricity usage by spend or if they don’t know it, the usage can be retrieved from the quote API. (numerical value) Required
electricity_night_kwh A customer’s annual night electricity usage in kWh. If the customer only knows their night electricity usage by spend or if they don’t know it, the usage can be retrieved from the quote API. (numerical value) Required (economy_7 = 1)
gas_kwh A customer’s annual night electricity usage in kWh. If the customer only knows their night electricity usage by spend or if they don’t know it, the usage can be retrieved from the quote API. (numerical value) Required (gas = 1)
move_month Month the customer moved into their current property. 01,02,03,04,05,06,07,08,09,10,11,12 (01 denoting January) Required
move_year Year customer moved into their current property. (numerical string, 4 characters) Required
title The customer title for energy bills. Mr, Mrs, Miss, Ms, Dr (we can accept additional salutations) Required
first_name The customer first name for energy bills. (text string) Required
surname The customer surname for energy bills. (text string) Required
email Email address that will be used to both send details of switches but also to log into a Switchd account. (text string) Required
phone Phone number is required for future energy suppliers to be able to contact the customer. (numerical string) Required
residential_status Residential status is required by most energy suppliers to complete a switch. home_owner, tenant, landlord Required
DOB Customer date of birth is required by most energy suppliers to complete a switch. (date format dd/mm/yyyy) Required
plan_option You can find our various pricing plans on our website. Which pricing plans you offer may be dictated by our terms agreement. If you are using the quote API it is important to state that the free plan does not save as much as the paid plans. free, lite, standard, premium Required
personal_data The customer can select whether they give consent to us for sending them emails with exciting news about us. 1 (consents), 0 (defult) 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
full_length_name This is the full length name of the customer for the bank. It is recommended that this is asked of the customer. If left blank we will concatenate the first name and surname of the customer. (text string) Recommended
account_number Account number of the customer for both their energy supplier and Switchd subscription. If this is left blank they will be able to add these from their Switchd dashboard and we will send follow-ups to try to get these details. (numerical value of 8 numbers) Recommended
sort_code Sort code of the customer for both their energy supplier and Switchd subscription. If this is left blank they will be able to add these from their Switchd dashboard and we will send follow-ups to try to get these details. (numerical value of 6 numbers) Recommended
billing_check Is the customers billing address different from their residential address. 1 (details are different), 0 (default) Recommended
billing_address Billing address for this customer. (text string) Recommended (if billing check = 1)
billing_postcode Billing postcode for this customer. (text string) Recommended (if billing check = 1)
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
password This is the password that will be used for the Switchd account. This can be left blank and they will be asked to set this up at a later date. (text string) Optional

Code Query (PHP)


This query is posts to the post_customers URL whilst passing the API key grant a sign up. 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',
	'address' => '10a, Shalimar Road',
	'postcode' => 'W39JD',
	'elec_tariff_details_unique_identifier' => '20558',
	'gas_tariff_details_unique_identifier' => '20558',
	'elec_tariff_end_date' => '01/01/2020',
	'gas_tariff_end_date' => '01/01/2020',
	'electricity_day_kwh' => '300',
	'electricity_night_kwh' => '500',
	'gas_kwh' => '700',
	'move_month' => '01',
	'move_year' => '2012',
	'title' => 'Mr',
	'first_name' => 'James',
	'surname' => 'Smith',
	'email' => 'test@switchd.co.uk',
	'phone' => '07929081581',
	'residential_status' => 'home_owner',
	'DOB' => '27/04/1988',
	'plan_option' => 'standard',
	'personal_data' => '1',
	'economy_7' => '',
	'full_length_name' => '',
	'account_number' => '',
	'sort_code' => '',
	'billing_check' => '',
	'billing_address' => '',
	'billing_postcode' => '',
	'green' => '',
	'payment_method' => '',	
	'password' => '',
);
$json = json_encode($data);

curl_setopt_array($curl, array(
	CURLOPT_URL => "https://api.switchd.co.uk/post_customer.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
result Returns a result so you can trigger the next action inserted_successfully
error_code Error code if tariff call fails api_key_not_valid (invalid API key)
postcode_not_supported (invalid postcode)
no_tariffs_param (there are no tariffs given the parameters provided)