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.
Endpoint: api.switchd.co.uk/post_customer
Ensure that you include api-key in your header, available through our partnership team
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 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 |
| 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 |
Example Json
"gas" : "1",
"dual" : "1",
"address" : "test address",
"postcode" : "W39JD",
"elec_tariff_details_unique_identifier" : "28382",
"gas_tariff_details_unique_identifier" : "28382",
"elec_tariff_end_date" : "",
"gas_tariff_end_date" : "",
"electricity_day_kwh" : "300",
"electricity_night_kwh" : "0",
"gas_kwh" : "700",
"move_month" : "01",
"move_year" : "2012",
"title": "Mr",
"first_name" : "James",
"surname" : "Smith",
"email" : "test_api@switchd.co.uk",
"phone" : "00000",
"residential_status" : "home_owner",
"DOB" : "27/04/1988",
"plan_option" : "standard",
"personal_data" : "1",
"economy_7" : "",
"full_length_name" : "James Smith",
"account_number" : "01234567",
"sort_code" : "012345",
"billing_check" : "",
"billing_address" : "",
"billing_postcode" : "",
"green" : "1",
"payment_method" : "direct_debit",
"password" : "password"
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 | postcode_not_supported (invalid postcode) no_tariffs_param (there are no tariffs given the parameters provided) |
