The Switch API provides a way for you to retrieve switches from Uswitch as frequently as you wish. You can retrieve and process your new customers from the moment they have finished switching, enabling the customer to receive updates about their switch sooner.
Our API operates on a ‘pull’ pattern — we make the data available, and your application retrieves it. Data is requested from one endpoint in the form of messages. When you have successfully processed a message, you ‘acknowledge’ it by responding to a second endpoint.
A ‘push’ model might seem more intuitive, but there are a number of advantages to our design.
https://staging-api.energy.uswitchsuppliers.comhttps://api.energy.uswitchsuppliers.comThe staging environment is only used for initial onboarding and testing. It does not contain real customer data.
Full swagger references detailing all the parameters with examples may be found at:
Authorisation is not needed to see the swagger references, but is needed to use the endpoints.
Requests to the API are rate-limited, but this should not interfere with normal usage. If your application is attempting to send multiple requests per second, it may cause some requests to be blocked.
See the Authentication section for details.
Example request:
curl --request GET \
--header 'Authorization: Bearer eyJ0eXAiO...Redacted...' \
--url 'https://staging-api.energy.uswitchsuppliers.com/switching/messages/health'
Example response:
{
"msg": "Switch API is OK"
}
In order to keep response sizes manageable, we limit the number of unacknowledged messages returned per request to 50. If you are not seeing new messages, make sure you are correctly acknowledging the messages that are currently being returned once you have successfully received them.
The optional test-switches query parameter filters on
the test_switch flag of each message:
test-switches=true returns test switches only.test-switches=false returns real (non-test) switches
only.false in production, so test
switches are not returned. In other environments it is unset, so all
switches are returned.Example request:
curl --request GET \
--header 'Authorization: Bearer eyJ0eXAiO...Redacted...' \
--url 'https://staging-api.energy.uswitchsuppliers.com/switching/messages/unread'
Example response:
{
"data": [
{
"action": "sale",
"message_id": "7d605099-b7b4-438a-8b43-5ad16f8dd515",
"switch_ref": "e5cc9aa0-739d-4b8f-8aa9-01dfff269b92",
"test_switch": false,
"session_id": "b1f1e1a0-6c1e-4f43-8d6b-2f4d0f5c8a11",
"version": "0.3",
"payload": {
"switched_at": 1548846440000,
...
}
},
...
]
}
If there are no unacknowledged messages, data is an
empty array.
live,
rejected, etc).The request body requires an array of message IDs. Each ID must be a
valid UUID and must belong to one of your messages. If any ID is invalid
or does not exist, none of the messages are acknowledged and a
400 Bad Request response is returned (see below).
Example request:
curl --request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiO...Redacted...' \
--data '["ca9333b6-c475-40c5-8995-a3f87cbb78ff","fc7e7406-f33f-4222-a103-96692c5c25e9"]' \
--url 'https://staging-api.energy.uswitchsuppliers.com/switching/messages/acknowledge'
Example response:
{
"message": "The following message IDs have been acknowledged.",
"data": [
"ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"fc7e7406-f33f-4222-a103-96692c5c25e9"
]
}
Example error response (400 Bad Request, for an
ID that does not exist):
{
"message": "Request contained non existing IDs.",
"data": [
"237e5153-461e-3f94-9aee-10eb59c22f1a"
]
}
A malformed ID returns the message
Request contained invalid IDs. with the offending values in
data.
Intended to be used as a way to retrieve a message for a switch that has already been acknowledged. Useful in recovery scenarios.
Example request:
curl --request GET \
--header 'Authorization: Bearer eyJ0eXAiO...Redacted...' \
--url 'https://staging-api.energy.uswitchsuppliers.com/switching/messages/switch-ref/ca9333b6-c475-40c5-8995-a3f87cbb78ff'
Example response:
{
"data": [
{
"action": "sale",
"message_id": "7d605099-b7b4-438a-8b43-5ad16f8dd515",
"switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"test_switch": false,
"session_id": "b1f1e1a0-6c1e-4f43-8d6b-2f4d0f5c8a11",
"version": "0.3",
"payload": {
"switched_at": 1548846440000,
...
}
},
...
]
}
All events surrounding switches are communicated via immutable
messages. All messages will include a switch-reference, a message-id and
an action. The time of the switch is given by switched_at
in the payload. There may be multiple messages for a single
switch-reference, however the action field will show you how they relate
to each other.
All JSON will be UTF-8 encoded.
Sale messages communicate a customers desire to perform an energy switch. The message schema for sale messages is available here.
Example sale message
Request:
GET /switching/messages/unread
Response:
A 200 OK response of form:
{
"action": "sale",
"message_id": "7d605099-b7b4-438a-8b43-5ad16f8dd515",
"switch_ref": "e5cc9aa0-739d-4b8f-8aa9-01dfff269b92",
"test_switch": false,
"session_id": "b1f1e1a0-6c1e-4f43-8d6b-2f4d0f5c8a11",
"version": "0.3",
"payload": {
"switched_at": 1548846440000,
"supply_address": {
"paf_address": {
"double_dependent_locality": "",
"town": "London",
"county": "",
"thoroughfare": "Copper Row",
"building_number": "5",
"organisation_name": "Uswitch",
"dependent_thoroughfare": "",
"building_name": "The Cooperage",
"po_box": "",
"dependent_locality": "",
"sub_building_name": "",
"post_code": "SE1 2LH"
},
"region_name": "London",
"region_number": "12"
},
"customer_information": {
"correspondence_address": {
"paf_address": {
"building_name": "",
"building_number": "12A",
"county": "Selkirkshire",
"dependent_locality": "",
"dependent_thoroughfare": "",
"double_dependent_locality": "",
"organisation_name": "",
"po_box": "",
"post_code": "TD7 4BT",
"sub_building_name": "",
"thoroughfare": "Market Place",
"town": "Selkirk"
}
},
"previous_addresses": [
{
"previous_number": 1,
"paf_address": {
"building_name": "",
"building_number": "3",
"county": "",
"dependent_locality": "",
"dependent_thoroughfare": "",
"double_dependent_locality": "",
"organisation_name": "",
"po_box": "",
"post_code": "EH1 1YZ",
"sub_building_name": "",
"thoroughfare": "High Street",
"town": "Edinburgh"
},
"duration": {
"years": 2,
"months": 6
}
}
],
"email_address": "test@uswitch.com",
"title": "Dr.",
"given_names": "Henry",
"family_name": "Blake",
"phone_numbers": [
{
"phone_number": "07909123456",
"phone_type": "Mobile"
}
]
},
"product_information": {
"electricity": {
"current_annual_consumption_kwh": 1555,
"current_annual_day_consumption_kwh": 902,
"current_annual_night_consumption_kwh": 653,
"current_payment_method": "Monthly Direct Debit",
"current_personal_projection_pence": 35985,
"current_supplier": "Big Energy",
"current_tariff_name": "Standard (Variable)",
"current_primary_rate_pence": 21.5,
"current_night_rate_pence": 12.3,
"current_standing_charge_pence": 45.2,
"current_exit_fee_pence": 0,
"current_product_end_date": "31/07/2020",
"is_dual_fuel": false,
"is_economy_7": true,
"meter_type": "credit",
"mpan": "2000004115448",
"new_payment_method": "Monthly Direct Debit",
"new_tariff_name": "ABC-DEF-180910",
"new_tariff_night_rate_pence": 18.139,
"new_tariff_primary_rate_pence": 18.139,
"new_tariff_standing_charge_pence": 22.05,
"new_tariff_exit_fee_pence": 500,
"new_tariff_end_date": "31/07/2027",
"new_tariff_rate_guarantee_duration_month": 12,
"quoted_annual_price_pence": 36254,
"tariff_id": "ABC-DEF-180910"
},
"gas": {
"is_dual_fuel": true,
"tariff_id": "ABC-DEF-180910",
"current_personal_projection_pence": 120000,
"new_tariff_standing_charge_pence": 20.445,
"new_payment_method": "Monthly Direct Debit",
"new_tariff_primary_rate_pence": 3.728,
"current_supplier": "Big Energy",
"meter_type": "credit",
"current_payment_method": "Monthly Direct Debit",
"current_annual_consumption_kwh": 28923,
"mprn": "3308152301",
"quoted_annual_price_pence": 115275,
"new_tariff_name": "Fixed Tariff",
"current_tariff_name": "Standard (Variable)",
"current_primary_rate_pence": 3.9,
"current_standing_charge_pence": 27.1,
"current_exit_fee_pence": 0,
"new_tariff_exit_fee_pence": 500
}
},
"bank_details": {
"bank_account_name": "Dr Henry Blake",
"bank_account_number": "12345678",
"bank_name": "Posh Bank PLC",
"bank_sort_code": "123456",
"direct_debit_payment_day": "1"
},
"supplementary_information": {
"has_vulnerabilities": true
},
"billing_consent": true
}
}
Notes:
switch_ref (Mandatory) - is a Unique
reference that you need to store in a database to report switch status
back to Uswitch Reporting API.
supply_address (Mandatory) - Return
paf_address where energy gets supplied. If
correspondence_address is empty, this address is also
billing address.
correspondence_address (Optional) -
Return paf_address if customer select different billing
address. (Only if supplier support different billing address.) - If
correspondence_address is empty, supply and billing address
are the same.
current_annual_consumption_kwh
(Mandatory) - Return annual consumption for electricity
in kwh.
current_annual_day_consumption_kwh
(Optional) - Return annual day consumption for
electricity in kwh only if is_economy_7 is TRUE.
current_annual_night_consumption_kwh
(Optional) - Return annual night consumption for
electricity in kwh only if is_economy_7 is TRUE.
is_economy_7 (Mandatory) - Return TRUE
if a switch uses economy 7 for electricity. - Return FALSE if the tariff
doesn’t support economy 7.
is_dual_fuel (Mandatory) - Return TRUE
if a switch is dual fuel switch.
tariff_id (Mandatory, default: tariff
name) - Identifier of the new tariff. This is the campaign code
or product ID if the supplier provides Uswitch with either, otherwise it
defaults to the tariff name.
new_payment_method (Mandatory) - Return
the payment type that suppliers tariff support. e.g. Monthly Direct
Debit, Prepayment, Variable Direct Debit or Pay on Receipt of Bill - If
supplier’s tariff doesn’t support certain payment types, unsupported
payment types won’t be returned.
current_payment_method (Mandatory) -
Return payment type of current tariff that customer has. e.g. Monthly
Direct Debit, Prepayment, Variable Direct Debit or Pay on Receipt of
Bill
new_tariff_name (Mandatory) - Tariff
chosen by customers which suppliers sell via Uswitch.
current_tariff_name (Mandatory) -
Current tariff that customer has.
bank_details (Optional) - Present when
new_payment_method is not Prepayment (e.g. Monthly Direct
Debit). - Not present if the payment type is Prepayment. -
direct_debit_payment_day is optional within
bank_details.
previous_addresses (Optional) -
Customer’s previous addresses, most recent first. Each entry has a
paf_address and a duration (years
and months, either of which may be null), and may include
previous_number (ordinal 1-4, most recent first) and
address_type (a legacy identifier of the same
ordering).
meter_type (Mandatory) - Either
credit or prepayment.
test_switch and session_id
(Mandatory, message level) - test_switch
is true for test switches. These can be filtered with the
test-switches query parameter on /unread. -
session_id identifies the Uswitch customer session in which
the sale was made.
current_primary_rate_pence,
current_standing_charge_pence,
current_exit_fee_pence (Mandatory) - Unit
rate (Economy 7 day rate if is_economy_7 is TRUE), daily
standing charge and exit fee of the customer’s existing tariff. Rates
include VAT. The Economy 7 night rate is in
current_night_rate_pence (optional).
new_tariff_exit_fee_pence (Mandatory) -
Exit fee of the new tariff in pence.
new_tariff_end_date,
new_tariff_rate_guarantee_duration_month
(Optional) - For fixed tariffs, the date until which
the rate is fixed and the number of months for which it is fixed. May be
null.
current_product_end_date (Optional) -
End date of the customer’s existing tariff.
new_tariff_electricity_variant
(Optional, electricity only) - Electricity meter
variant of the new tariff, e.g. Standard,
Economy 7, EV. Treat unrecognised values as
Standard.
projected_annual_peak_consumption_kwh,
projected_annual_offpeak_consumption_kwh
(Optional, electricity only) - Only present if
new_tariff_electricity_variant is EV. An EV
switcher is usually coming off a single-rate meter, so these are the
peak and off-peak apportionment of
current_annual_consumption_kwh for the new EV tariff. The
two sum to current_annual_consumption_kwh.
supplementary_information (Optional) -
Can have Date Of Birth, Vulnerabilities questions, Marketing consent
etc. - Mandatory if supplier is required to have additionl questions
during the journey - Optional if supplier is using Uswitch default
questions only
billing_consent - For Faster and More Reliable Switch
(FMRS) - True if a customer is happy to move to selected supplier
straight away and consent to being billed for services provided after
the switch, false if the customer wanted to wait until after the cooling
off period. - When at least one fuel is acquisition (moving
supplier from one to the other), this field is
Mandatory. If both fuels are retention (moving
from same supplier to the same supplier), this field will not be
present.