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:
- List of all energy suppliers (through the ‘Get Supplier API’)
- List of all tariffs provided by a chosen supplier (through the ‘Get Tariff API’)
- Estimated savings quote for switching with us (through the ‘Get Quote API’)
1) Get Supplier API
Endpoint: api.switchd.co.uk/get_suppliers
Ensure that you include api-key in your header, available through our partnership team
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.
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 Tariffs API
Endpoint: api.switchd.co.uk/get_tariffs
Ensure that you include api-key in your header, available through our partnership team
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.
If you do not know the tariff, use the get_tariffs call and then find the tariff that has field most common
Required information:
- Current supplier (chosen from list sent by ‘Get Supplier API’)
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). London postcode default. | Recommended |
| 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 |
Recommended |
| 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 |
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 | postcode_not_supported (invalid postcode) no_tariffs_param (there are no tariffs given the parameters provided) no_supplier_provided (no supplier given) |
3) Get Quote API
Endpoint: api.switchd.co.uk/get_quote
Ensure that you include api-key in your header, available through our partnership team
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 |
|---|---|---|---|
| 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) |
| gas | This tells us if customer uses gas. | 1 (gas included, default) 0 (no gas) |
Recommended |
| dual | If customer uses gas, is the gas supply with the same supplier as the electricity? | 1 (both suppliers the same, default) 0 |
Recommended |
| postcode | The postcode of the customer. This will define which of the 14 UK regions the customer lives in. | (UK postcode, excludes Northern Ireland). | Recommended |
| 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) |
Recommended |
| electricity_day_kwh | A customer’s annual electricity usage in kWh. | (numerical value) | Recommended (if usage_type = kwh) |
| electricity_night_kwh | A customer’s annual night electricity usage in kWh. | (numerical value) | Recommended (if usage_type = kwh and economy_7 = 1) |
| gas_kwh | A customer’s annual gas usage in kWh. | (numerical value) | Recommended (if usage_type = kwh and gas = 1) |
| electricity_spend | Monthly electricity spend. | (numerical value) | Recommended (if usage_type = spend) |
| night_percentage | Monthly electricity spend at night. | (numerical value) | Recommended (if usage_type = spend and economy_7 = 1) |
| gas_spend | Monthly gas spend. | (numerical value) | Recommended (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 |
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. | postcode_not_supported (invalid postcode) |
