See below for our external-facing Energylinx Quote API endpoints.
\nFor all URLs referenced in this documentation, please substitute {{host}} with the relevant hostname below, for testing in the sandbox environment.
\n{{ host }} = https://api.sandbox.energylinx.com
This API provides all the features necessary to create domestic energy quotes. The customer can choose their existing Supplier(s) and Tariff(s) from those endpoints. These and usage information are then input into the Quote endpoint to generate a comparison between their existing cost of gas and electricity vs. the cost of most other tariffs currently available on the market.
\nWe have over 20 years' experience in the UK Domestic Energy industry.
\nOur infrastructure is deployed as Serverless Lambdas in Amazon Web Services. They auto-scale with demand, with no manual provisioning necessary during demand spikes.
\nWe can derive kWh usage if the customer chooses their current tariff and enters their pounds usage.
\nOur annual cost projections can include a fall-back onto the supplier's Standard Variable tariff if their fixed tariff ends within the next year.
\nWe can take consumption figures as pounds, kWh's, OFGEM TDCV averages, or combination of house type + bedrooms + people.
\nWe can return a list of all tariffs on the market, or just ones we have a switchable relationship with.
\nAll tariffs returned will include their full unit rate information.
\nWe can send the customer a \"Best Prices\" email of top search results at time of quote.
\nWe can provide a \"Quick Quote\" from just the UPRN of a customer's address, looking up as much data as possible in EES/GES and using common default values for the rest.
\nWe can generate a list of search results (with no savings figures) even if no customer existing tariff information is provided.
\nWe can provide energy quotes for today's date or dates in the recent past.
\nThe API is available without any needed authentication.
\nHowever, the Quote Endpoint requires a special header, x-api-key, which should contain a hash value tied to the Affiliate ID we have provided you.
Currently we have no defined rate limit for number of requests.
\nBy providing an address (postcode + uprn + udprn), the Energy Switch Backend is able to look up a customer's electricity and gas meter information, fill in some default data, and provide a quote against the lowest-priced switchable tariff available through the GoCompare Energy PCW white label web site.
\nSend a POST request payload as shown in example below.
\nThe only mandatory fields are: requester name, address fields, email address, and (unless we're not sending a QuickQuote email because sendEmail is false), unsubscribeUrl.
Description of POST body parameters:
\n*REQUIRED fields
\ndata:
\ntype*: always \"QuickQuoteRequest\"
\nattributes:
\nrequester:
\nname* (string): freeform identifier in slug-name format (lower case hyphenated) indicating what service is making this Quick Quote request. Examples: car-insurance, home-insurance
customerId (int): Customer ID pertaining to the customer
\nquoteRequestId (int): Quote Request ID related to the customer at the time
\naddress:
\npostcode* (string): postcode for the customer's energy supply address
\nuprn* (string): UPRN for the customer's energy supply address (required for looking up meter data)
\nudprn* (string): UDPRN for the customer's energy supply address (required for looking up the address fields)
\ncontactDetails:
\nsendEmail (boolean): true (or blank) to send a Quick Quote email to the customer
\nemail* (string): customer's email address
\ntitle (string)
\nfirstName (string)
\nlastName (string)
\ndateOfBirth (\"yyyy-mm-dd\")
\nphone (LIST of objects)
\ntype (string): mobile or landline
number (string): e.g. \"01983527682\"
unsubscribeUrl (string): URL to add to the email sent to the customer to allow them to unsubscribe
\ntrackingTags (LIST of fields): - NOTE: these are ignored
\n*REQUIRED fields
\nSee \"Quote Endpoint\" below for details on every response field.
\nOn success, returns HTTP code 201.
\nUsing the customer's address information, we look up the customer's existing energy supplier(s), usage (if usage not found in industry data lookup, we assume medium usage), meter information (Standard/E7, smart meter status, prepayment status). We assume the customer is on their supplier's standard variable tariff, paying by monthly fixed direct debit, and on paperless billing.
\nWith these assumptions, we calculate the customer's estimated existing annual spend, and we provide details on the unit rates and annual spend of the top switchable tariff available to GoCompare customers.
\nEmailed Quick Quote: If the request payload contains sendEmail: true or is missing the sendEmail parameter, an email is sent to the customer with details of their Quick Quote. The unsubscribeUrl is populated within the body of the email.
Direct Quick Quote: If the request payload contains sendEmail: false, then no email is sent to the customer. The response will contain an attributes.links.quoteUrl parameter. This URL will take you to the GoCompare Energy PCW web site with the customer's Quick Quote data already prefilled.
By providing supplier, tariff, and usage information to the Quote endpoint, you can generate a comparison between the customer's existing cost of gas and electricity vs. the cost of other tariffs currently available on the market.
\nSend a POST request payload as shown in example below.
\nDescription of POST body parameters:
\n*REQUIRED fields
\ndata:
\ntype: always \"QuoteRequest\"
\nattributes:
\ncriteria:
\nfuelType* (enum): what kind of tariffs do you want in your quote search results? choices: elec, gas, or dual
postcode* (string): supply the customer's postcode to ensure their search results have any supplier-specific postcode-related filtering rules applied
\ndistributorId* (numerical 10-23): supply the customer's distributor ID
\nseparateSuppliers (boolean): for a dual quote, indicate whether the customer has one dual tariff or two separate gas and electricity ones
\nincludeReviewTariffs (boolean): choose whether to show tariffs available only for review (not available for signup)
\ndesiredPayTypes* (list of enum's): list the customers' desired payment types (choose one or many from the list below)
\nsearchStartDate (optional YYYY-MM-DD): perform the quote using pricing data from a date in the past
\nuseDefaultExistingSuppliers (boolean): perform the quote using a default supplier for the distribution area and the supplier's Standard tariff?
\nfilterSupplierName (string): perform the quote only against a particular supplierName
\nincludeTestTariffs (boolean): include non-live test tariffs in the search results?
\nshowHistoricTariffs (boolean): include tariffs based on regulatory start/end dates rather than onsale start/end dates?
\nrmrNonCompliantCalculation (boolean): if true, include a (separate) savings quote (in the nonRmrSaving fields) based on the tariff lasting for the full year of the quote period, rather than falling back to Standard tariffs if the tariff ends before the full year
\nhasExistingSupply (boolean): if false, perform the quote without providing any existingTariffs fields in the quote request (except for existingTariffs.elec.pricePlanId). Rates for the customer's existing energy supply will then not be looked up, and savings figures will not be calculated for each search result.
usage:
\nelec: you must provide ONE of either spend, kwh, or usage estimation
\nspend (decimal): how much does the customer currently spend?
\nspendInterval (enum): does the spend apply to month, quarter, or year?
kwh (decimal): how much does the customer currently use in kWh?
\nkwhInterval (enum): does the kwh amount apply to month, quarter, or year?
nightUsagePercentage (decimal 0-100): required if on an E7 tariff. What is customer's kWh usage is at night?
\nunknownUsageType (enum): use-ofgem-averages, use-profiling, or blank
ofgemAverage (enum): if unknownUsageType is use-ofgem-averages, then choose from OFGEM standard values of: low, medium, high
people (integer 1-5): if unknownUsageType is use-profiling, then enter the number of people in the home (up to 5)
bedrooms (integer 1-5): if unknownUsageType is use-profiling, then enter the number of bedrooms in the home (up to 5)
typeOfHome (enum): if unknownUsageType is use-profiling, then choose the type of home: bungalow, detached, flat-or-maisonette, semi-detached, terraced
gas: you must provide ONE of either spend, kwh, or usage estimation
\nspend (decimal): how much does the customer currently spend?
\nspendInterval (enum): does the spend apply to month, quarter, or year?
kwh (decimal): how much does the customer currently use in kWh?
\nkwhInterval (enum): does the kwh amount apply to month, quarter, or year?
nightUsagePercentage (decimal 0-100): if on an E7 tariff, what percentage of the customer's kWh usage is at night?
\nunknownUsageType (enum): use-ofgem-averages, use-profiling, or blank
ofgemAverage (enum): if unknownUsageType is use-ofgem-averages, then choose from OFGEM standard values of: low, medium, high
people (integer 1-5): if unknownUsageType is use-profiling, then enter the number of people in the home (up to 5)
bedrooms (integer 1-5): if unknownUsageType is use-profiling, then enter the number of bedrooms in the home (up to 5)
typeOfHome (enum): if unknownUsageType is use-profiling, then choose the type of home: bungalow, detached, flat-or-maisonette, semi-detached, terraced
existingTariffs:
\nelec:
\nsupplierName* (string): choose the customer's existing supplierName from the suppliers endpoint (or provide a supplierCode instead)
\nsupplierCode (string): if preferred, you can provide a supplierCode rather than a supplierName
\ntariffName* (string): choose the customer's existing tariffName from the tariffs endpoint
\ntariffEndDate (optional, YYYY-MM-DD): if the tariff may end within the next year, and doesn't have an absolute end date, the customer can provide their tariff end date
\npaymentTypes* (list of enum's): choose the customer's existing payment type(s); see list below
\nsmartMeter (boolean): is the customer currently on a smart meter?
\npaperlessBill (boolean): is the customer using paperless billing?
\npricePlanId* (enum): is the customer on a std or e7 price plan?
gas:
\nsupplierName* (string): choose the customer's existing supplierName from the suppliers endpoint (or provide a supplierCode instead)
\ntariffName* (string): choose the customer's existing tariffName from the tariffs endpoint
\nproductCode (string): supplier's internal product code for this tariff
\ntariffEndDate (optional, YYYY-MM-DD): if the tariff may end within the next year, and doesn't have an absolute end date, the customer can provide their tariff end date
\npaymentTypes* (list of enum's): choose the customer's existing payment type(s); see list below
\nsmartMeter (boolean): is the customer currently on a smart meter?
\npaperlessBill (boolean): is the customer using paperless billing?
\naddress:
\ncontactDetails:
\n*REQUIRED fields
\nOn success, returns HTTP code 201.
\nPayload contains details on the customer's existing spend, and details on the unit rates and spends of a list of tariff search results.
\ndata:
\ntype: always \"Quote\"
\nid (integer): unique quote ID
\nattributes:
\nkey (string): unique quote key (hash) to use for signing up to this quote
\ncriteria:
\nfuelType (enum): dual, elec, gas from request
distributorId (integer 10-23): distributor ID from request
\ngspId (string): distributor ID converted to GSP ID, e.g. if distributor ID is 17, this returns _P
includeTestTariffs (boolean): from request
\nshowHistoricTariffs (boolean): passed through from request
\nsearchStartDate (YYYY-MM-DD): passed through from request
\nuseDefaultExistingSuppliers (boolean): passed through from request
\nrmrNonCompliantCalculation (boolean): passed through from request
\nusage:
\nspendTotal (decimal): total annual spend on existing tariff over the quote period (the next year)
\nelec:
\nspend (decimal): annual elec spend on existing tariff over the quote period (the next year)
\nkwh (decimal): annual elec kWh usage
\ngas:
\nspend (decimal): annual gas spend on existing tariff over the quote period (the next year)
\nkwh (decimal): annual gas kWh usage
\nexistingTariffs:
\nelec:
\nsupplierName (string): existing elec supplierName
\nsupplierCode (string): existing elec supplierCode
\nsupplierImageUrl (string): supplier logo image URL
\ntariffName (string): existing elec tariffName
\nproductCode (string): supplier's internal code for this tariff
\ntariffTypes (list of strings): variable, fixed, etc.
paymentType (enum): see list of possible Payment Types below
\npricePlanId (enum): std or e7
unitRate1 (decimal): primary unit rate, if STD (pence)
\nunitRate2 (decimal): secondary unit rate, if STD (pence)
\nunitRate1DayE7 (decimal): primary day rate, if E7 (pence)
\nunitRate2DayE7 (decimal): secondary day rate, if E7 (pence)
\nunitRateNightE7 (decimal): night rate, if E7 (pence)
\nunitLimit1Quarter (decimal): primary rate limit (kWh)
\nstandingCharge (decimal): standing charge (pence)
\nexitFee (decimal): exit fee in pounds
\nexitFeeEndDate (date): exit fee end date
\nfixedTermEndMonths (decimal): fixed term end, if in months
\nfixedTermEndDate (date): fixed term end, if exact date
\nregulatoryStartDate (date): regulatory start date
\nregulatoryEndDate (date): regulatory end date
\ntariffEndDate (date): optional customer-supplied tariff end date
\nmonthlyFee (decimal): monthly fee (pounds)
\nmonthlyFeeDescription (decimal): monthly fee description
\ndiscounts (LIST of discount objects):
\nlabel (string): short description
\nvalue (decimal): discount value in pounds
\ngas:
\nrolloverCalculation: this structure only appears if customer rolled over onto Standard tariff(s) during the ensuing one-year quote period
\nfixedTariff: details of the initial fixed tariff (tariff before the rollover)
\nelec:
\nfraction (decimal): decimal fraction of kWh usage for this tariff
\nkwh (decimal): kWh usage for this tariff
\ndays (decimal): days on this tariff
\ngas:
\nfraction (decimal): decimal fraction of kWh usage for this tariff
\nkwh (decimal): kWh usage for this tariff
\ndays (decimal): number of days on this tariff
\ndeemedTariffs: details of one or more rollover/deemed standard tariffs
\nelec (LIST of objects):
\nsupplierName (string): supplierName
\nsupplierCode (string): supplierCode
\ntariffName (string): tariffName
\nstandingCharge (decimal): standing charge (pence)
\nunitRate1 (decimal): primary unit rate (pence)
\nunitRate2 (decimal): secondary unit rate (pence)
\nunitRate1DayE7 (decimal): primary day rate, if E7 (pence)
\nunitRate2DayE7 (decimal): secondary day rate, if E7 (pence)
\nunitRateNightE7 (decimal): night rate, if E7 (pence)
\nunitRate1LimitQuarter (decimal): primary rate limit (kWh)
\ndiscountsTotal (decimal): discounts in pounds
\nkwhDay (decimal): kWh usage for this tariff (day)
\nkwhNight (decimal): kWh usage for this tariff (night)
\nfractionDay (decimal): decimal fraction of kWh usage for this tariff (day)
\nfractionNight (decimal): decimal fraction of kWh usage for this tariff (night)
\ndays (decimal): number of days on this tariff
\nspend (decimal): spend on this tariff
\ngas (LIST of objects):
\nlinks:
\nunsubscribeUrl (string): if generating a Quick Quote, and sending a Quick Quote email, used internally for populating the unsubscribe link
\nquoteUrl (string): if generating a Quick Quote, and not sending a Quick Quote email, this URL links to the GoCompare Energy PCW web site, with all fields prefilled data from the Quick Quote data
\nsearchResults (LIST of tariff search result objects):
\nid (integer): price ID (unique for every tariff's price)
\nusage:
\nspendTotal (decimal): annual spend (for both fuels)
\nsavingsTotal (decimal): annual savings (for both fuels) vs. customer's existing spend
\nnonRmrSavingTotal (decimal): only shown if rmrNonCompliantCalculation is true
\nelec:
\nspend (decimal): annual spend (for elec only)
\nsavings (decimal): annual savings (for elec only) vs. customer's existing spend
\nspendMonthlyDDEqualPayments (decimal): monthly Direct Debit amount (for elec only) if spread evenly through the year
\nspendMonthlyDDWithUplift (decimal): monthly Direct Debit amount (for elec only) for the first month if tariff has a winter uplift or summer discount
\nnonRmrSaving (decimal): only shown if rmrNonCompliantCalculation is true
\ngas:
\nspend (decimal): annual spend (for gas only)
\nsavings (decimal): annual savings (for gas only) vs. customer's existing spend
\nspendMonthlyDDEqualPayments (decimal): monthly Direct Debit amount (for gas only) if spread evenly through the year
\nspendMonthlyDDWithUplift (decimal): monthly Direct Debit amount (for gas only) for the first month if tariff has a winter uplift or summer discount
\nnonRmrSaving (decimal): only shown if rmrNonCompliantCalculation is true
\ntariff:
\nsupplierId (integer): supplierId
\nsupplierCode (string, 10 characters): supplierCode
\nsupplierName (string): supplierName
\nsupplierImageUrl (string): supplier logo image URL
\ntariffName (string): tariffName
\ntariffCode (string): ELX tariff code
\ntariffTypes (list of strings): variable, fixed, etc.
tariffTermsPdf (string): URL to T&C PDF for this tariff
\nstraplineText (string): tariff strapline text
\nsynopsisText (string): long-form tariff synopsis text
\nfeatureText (LIST of strings): each string contains a feature of the tariff
\npaymentType (enum): payment type (see list of Payment Types below)
\nspendMonthlyDDEqualPayments (decimal): monthly Direct Debit amount if spread evenly through the year
\nspendMonthlyDDWithUplift (decimal): monthly Direct Debit amount for the first month if tariff has a winter uplift or summer discount
\nfixedTermEndMonths (decimal): fixed term end, if in months
\nfixedTermEndDate (date): fixed term end, if exact date
\nregulatoryStartDate (date): regulatory start date
\nregulatoryEndDate (date): regulatory end date
\nonsaleStartDate (date): on-sale start date
\nonsaleEndDate (date): on-sale end date
\npaperBills (boolean): is the tariff available via paper billing?
\npaperlessBills (boolean): is the tariff available via paperless billing?
\nsupplierImageUrl (string): URL to image for this supplier
\nexitFeeCombined (date): exit fee (irrespective of which fuel the customer leaves)
\nexitFeeEndDate (date): exit fee end date
\nmonthlyFee (decimal): monthly fee (pounds)
\nmonthlyFeeDescription (decimal): monthly fee description
\nphoneMobileMandatory (boolean): is a mobile phone mandatory for this tariff?
\nsignupLinkConfig (JSON): config for a click-out link from the search results to an external supplier's site rather than our signup process
\nuiConfig:
\nswitchable (boolean): is this tariff available for signup online on this white label? (white label brand identified by partnerUUID)
\nelec:
\nproductCode (string): supplier's internal code for this tariff
\nunitRate1 (decimal): primary unit rate, if STD (pence)
\nunitRate2 (decimal): secondary unit rate, if STD (pence)
\nunitRate1DayE7 (decimal): primary day rate, if E7 (pence)
\nunitRate2DayE7 (decimal): secondary day rate, if E7 (pence)
\nunitRateNightE7 (decimal): night rate, if E7 (pence)
\nunitLimit1Quarter (decimal): primary rate limit (kWh)
\nstandingCharge (decimal): standing charge (pence)
\nexitFee (decimal): exit fee in pounds
\nadditionalProductsText (string): additional products text
\npricePlanId (enum): std or e7
discounts (LIST of discount objects):
\nlabel (string): short description
\nvalue (decimal): discount value in pounds
\nisRetention (boolean): is this a retention fuel (the customer is already supplied by this supplier for this fuel)?
\ngas:
\nrolloverCalculation: this structure only appears if this tariff ends and rolls over onto a Standard tariff(s) during the ensuing one-year quote period. The structure is identical to \"rolloverCalculation\" under \"attributes\" above.
\nReturn a list of all suppliers, with minimal details for each. The supplier list can be narrowed down by some filter parameters.
\nSend a GET request payload as shown in example below.
\nAvailable GET parameters:
\nelec, gas, dualOn success, returns HTTP code 200.
\nPayload contains a list of minimal supplier objects. Each minimal supplier object consists of:
\nGiven a supplierId, return full details on just one supplier.
\nSend a GET request payload as shown in example below.
\nParameters within URL:
\nAvailable GET parameters:
\nOn success, returns HTTP code 200.
\nPayload contains a list of supplier detail objects. Each supplier detail object consists of:
\nReturn details on a list of tariffs for a supplier. By default, tariffs are shown that are within their regulatory start and end dates (tariffs which customers can still be on, even if no longer for sale.) The tariff list can be narrowed down by some filter parameters.
\nSend a GET request payload as shown in example below.
\nParameters within URL:
\nAvailable GET parameters:
\nelec, gas, dualregulatory if not supplied. If set to on-sale, the tariff list will be filtered to only show tariffs currently available for salestd, e7On success, returns HTTP code 200 and a list of tariffs.
\nPayload contains a list of tariff objects. Each tariff object consists of:
\nelec, gas, dualstd, e7Returns the Distributor Id (DNO) from postcodes.
\nSend a GET request payload as shown in example below.
\nParameters within URL:
\nOn success, returns HTTP code 200 and a list of tariffs.
\nPayload contains a list of tariff objects. Each tariff object consists of:
\n {\n \"type\": \"DistributorData\",\n \"id\": 20,\n \"attributes\": {\n \"distibutorId\": 20,\n \"gspGroupId\": \"_H\",\n \"distributorData\": {\n \"id\": 20,\n \"name\": \"Southern England\",\n \"operator\": \"Scottish & Southern Electricity Networks\",\n \"phoneNumber\": \"0800 048 3516\",\n \"marketParticipantId\": \"SOUT\",\n \"gspGroupId\": \"_H\",\n \"idno\": false,\n \"licensee\": \"\",\n \"timeUpdated\": \"2020-04-07 16:57:00\"\n }\n }\n