Uswitch Energy Partners API

Partners API Developer Guide

  1. Authentication
  2. Endpoint summary
  3. Endpoint reference

Authentication

See the Authentication section for details.

Environment URLs

There are production and staging environments, delineated by URL.

Production: https://api.partners.uswitch.com/energy/docs/index.html
Staging: https://staging-api.partners.uswitch.com/energy/docs/index.html

The staging environment should be only used for testing and may not serve current production data.

Endpoint Summary

Available endpoints (all environments):

GET /energy/status
GET /energy/docs/index.html
GET /energy/suppliers
GET /energy/plans
GET /energy/comparison
GET /energy/best-buys/{best_buy_type}
POST /energy/drop

  

GET /energy/status

Returns a response indicating the health of the service.

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/status'

Example response:

{
  "msg": "Partner API is OK",
  "environment": "STAGING API for partners",
  "request-from": "test-partner"
}

  

GET /energy/docs/index.html

Swagger documentation. This is best viewed in a browser, you must set the authorization header to view.

See Endpoint reference

  

GET /energy/suppliers

Returns the list of suppliers covering the postcode and also a list of fuel, payment type and meter variant combinations allowed by the suppliers tariffs. The support may be have been historical, i.e. Customers might still be contracted to these plans, but that does not guarantee that the supplier is still offering this combination for new customers.

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/suppliers?post_code=SW1A%201AA&fuel=electricity'

Example response:

{
  "suppliers": [
    {
      "big_six": false,
      "logo_url": "https://uswitch-cms.imgix.net/uswitch-imgix/energy/supplier-logos/ovo.png",
      "key": "ovo",
      "name": "OVO Energy",
      "incumbent": false,
      "plan_types": [
        {
          "fuel": "dual_fuel",
          "payment_method": "pay_on_receipt_of_bill",
          "electricity_variant": "economy_7"
        },
        {
          "fuel": "electricity",
          "payment_method": "monthly_direct_debit",
          "electricity_variant": "standard"
        },
        {
          "fuel": "gas",
          "payment_method": "monthly_direct_debit"
        },
        {
          "fuel": "gas",
          "payment_method": "pay_on_receipt_of_bill"
        },
        {
          "fuel": "dual_fuel",
          "payment_method": "monthly_direct_debit",
          "electricity_variant": "standard"
        },
        {
          "fuel": "electricity",
          "payment_method": "prepayment",
          "electricity_variant": "standard"
        },
        {
          "fuel": "electricity",
          "payment_method": "prepayment",
          "electricity_variant": "economy_7"
        },
        {
          "fuel": "dual_fuel",
          "payment_method": "prepayment",
          "electricity_variant": "economy_7"
        },
        {
          "fuel": "dual_fuel",
          "payment_method": "prepayment",
          "electricity_variant": "standard"
        },
        {
          "fuel": "electricity",
          "payment_method": "pay_on_receipt_of_bill",
          "electricity_variant": "economy_7"
        },
        {
          "fuel": "electricity",
          "payment_method": "monthly_direct_debit",
          "electricity_variant": "economy_7"
        },
        {
          "fuel": "dual_fuel",
          "payment_method": "monthly_direct_debit",
          "electricity_variant": "economy_7"
        },
        {
          "fuel": "electricity",
          "payment_method": "pay_on_receipt_of_bill",
          "electricity_variant": "standard"
        },
        {
          "fuel": "dual_fuel",
          "payment_method": "pay_on_receipt_of_bill",
          "electricity_variant": "standard"
        }
      ],
      "fulfillable": true,
      "retainable": false,
      "support_phone_number": "0330 303 5063"
    }
 ]
}

Error Responses

HTTP Status Code Description
400 missing-required-parameter The request was invalid because it is missing parameters that are mandatory (e.g., post_code).
400 invalid-parameter-value The request was invalid because it contains parameters that have values that are incorrect (e.g., specifying a fuel that is not one of gas, electricity or dual_fuel).
404 postcode-not-found The provided postcode was not recognised.

Example response:

{
  "errors": [
    { "code": "postcode-not-found",
      "message": "The provided postcode was not recognised",
      "parameters": {
        "post_code": "SW1B1AA"
      }
    }
  ]
}
{
    "errors": [
        {
            "code": "missing-required-parameter",
            "message": "The request was invalid because of missing required parameters.",
            "parameters": {
                "post_code": null
            }
        },
        {
            "code": "invalid-parameter-value",
            "message": "The request was invalid because of parameters that have values that are incorrect. Please refer to documentation for further details.",
            "parameters": {
                "fuel": "dualfuel"
            }
        }
    ]
}

  

GET /energy/plans

List the plans available from a given supplier.

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/plans?post_code=SW1A%201AA&fuel=electricity&supplier_key=so-energy&payment_method=monthly_direct_debit&electricity_variant=standard'

Example response:

{
  "plans": [
    {
      "key": "copy-of-so-ladybird-1518596365",
      "needs_end_date": true,
      "name": "So Leopard",
      "standard_variable": false,
      "fulfillable": false,
      "feature_labels": [
        "green",
        "fixed"
      ],
      "product_end_date": null,
      "available_to_switch": false,
    },
    {
      "key": "so-out-of-contract-1454669402",
      "needs_end_date": false,
      "name": "So Out of Contract",
      "standard_variable": true,
      "fulfillable": false,
      "feature_labels": [
        "paper_billing",
        "no-exit-fee"
      ],
      "product_end_date": null,
      "available_to_switch": false,
    },
    {
      "key": "copy-of-so-leopard-1519665892",
      "needs_end_date": true,
      "name": "So Lion",
      "standard_variable": false,
      "fulfillable": false,
      "feature_labels": [
        "green",
        "fixed"
      ],
      "product_end_date": null,
      "available_to_switch": false,
    }
 ]

Error Responses

HTTP Status Code Description
400 missing-required-parameter The request was invalid because it is missing parameters that are mandatory (e.g., post_code).
400 invalid-parameter-value The request was invalid because it contains parameters that have values that are incorrect (e.g., specifying a fuel that is not one of gas, electricity or dual_fuel).
404 postcode-not-found The provided postcode was not recognised.

Example response:

{
  "errors": [
    { "code": "postcode-not-found",
      "message": "The provided postcode was not recognised",
      "parameters": {
        "post_code": "SW1B1AA"
      }
    }
  ]
}
{
    "errors": [
        {
            "code": "missing-required-parameter",
            "message": "The request was invalid because of missing required parameters.",
            "parameters": {
                "electricity_variant": null
            }
        },
        {
            "code": "invalid-parameter-value",
            "message": "The request was invalid because of parameters that have values that are incorrect. Please refer to documentation for further details.",
            "parameters": {
                "fuel": "dualfuel"
            }
        }
    ]
}

GET /energy/plan-lookup

This finds the plan with the rates closest to the rates provided. This is intended for use only where you know the rates (e.g. from smart metering information), but not plan name.

Returns the a single plan that most closely matches supplied characteristics. If supplier is given, the plans will be from that supplier. The plan will be a direct debit plan and of the standard variant (economy 7 is not supported).

A plan will be returned even if no “close” plan can be found for the rates provided. Callers should check the rates returned to judge how closely they match the provided rates.

Supplier key is optional, but increases the chance of correctly identifying the correct plan.

A duel fuel plan will be returned if gas_rate_pence_per_kwh and gas_charge_pence_per_day are provided, otherwise a electricity plan will be returned.

The response will be a object with the key "plan" and the value being a plan object.

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/plan-lookup?electricity_charge_pence_per_day=19.5&electricity_rate_pence_per_kwh=24.3&post_code=E9%207NQ&supplier_key=british-gas'

Example response:

{
  "plan": {
    "key": "7110a717-32a4-41d6-b8c4-e00281902842",
    "needs_end_date": false,
    "name": "Online Fixed Nov 2023",
    "electricity_charge_pence_per_day": 19.588,
    "standard_variable": false,
    "supplier_name": "British Gas",
    "electricity_rate_pence_per_kwh": 24.381,
    "fulfillable": false,
    "feature_labels": [
      "green",
      "fixed"
    ],
    "product_end_date": "2023-11-30",
    "available_to_switch": false,
    "supplier_name_key": "british-gas"
  }
}

Error Responses

HTTP Status Code Description
400 missing-required-parameter The request was invalid because it is missing parameters that are mandatory (e.g., post_code).
400 invalid-parameter-value The request was invalid because it contains parameters that have values that are incorrect
404 postcode-not-found The provided postcode was not recognised.

Example response:

{
  "errors": [
    { "code": "postcode-not-found",
      "message": "The provided postcode was not recognised",
      "parameters": {
        "post_code": "SW1B1AA"
      }
    }
  ]
}
{
    "errors": [
        {
            "code": "missing-required-parameter",
            "message": "The request was invalid because of missing required parameters.",
            "parameters": {
                "electricity_variant": null
            }
        },
        {
            "code": "invalid-parameter-value",
            "message": "The request was invalid because of parameters that have values that are incorrect. Please refer to documentation for further details.",
            "parameters": {
                "electricity_charge_pence_per_day": "X"
            }
        }
    ]
}

  

GET /energy/comparison

Perform an energy comparison.

The returned plans are in ordered of ascending cost (i.e., the cheapest plans first).

Many of the parameters are optional when considered individually, but are required in combination with other parameters. See below for further details.

Required parameters

  • post_code
  • fuel (one of dual_fuel, gas or electricity)

Dual-Fuel Comparisons

Requires either:

  • dual_fuel_supplier_key
  • dual_fuel_plan_key

Or:

  • electricity_supplier_key
  • electricity_plan_key
  • gas_supplier_key
  • gas_plan_key

The latter example should be used in the case where a customer is on different suppliers or plans for their electricity and gas supply.

A plan end-date (dual_fuel_end_date, electricity_end_date or gas_end_date) can optionally be provided when the plan has a fixed end-date.

A plan payment method (dual_fuel_payment_method, electricity_payment_method or gas_payment_method) can optionally be provided. When not provided a default of monthly_direct_debit will be used.

Usage must be supplied for both fuels (see below).

Single-Fuel Comparisons

An electricity-only comparison requires:

  • electricity_supplier_key
  • electricity_plan_key

A gas-only comparison requires:

  • gas_supplier_key
  • gas_plan_key
  • electricity_supplier_key
  • electricity_plan_key

Uswitch does not support users that do not have an electricity supply. Therefore electricity plan and usage details must be provided.

A plan end-date (electricity_end_date or gas_end_date) can optionally be provided for each fuel when the plan has a fixed end-date.

A plan payment method (electricity_payment_method or gas_payment_method) can optionally be provided. When not provided a default of monthly_direct_debit will be used.

The possible payment method options are monthly_direct_debit, variable_direct_debit, pay_on_receipt_of_bill, or prepayment.

The possible values for supplier parameters can be discovered using the /energy/suppliers endpoint.

The possible values for plan parameters can be discovered using the /energy/plans endpoint.

Electricity Variant The electricity meter type must be specified using the electricity_variant parameter. Valid values are standard or economy_7.

Specifying Usage

Energy usage must be specified for all fuels that are part of a comparison (i.e., gas and electricity must be specified for dual fuel)

Usage can be specified by either:

  • Actual annual usage in kWh (electricity_usage_kwh, gas_usage_kwh)
  • Customer spend over a specified time period (electricity_spend_pence & electricity_spend_frequency, gas_spend_pence & gas_spend_frequency)
  • Estimated usage (electricity_usage_estimate, gas_usage_estimate)

Spend periods are one of annual, quarterly or monthly

The estimated usage values are one of low, medium or high and based on Ofgem’s Typical Domestic Consumption Values.

Comparisons for Economy-7 meters that are based on actual annual usage or customer spend must also specify the percent_night_usage parameter which is expressed as a percentage between 1 an 99.

Optional parameters

  • limit Limits the number of plans returned in a comparison. Defaults to 10.
  • offset Excludes a number of the first results. Defaults to 0.

Response description

The response will consist of a object containing a comparison key which has an array of comparison objects. Each object will provide a plan key the value of which explains the plan attributes.

Explanatory notes:

- Plans can have a rate guarantee indicating that the rate will not change, either until a specific end-date or for a duration from signup. It is possible to have neither, e.g. Bulb's Vari-Fair.
- `personal_projection` lists the projected cost of this plan for 365 days and explains the breakdown of the calculation
- `features` are the features of this plan as provided by the supplier.
- `saving_pence` is Current spend minus personal projection total
- `name` is the plan name as set by supplier
- `name_key` is the Uswitch's identifier for the plan
- `supplier_name` is the Supplier's brand name
- `supplier_key` is Uswitch's identifier for the supplier
- `exit_fees` provides details of exit fees - fields: `total_fee_pence`, `gas_fee_pence`, `electricity_fee_pence`

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/comparison?post_code=se12lh&fuel=dual_fuel&electricity_variant=standard&new_payment_method=monthly_direct_debit&dual_fuel_supplier_key=british-gas&dual_fuel_plan_key=standard&dual_fuel_payment_method=monthly_direct_debit&gas_usage_kwh=16500&electricity_usage_kwh=8200&limit=1'

Example response:

{
  "comparison": {
    "id": "72be8a40-0c50-4800-908a-79bbde20785e",
    "comparisons": [
      {
        "item_id": "a435dd62-fcd7-48df-81bb-28ecc4bb879e",
        "plan": {
          "features": [
            {
              "title": "Online account management - no need for paper bills"
            },
            {
              "title": "So Energy do not currently offer the Warm Home Discount",
              "description": "The Warm Home Discount is a government scheme that provides a one-off rebate to households receiving the Guarantee Credit element of Pension Credit."
            },
            {
              "title": "100% renewable electricity",
              "description": "So Energy lets their customers decide how their 100% renewable electricity is generated, whether its wind, solar, hydroelectric, biomass or tidal."
            },
            {
              "title": "Your first payment will be taken on your supply start date",
              "description": null
            }
          ],
          "key": "copy-of-so-yak---green-1576143292",
          "name": "So Zebra - Green",
          "supplier_key": "so-energy",
          "supplier_name": "So Energy",
          "fulfillable": true,
          "exit_fees": {
            "total_fee_pence": 1000,
            "gas_fee_pence": 500,
            "electricity_fee_pence": 500
          },
          "product_end_date": null,
          "rate_guarantee": {
            "end_date": null,
            "duration": 12,
            "description": "The rate you pay per kWh stays the same for 12 months from the day your switch is processed"
          }
        },
        "personal_projection": {
          "total_pence": 172002,
          "gas_total_pence": 52598,
          "electricity_total_pence": 119404,
          "current": {
            "gas": {
              "breakdown": [
                {
                  "type": "consumption",
                  "value_pence": 42428.1,
                  "rate_pence_per_kWh": 2.57,
                  "usage_kWh": 16500
                },
                {
                  "type": "standing-charge",
                  "value_pence": 7665,
                  "charge_pence_per_day": 21
                },
                {
                  "type": "tax",
                  "value_pence": 2504.66
                }
              ],
              "total_pence": 52598
            },
            "electricity": {
              "breakdown": [
                {
                  "type": "consumption",
                  "value_pence": 106053.06,
                  "rate_pence_per_kWh": 12.93,
                  "usage_kWh": 8200
                },
                {
                  "type": "standing-charge",
                  "value_pence": 7665,
                  "charge_pence_per_day": 21
                },
                {
                  "type": "tax",
                  "value_pence": 5685.9
                }
              ],
              "total_pence": 119404
            },
            "total_pence": 172002
          }
        },
        "saving_pence": 51758
      }
    ]
  }
}

Error Responses

HTTP Status Code Description
400 missing-required-parameter The request was invalid because it is missing parameters that are required for the fuel or variant being compared (e.g., percent_night_usage for an economy_7 comparison with electricity_usage_kwh specified).
400 disallowed-parameter The request was invalid because it contains parameters that are invalid for the fuel or variant being compared (e.g., gas_supplier for an electricity comparison).
400 invalid-parameter-value The request was invalid because it contains parameters that have values that are incorrect (e.g., specifying a fuel that is not one of gas, electricity or dual_fuel).
404 postcode-not-found The provided postcode was not recognised.
404 plan-not-found The plan for comparison could not be found. This occurs when a plan with the given name is not available for the given combination of supplier, postcode, payment method and variant.

Example responses:

{
  "errors": [
    { code": "postcode-not-found",
      "message": "The provided postcode was not recognised",
      "parameters": {
        "post_code": "sw1b1aa"
      }
    }
  ]
}
{
  "errors: [
    { "code": "plan-not-found",
      "message": "The plan for comparison could be found",
      "parameters": {
        "gas_payment_method": "monthly_direct_debit",
        "gas_plan": "standard",
        "gas_supplier": "made-up-energy-supplier",
        "post_code": "sw1a1aa",
        "electricity_variant": "standard"
      }
    }
  ]
}
{
    "errors": [
        {
            "code": "missing-required-parameter",
            "message": "The request was invalid because of missing required parameters.",
            "parameters": {
                "electricity_variant": null
            }
        },
        {
            "code": "invalid-parameter-value",
            "message": "The request was invalid because of parameters that have values that are incorrect. Please refer to documentation for further details.",
            "parameters": {
                "fuel": "dualfuel"
            }
        }
    ]
}

  

GET /energy/valuation

Perform an energy valuation, i.e. convert usage to annual cost for a particular plan, payment method.

The parameters and parameter validation are the same as comparison, excluding limit and new_payment_method which are not applicable.

Given that a plan may terminate during the coming year, the calculation will also reference the plan to which the customer would rollover after the expected rollover date.

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/valuation?electricity_payment_method=monthly_direct_debit&electricity_plan_key=copy-of-bg-homeenergy-fix-apr-2019-1523352618&electricity_supplier_key=british-gas&fuel=dual_fuel&electricity_usage_kwh_estimate=medium&gas_usage_kwh_estimate=medium&post_code=SW1A%201AA&electricity_variant=standard&gas_payment_method=monthly_direct_debit&gas_supplier_key=ovo&gas_plan_key=copy-of-simpler-energy-1549299855'

Example response:

{
  "valuation": {
    "total_pence": 119842,
    "gas": {
      "personal_projection": {
        "total_pence": 60180,
        "gas_total_pence": 60180,
        "current": {
          "gas": {
            "breakdown": [
              {
                "type": "consumption",
                "value_pence": 48240,
                "rate_pence_per_kWh": 4.02,
                "usage_kWh": 12000
              },
              {
                "type": "standing-charge",
                "value_pence": 9073.9,
                "charge_pence_per_day": 24.86
              },
              {
                "type": "tax",
                "value_pence": 2865.69
              }
            ],
            "total_pence": 60180
          },
          "total_pence": 60180
        }
      },
      "plan_duration": {
        "rollover": false,
        "rollover_treatment": "no-end-date-fallback",
        "days_on_current_plan": null,
        "rollover_date": null,
        "reference_date": null
      },
      "plan": {
        "features": [
          {
            "title": "3-5% interest on account credit balances",
            "description": "If your energy account is in credit, you will receive 3% interest on the credit amount\r\n\r\n * This is automatically credited to your account monthly\r\n * The maximum credit balance which can earn OVO Interest Reward is £1,000."
          },
          {
            "title": "Your first payment will be taken on or shortly after your supply start date",
            "description": null
          }
        ],
        "key": "copy-of-simpler-energy-1549299855",
        "name": "Simpler Energy (gas only)",
        "supplier_key": "ovo",
        "supplier_name": "OVO Energy",
        "fulfillable": false,
        "exit_fees": null,
        "product_end_date": null,
        "rate_guarantee": {
          "end_date": null,
          "duration": null,
          "description": "The rate you're paying per kWh may change if OVO Energy changes its prices"
        }
      },
      "rollover_plan": {
        "features": [
          {
            "title": "3-5% interest on account credit balances",
            "description": "If your energy account is in credit, you will receive 3% interest on the credit amount\r\n\r\n * This is automatically credited to your account monthly\r\n * The maximum credit balance which can earn OVO Interest Reward is £1,000."
          },
          {
            "title": "Your first payment will be taken on or shortly after your supply start date",
            "description": null
          }
        ],
        "key": "copy-of-simpler-energy-1549299855",
        "name": "Simpler Energy (gas only)",
        "supplier_key": "ovo",
        "supplier_name": "OVO Energy",
        "fulfillable": false,
        "exit_fees": null,
        "product_end_date": null,
        "rate_guarantee": {
          "end_date": null,
          "duration": null,
          "description": "The rate you're paying per kWh may change if OVO Energy changes its prices"
        }
      }
    },
    "electricity": {
      "personal_projection": {
        "total_pence": 59662,
        "electricity_total_pence": 59662,
        "current": {
          "electricity": {
            "breakdown": [
              {
                "type": "consumption",
                "value_pence": 15814.25,
                "rate_pence_per_kWh": 14,
                "usage_kWh": 1129.59
              },
              {
                "type": "standing-charge",
                "value_pence": 3172.05,
                "charge_pence_per_day": 23.85
              },
              {
                "type": "tax",
                "value_pence": 949.31
              }
            ],
            "total_pence": 19936
          },
          "total_pence": 19936
        },
        "rollover": {
          "electricity": {
            "breakdown": [
              {
                "type": "consumption",
                "value_pence": 32767.93,
                "rate_pence_per_kWh": 16.63,
                "usage_kWh": 1970.41
              },
              {
                "type": "standing-charge",
                "value_pence": 5066.42,
                "charge_pence_per_day": 21.84
              },
              {
                "type": "tax",
                "value_pence": 1891.72
              }
            ],
            "total_pence": 39726
          },
          "total_pence": 39726
        }
      },
      "plan_duration": {
        "rollover": true,
        "rollover_treatment": "fixed-plan",
        "days_on_current_plan": 133,
        "rollover_date": "2020-05-01",
        "reference_date": "2019-12-19"
      },
      "plan": {
        "features": [
          {
            "title": "If British Gas raise their prices, yours will never go up",
            "description": null
          },
          {
            "title": "No exit fees if you switch between British Gas tariffs",
            "description": null
          },
          {
            "title": "Only available to switch to online",
            "description": null
          }
        ],
        "key": "copy-of-bg-homeenergy-fix-apr-2019-1523352618",
        "name": "HomeEnergy Secure Apr 2020",
        "supplier_key": "british-gas",
        "supplier_name": "British Gas",
        "fulfillable": true,
        "exit_fees": {
          "total_fee_pence": 4000
        },
        "product_end_date": "2020-04-30",
        "rate_guarantee": {
          "end_date": "2020-04-30",
          "duration": null,
          "description": "The rate you pay per kWh stays the same until 30th April 2020"
        }
      },
      "rollover_plan": {
        "features": [
          {
            "title": "If British Gas raise their prices, yours will never go up",
            "description": null
          },
          {
            "title": "No exit fees if you switch between British Gas tariffs",
            "description": null
          }
        ],
        "key": "copy-of-temporary-december-2020-1571126130",
        "name": "Temporary May 2021",
        "supplier_key": "british-gas",
        "supplier_name": "British Gas",
        "fulfillable": false,
        "exit_fees": null,
        "product_end_date": "2021-05-31",
        "rate_guarantee": {
          "end_date": null,
          "duration": 0,
          "description": "The rate you're paying per kWh may change if British Gas changes its prices"
        }
      }
    },
    "usage": {
      "gas": 12000,
      "electricity": 3100
    }
  }
}

  

GET /energy/best-buys/{best_buy_type}

List the the best buy plans of a particular type.

Possible types are

  • big-six-standard-plans
  • cheapest-economy-7-plans
  • cheapest-electricity-only-plans
  • cheapest-green-plans
  • cheapest-plans-fixed-only
  • cheapest-plans-variable-and-fixed-whole-market
  • cheapest-plans-variable-and-fixed cheapest-ppm-plans
  • fixed-plans-ending-soon

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/best-buys/big-six-standard-plans'

Example response:

{
  "meta": {
    "filters": {
      "fuel-type": "dual-fuel",
      "payment-method": "Monthly Direct Debit",
      "variant": "Standard"
    },
    "big_six": [
      "sse",
      "swalec",
      "edf",
      "scottish-hydro-electric",
      "southern-electric",
      "british-gas",
      "npower",
      "e-dot-on",
      "scottishpower"
    ],
    "only_standard_plans": true,
    "standard_plan_keys": [
      "online-energy",
      "standard",
      "e-dot-on-energy-plan"
    ]
  },
  "plans": [
    {
      "average_personal_projection": 117727,
      "name": "E.ON Energy Plan",
      "supplier_name": "E.ON",
      "supplier_key": "e-dot-on",
      "rate_guarantee": {
        "available": null,
        "fixed": false,
        "duration": null,
        "description": "The rate you're paying per kWh may change if E.ON changes its prices",
        "end_date": null
      },
      "exit_fee": 0
    },
    {
      "average_personal_projection": 117727,
      "name": "Standard (Variable)",
      "supplier_name": "EDF Energy",
      "supplier_key": "edf",
      "rate_guarantee": {
        "available": null,
        "fixed": false,
        "duration": null,
        "description": "The rate you're paying per kWh may change if EDF Energy changes its prices",
        "end_date": null
      },
      "exit_fee": 3000
    },
    {
      "average_personal_projection": 117774,
      "name": "Standard",
      "supplier_name": "SSE",
      "supplier_key": "sse",
      "rate_guarantee": {
        "available": null,
        "fixed": false,
        "duration": null,
        "description": "The rate you're paying per kWh may change if SSE changes its prices",
        "end_date": null
      },
      "exit_fee": 3000
    },
    {
      "average_personal_projection": 117849,
      "name": "Standard Online",
      "supplier_name": "ScottishPower",
      "supplier_key": "scottishpower",
      "rate_guarantee": {
        "available": null,
        "fixed": false,
        "duration": null,
        "description": "The rate you're paying per kWh may change if ScottishPower changes its prices",
        "end_date": null
      },
      "exit_fee": 0
    },
    {
      "average_personal_projection": 117850,
      "name": "Standard SC",
      "supplier_name": "npower",
      "supplier_key": "npower",
      "rate_guarantee": {
        "available": null,
        "fixed": false,
        "duration": null,
        "description": "The rate you're paying per kWh may change if npower changes its prices",
        "end_date": null
      },
     "exit_fee": 0
    }
  ]
}

Error Responses

HTTP Status Code Description
400 invalid-parameter-value The request was invalid because it contains parameters that have values that are incorrect (e.g., specifying an unrecognized best_buy_type).

Example responses:

{
    "errors": [
        {
            "code": "invalid-parameter-value",
            "message": "The request was invalid because of parameters that have values that are incorrect. Please refer to documentation for further details.",
            "parameters": {
                "best_buy_type": null
            }
        }
    ]
}

  

POST /energy/drop

Create a session with Uswitch and generate a URL to redirect the user to continue their switch.

In order to create a session and generate a URL, you will need to provide the following information about a user:

  • their post_code and electricity_variant
  • their current plan (gas, electricity, dual_fuel)
  • their usage (electricity_usage, gas_usage)
  • their selected plan (selected_plan)

as well as attribution information that can relate switches back to you. Attribution information is partner specific.

You can read more information in the endpoint reference.

Valid switch combinations

Depending on their current plan, we are not able to support some switches.

The fuel combinations must be compatible:

  • If the current plan is dual_fuel the selected_plan.fuel can be dual_fuel or electricity
  • If the current plan is electricity the selected_plan.fuel can only be electricity
  • If the current plan is a combination of electricity and gas, the selected_plan.fuel can be dual_fuel, electricity or gas
  • If the current plan is only gas, we cannot support any switches. You can use the fuel parameter on the comparison endpoint to make sure the user only sees suitable plans.

If they are not compatible you will see this error:

{
  "code": "invalid-fuel-selected",
  "message": "The request was invalid because switching to the selected fuel-type from the user's current fuel-type is not supported.",
}

The payment methods must be compatible:

  • If the current plan’s payment_method is prepayment, the selected_plan.payment_method must be prepayment.
  • If the current plan’s payment_method is monthly_direct_debit, variable_direct_debit, or pay_on_receipt_of_bill, the selected_plan.payment_method can be monthly_direct_debit, variable_direct_debit, or pay_on_receipt_of_bill You can use the new_payment_method parameter on the comparison endpoint to make sure the user only sees suitable plans.

If they are not compatible you will see this error:

{
  "code": "invalid-payment-method-selected",
  "message": "The request was invalid because the selected payment-type is not supported for the user's meter type.",
}

The electricity variant must match You should use the electricity_variant parameter on the comparison endpoint to make sure the user only sees suitable plans.

Full example

{
  "attribution": {
    "utm_campaign": "CAMPAIGN",
    "utm_content": "CONTENT"
  },
  "dual_fuel": {
    "payment_method": "monthly_direct_debit",
    "plan_key": "standard",
    "supplier_key": "edf"
  },
  "electricity_usage": {
    "estimate": "medium"
  },
  "electricity_variant": "standard",
  "gas_usage": {
    "estimate": "medium"
  },
  "post_code": "SE12LH",
  "selected_plan": {
    "annual_cost_pence": 50147,
    "annual_saving_pence": 12350,
    "comparison_id": "f805b41c-6c66-43fb-9e43-938fd5ee7e35",
    "comparison_item_id": "9b561f27-6237-4017-89dc-e44c22f7be05",
    "fuel": "dual_fuel",
    "payment_method": "monthly_direct_debit",
    "plan_key": "green-electricity--gas-1454419621",
    "plan_name": "Vari-Fair",
    "supplier_key": "bulb",
    "supplier_name": "Bulb"
  }
}

Example response:

{
  "plan_info_url": "https://www.uswitch.com/gas-electricity/selected-plan-info?ref=test-partner-ref~custom~partner"
}

  

GET /energy/best-available

Return the best available plans, using our best guess as to supplier, fuel, usage, current plan.

The parameters post_code and either building_name or building_number, or sub_building_name are needed to uniquely identify the address. Flat numbers should be given in sub_building_name. Other parameters are optional but will improve accuracy of the quotes if provided.

The returned plans are in ordered of ascending cost (i.e., the cheapest plans first).

The response also provides guidance as to what assumptions were made.

The system attempts to lookup usage for each fuel from the following sources

- As provided by the caller
- From industry databases (if consent is given).
- From UK government supplier post code averages.
- From the Ofgem Medium usage amounts.

Notes on some fields:

fulfillable_only - If true select plans fulfillable through uSwitch, if false provide whole of market. Default true. If no tariffs are available then the error key in response map will indicate that.

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/best-available?building_number=30&industry_db_consent=true&post_code=e9%207nq&electricity_usage_kwh=3444'

Example response:

{
  "errors": {
    "comparison": "No tariffs available for these parameters"
  },
  "address": {
    "organisation": "",
    "town": "London",
    "postcode": "E97NQ",
    "thoroughfare": "Fremont Street",
    "building_number": "30",
    "region": 12,
    "building_name": "",
    "po_box": "",
    "economy_7": false,
    "sub_building_name": ""
  },
  "comparison": null,
  "payment_method": "monthly_direct_debit",
  "plan_key": "green-electricity--gas-1454419621",
  "variant": "standard",
  "assumptions": {
    "payment_method": {
      "value": "monthly_direct_debit",
      "reason": "No payment method given, Monthly direct debit is the most common"
    },
    "plan_key": {
      "value": "green-electricity--gas-1454419621",
      "reason": "Key of standard variable tariff for this supplier"
    },
    "variant": {
      "value": "standard",
      "reason": "Looked up from meter info at address"
    },
    "supplier_key": {
      "value": "bulb",
      "reason": "Looked up from industry sources"
    },
    "fuel": {
      "value": "dual_fuel",
      "reason": "Address lookup found both electricity and gas meters"
    },
    "electricity_usage_kwh": {
      "value": 3444,
      "reason": "Provided by caller."
    },
    "supplier_name": {
      "value": "Bulb Energy Ltd",
      "reason": "Looked up from industry sources"
    },
    "gas_usage_kwh": {
      "value": 18513,
      "reason": "Looked up from industry sources"
    },
    "plan_name": {
      "value": "Vari-Fair",
      "reason": "Name of standard variable tariff for this supplier"
    }
  },
  "supplier_key": "bulb",
  "fuel": "dual_fuel",
  "supplier_name": "Bulb Energy Ltd",
  "consumption": {
    "gas_usage_kwh": 18513,
    "electricity_usage_kwh": 3444
  },
  "plan_name": "Vari-Fair"
}

Example request:

curl --request GET \
     --header 'authorization: Bearer eyJ0eXAiO...Redacted...' \
     --url 'https://staging-api.partners.uswitch.com/energy/best-available?building_number=30&industry_db_consent=true&post_code=e9%207nq&electricity_usage_kwh=3444&limit=1&fulfillable_only=false'

Example response:

{
  "errors": null,
  "address": {
    "organisation": "",
    "town": "London",
    "postcode": "E97NQ",
    "thoroughfare": "Fremont Street",
    "building_number": "30",
    "region": 12,
    "building_name": "",
    "po_box": "",
    "economy_7": false,
    "sub_building_name": ""
  },
  "comparison": {
    "id": "af1b07b4-56b5-4f09-8479-5fff9c5fb7f8",
    "valuations": {
      "plan": {
        "features": [
          {
            "title": "Bronze Standard - Green Tariff",
            "description": "These tariffs meet the minimum requirements needed to be classed as a green tariff. \r\n\r\nRenewable generation certificates help prove renewable electricity has been generated. This tariff has enough certificates to prove that compared to the electricity you use, an equivalent amount will be generated from renewable sources.\r\n\r\nFor more information, visit our Green Accreditation page."
          },
          {
            "title": "Your first Direct Debit payment will be taken in advance, starting on or shortly after your supply start date",
            "description": ""
          },
          {
            "title": "Switch to Bulb today and if your current supplier charges you an early exit fee for leaving, Bulb will pay it up to £60 per fuel",
            "description": "* You'll receive credit to your Bulb account to cover cancellation charges/early exit fees incurred by switching away from your current supplier"
          }
        ],
        "key": "green-electricity--gas-1454419621",
        "name": "Vari-Fair",
        "standard_variable": true,
        "supplier_key": "bulb",
        "supplier_name": "Bulb",
        "fulfillable": false,
        "exit_fees": null,
        "feature_labels": [
          "green",
          "no-exit-fee"
        ],
        "product_end_date": null,
        "rate_guarantee": {
          "end_date": null,
          "duration": 0,
          "description": "The rate you’re paying per kWh may change if Bulb changes their prices."
        }
      },
      "personal_projection": {
        "total_pence": 167043,
        "gas_total_pence": 87033,
        "electricity_total_pence": 80010,
        "current": {
          "gas": {
            "breakdown": [
              {
                "type": "consumption",
                "value_pence": 73811.33,
                "rate_pence_per_kWh": 3.99,
                "usage_kWh": 18513
              },
              {
                "type": "standing-charge",
                "value_pence": 9077.18,
                "charge_pence_per_day": 24.87
              },
              {
                "type": "tax",
                "value_pence": 4144.43
              }
            ],
            "total_pence": 87033
          },
          "electricity": {
            "breakdown": [
              {
                "type": "consumption",
                "value_pence": 68101.66,
                "rate_pence_per_kWh": 19.77,
                "usage_kWh": 3444
              },
              {
                "type": "standing-charge",
                "value_pence": 8098.26,
                "charge_pence_per_day": 22.19
              },
              {
                "type": "tax",
                "value_pence": 3810
              }
            ],
            "total_pence": 80010
          },
          "total_pence": 167043
        }
      }
    },
    "comparisons": [
      {
        "item_id": "f76f7e94-5786-4da2-880a-6a1af64c01d6",
        "plan": {
          "features": [
            {
              "title": "Online account management - no need for paper bills"
            }
          ],
          "key": "double-gold",
          "name": "Double Gold",
          "standard_variable": false,
          "supplier_key": "telecom-plus",
          "supplier_name": "Utility Warehouse",
          "fulfillable": false,
          "exit_fees": null,
          "feature_labels": [
            "no-exit-fee"
          ],
          "product_end_date": null,
          "rate_guarantee": {
            "end_date": null,
            "duration": null,
            "description": "The rate you’re paying per kWh may change if Utility Warehouse changes their prices."
          }
        },
        "personal_projection": {
          "total_pence": 160655,
          "gas_total_pence": 84047,
          "electricity_total_pence": 76608,
          "current": {
            "gas": {
              "breakdown": [
                {
                  "type": "consumption",
                  "value_pence": 73811.33,
                  "rate_pence_per_kWh": 3.99,
                  "usage_kWh": 18513
                },
                {
                  "type": "standing-charge",
                  "value_pence": 6233.84,
                  "charge_pence_per_day": 17.08
                },
                {
                  "type": "tax",
                  "value_pence": 4002.26
                }
              ],
              "total_pence": 84047
            },
            "electricity": {
              "breakdown": [
                {
                  "type": "consumption",
                  "value_pence": 68132.65,
                  "rate_pence_per_kWh": 19.78,
                  "usage_kWh": 3444
                },
                {
                  "type": "standing-charge",
                  "value_pence": 4827.49,
                  "charge_pence_per_day": 13.23
                },
                {
                  "type": "tax",
                  "value_pence": 3648.01
                }
              ],
              "total_pence": 76608
            },
            "total_pence": 160655
          }
        },
        "saving_pence": 6388
      }
    ]
  },
  "payment_method": "monthly_direct_debit",
  "plan_key": "green-electricity--gas-1454419621",
  "variant": "standard",
  "assumptions": {
    "payment_method": {
      "value": "monthly_direct_debit",
      "reason": "No payment method given, Monthly direct debit is the most common"
    },
    "plan_key": {
      "value": "green-electricity--gas-1454419621",
      "reason": "Key of standard variable tariff for this supplier"
    },
    "variant": {
      "value": "standard",
      "reason": "Looked up from meter info at address"
    },
    "supplier_key": {
      "value": "bulb",
      "reason": "Looked up from industry sources"
    },
    "fuel": {
      "value": "dual_fuel",
      "reason": "Address lookup found both electricity and gas meters"
    },
    "electricity_usage_kwh": {
      "value": 3444,
      "reason": "Provided by caller."
    },
    "supplier_name": {
      "value": "Bulb Energy Ltd",
      "reason": "Looked up from industry sources"
    },
    "gas_usage_kwh": {
      "value": 18513,
      "reason": "Looked up from industry sources"
    },
    "plan_name": {
      "value": "Vari-Fair",
      "reason": "Name of standard variable tariff for this supplier"
    }
  },
  "supplier_key": "bulb",
  "fuel": "dual_fuel",
  "supplier_name": "Bulb Energy Ltd",
  "consumption": {
    "gas_usage_kwh": 18513,
    "electricity_usage_kwh": 3444
  },
  "plan_name": "Vari-Fair"
}

Endpoint reference

The full reference to the partners API, detailing all the parameters with examples may be found at

Authorisation is needed to see the full API reference, you should use a browser extension that allows one to set a request header Authorization: Bearer ...your token... when viewing the above pages.

Note that future developments may lead to additional being added to the JSON responses, clients of the API should accept key/value pairs that are not currently specified in the documentation and not regard these as an error.