Switch API | Developer Guide

Switch API Developer Guide

Introduction
Environment URLs
Swagger
API Usage
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:

Staging: staging-api.energy.uswitchsuppliers.com/switching/messages/docs/index.html
Production: api.energy.uswitchsuppliers.com/switching/messages/docs/index.html

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.
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.

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",
      "version": "0.3",
      "payload": {
        "switched_at": 1548846440000,
        ...
      }
    },
    ...
  ]
}

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.

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

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.

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",
      "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, an action and a timestamp. 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",
  "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"
        }
      },
      "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)",
        "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,
        "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)"
      }
    },
    "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) - If supplier doesn’t provide Uswitch an identifier of a tariff, default to 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) - Mandatory if the payment type is Monthly Direct Debit. - Optional if the payment type is Prepayment.

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.

Uswitch Energy Suppliers API