Uswitch Energy Suppliers API

Switch API Developer Guide

  1. Introduction
  2. Environment URLs
  3. Swagger
  4. API Usage
  5. Messages

Introduction

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.

  • It’s impossible for data to be lost. If there is any failure in processing the data, you can simply repeat requests.
  • We take responsibility for maintaining a high-availability system. If your application suffers any outages, you won’t lose switches.
  • You can choose how often to request data. If you are experience high switching volumes, you can space out requests in order to give yourself more time for processing.
  • You can view new switches, and only process them when your system is ready.

Environment URLs

  • Staging: https://staging-api.energy.uswitchsuppliers.com
  • Production: https://api.energy.uswitchsuppliers.com

The staging environment is only used for initial onboarding and testing. It does not contain real customer data.

Swagger

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.

API Usage

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.

1. Obtain the access token from the authentication service

See the Authentication section for details.

2. Optionally check the state of the API service

  • Check if the service is accessible before starting to receive switches.

Swagger reference

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"
}

3. Obtain list of unread switches

  • Returns up to 50 unacknowledged messages, oldest first.
  • Only messages from the last 3 months are returned.
  • Messages can be fetched as many times as required until they are acknowledged.
  • A switch will not appear after it has been acknowledged. You must only acknowledge a switch after you have saved it to permanent storage.
  • All date-time values are integers representing the number of milliseconds since Unix Epoch.

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.
  • If omitted, the default is false in production, so test switches are not returned. In other environments it is unset, so all switches are returned.

Swagger reference

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.

4. Acknowledge receipt of those switches

  • Acknowledging a message only indicates that it has been received sucessfully.
  • Acknowledging a message does not indicate anything about that switch’s reportable status (e.g. 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).

Swagger reference

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.

5. Request all messages for a particular switch reference

  • Returns all messages for the specified switch reference, regardless of if those messages are acknowledged or not.
  • Works for both real and test switches.

Intended to be used as a way to retrieve a message for a switch that has already been acknowledged. Useful in recovery scenarios.

Swagger reference

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,
        ...
      }
    },
    ...
  ]
}

Messages

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

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.