The purpose of the status reporting API is to allow suppliers to provide information to Uswitch as to whether the switch of a fuel succeeded in going live or not.
This information is used to
These statuses have historically been provided to Uswitch in spreadsheets.
The API provides a way to provide status to Uswitch and also for the supplier to find out the switched fuels for which Uswitch still expects to receive status.
The Uswitch operations team may be contacted for assistance with this API.
An energy switch with Uswitch may have 1 or 2 fuels (gas and/or electricity). Each switched product will eventually reach a status that indicates whether or not it went on supply as a result of Uswitch sending the switch to the supplier. The product statuses are independent, i.e. is it possible for gas to live, but electricity to be rejected.
Statuses accepted by the API:
| Status | Status type | |
|
|---|---|---|---|
| in_progress | intermediate | The switch is still in progress. This state is not final. | Notify Uswitch when you start processing the switch. |
| live | final | Product has gone on supply. | The consumer successfully onboarded. |
| cancelled | final | Did not go live due to consumer’s request. | The consumer changed their mind and cancelled. |
| rejected | final | Did not go live due to the new supplier’s request. | The consumer information is not correct to onboard. e.g. business meter type. |
| objected | final | Did not go live due to the old supplier’s request. | Previous supplier objects to the switch, e.g. due to consumer debt. |
| deleted | final | Erroneous transfer and fraudulent switches. | If the consumer did not request the switch. e.g. fraud |
A switch will typically start in the in_progress state and end in one of the final states. In the normal course of events, Uswitch would expect that a switch’s status will not change from one final status to another. This would indicate that the first advised final status was incorrect. However the supplier may advise Uswitch of a new correct final status if this situation has occurred.
Example case;
A customer typed their mpan incorrectly, and customer service managed to fix this issue.
switch status
in_progress -> rejected -> live
When the switch is rejected, we would like to receive the reason why the switch has been rejected. This information would be shared with the customers to increase customers’ satisfaction. e.g. “National database shows that the customer’s MPAN or MPRN does not match the provided address”
Each time the supplier advises Uswitch of the status we record that information as a status fact. The switch’s final status is determined from the full list of facts provided.
Switches will always be identified by the supplier “brand” and switch reference “switch_ref” provided by Uswitch when sending the switch to the supplier. This field has also been referred to as URN.
“brand” is based on your supplier name. If you are successfully authenticated you can see brand name in your scope field.
{
...
"scope":"switch-api status-reporting supplier-name-key:test-supplier brand:test-supplier"
...
}“switch_ref” is the reference you have received from switch API. A switch has a reference. A switch can be dual fuel, gas only and elec only switches.
Some suppliers have agreements that provide for additional payments where switches go live and remain live with that supplier for an agreed time period. (e.g. a year) These are loyalty payments and suppliers who have such agreements should also report loyalty status when the time period for the switches to stay live has passed.
The api provides for the possiblity of multiple loyalty payments,
each identified by a payment number. (e.g. first year payment will have
payment number 1, second year payment will have payment number 2, etc.)
The /missing-loyalty-statuses route will provide you with
the list of switches where reporting is now due and the due date.
In the staging environment loyalty is considered due immediately to facilitate testing without waiting for the due date. In production, the loyalty statuses are only due after the period contractually agreed with each supplier.
https://staging-api.energy.uswitchsuppliers.comThe staging endpoints will return and process data for test switches. This environment is supplied with a database of test switches which is refreshed at midnight each night. These test switches are automatically generated and have no relation to real consumer switches. You may get and post status to the staging environment at any time.
https://api.energy.uswitchsuppliers.comThe production endpoints will return and process data for real
switches. Do not use production for testing, however the
/status-reporting/health endpoint may be safely used at any
time as it has no side effects.
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.
See the Authentication section for details.
These are the switches for the supplier where Uswitch does not hold a final status.
Use your own brand key in your requests. The permitted brands are listed in the authentication response from step 1.
Example request:
curl --request GET \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiO...Redacted...' \
--url 'https://staging-api.energy.uswitchsuppliers.com/status-reporting/missing-statuses?brand=test-supplier'Example response:
[
{
"switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"fuel": "gas",
"switch_date": "2019-01-01",
"mpan": "1419143010000",
"mprn": "2465692006",
"postcode": "GL50 3QB",
"payment_method": "monthly direct debit"
},
{
"switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"fuel": "electricity",
"switch_date": "2019-01-01",
"mpan": "1419143010000",
"mprn": "2465692006",
"postcode": "GL50 3QB",
"payment_method": "monthly direct debit"
},
{
"switch_ref": "7d605099-b7b4-438a-8b43-5ad16f8dd515",
"fuel": "electricity",
"switch_date": "2019-01-01",
"mpan": "1012852757423",
"mprn": "3287444104",
"postcode": "W5 4LP",
"payment_method": "prepayment"
}
]If a switch is dual fuel switch and neither products have been
reported yet, then you will get two objects back under the same switch
reference, one for gas and the other for electricity. If you report the
final status for the gas, then the /missing-statuses
endpoint will return only the object for electricity switch under the
same reference.
If a switch is gas only switch, you will get only the gas product as
an object back under the switch reference. If you report the final
status for the gas, /missing-statuses endpoint won’t return
any objects under the switch reference.
Here you can submit facts about your switches. Multiple facts can be submitted by including more json maps in the vector.
Example request:
curl --request POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiO...Redacted...' \
--data '[{ "switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"fuel": "electricity",
"status": "rejected",
"reason": "This MPAN has been deenergised",
"effective_date": "2019-02-19",
"supplier_dropout_code": "DeEnergisedMPAN" }]' \
--url 'https://staging-api.energy.uswitchsuppliers.com/status-reporting/status-facts?brand=test-supplier'Example response:
{
"msg": "OK 1 status received",
"statuses": [
{
"elec_status": "rejected",
"switch_ref": "67370"
}
]
}Example request:
curl --request GET \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eX...redacted...' \
--url 'https://staging-api.energy.uswitchsuppliers.com/status-reporting/status-facts?brand=test-supplier&switch_ref=67370'Example response:
[
{
"switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"fuel": "electricity",
"status": "rejected",
"received_via": "reporting-api",
"received_date": "2019-06-07",
"switch_date": "2019-01-01"
}
]Example request:
These are the switches for the supplier where loyalty status is due
and has not yet been received. Only switches where reporting is due are
returned. The from and to dates refer to the
dates of the switch, not the end of the loyalty period.
Example Request for a test-supplier below, use your own
brand key in your requests. The permitted brands are listed in the
authentication response from step 1.
curl --request GET \
--header 'Accept: application/json'
--header 'Authorization: Bearer eyJ0eXAiO...Redacted...' \
--url 'https://staging-api.energy.uswitchsuppliers.com/status-reporting/missing-loyalty-statuses?brand=test-supplier&from=2020-03-15&to=2020-04-15'Example response:
[
{
"switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"fuel": "gas",
"switch_date": "2019-02-12",
"mpan": "13413452351352",
"mprn": "1231232521",
"postcode": "SW11AA",
"payment_method": "Monthly Direct Debit",
"acquisition_retention": "acquisition",
"payment_number": 1,
"payment_due_date": "2020-02-12"
}
]Here you can submit loyalty facts about your switches. Multiple facts can be submitted by including more json maps in the vector.
Example request:
curl --request POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiO...Redacted...' \
--data '[
{
"switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"fuel": "gas",
"payment_number": 1,
"payable": true
}, {
"switch_ref": "7d605099-b7b4-438a-8b43-5ad16f8dd515",
"fuel": "gas",
"payment_number": 2,
"payable": false
}
]'
--url 'https://staging-api.energy.uswitchsuppliers.com/status-reporting/loyalty-status-facts?brand=test-supplier'Example response:
{
"msg": "OK 2 status received",
"statuses": [
{"elec_payable": null,
"gas_payable": true,
"switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"payment_number": 1,
"payment_due_date": "2020-02-12"}
{"elec_payable": null,
"gas_payable": false,
"switch_ref": "7d605099-b7b4-438a-8b43-5ad16f8dd515",
"payment_number": 2,
"payment_due_date": "2021-02-12"}
]
}Example request:
curl --request GET \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eX...redacted...' \
--url 'https://staging-api.energy.uswitchsuppliers.com/status-reporting/loyalty-status?brand=test-supplier&switch_ref=67370'Example response:
[{"switch_date": "2019-01-12",
"switch_ref": "ca9333b6-c475-40c5-8995-a3f87cbb78ff",
"fuel": "gas",
"payable": true,
"payment_number": 1,
"payment_due_date": "2020-01-12"},
{
"switch_date": "2019-01-12",
"switch_ref": "7d605099-b7b4-438a-8b43-5ad16f8dd515",
"fuel": "gas",
"payable": false,
"payment_number": 2,
"payment_due_date": "2021-01-12"}]A few operational aspects should be considered to make the reporting process work smoothly.
Posting schedule: You post updates to individual switches as they
occur, e.g. if you put switch reference
3cdaca10-0920-4b68-8c2f-27571960a414 live, then you can
make posting a live status part of that process, but there should also
be a regular run to get references from
/status-reporting/missing-statuses and post the final statuses where
they are known. We suggest this process is run daily, but it should be
at least weekly.
If you end up doing a lot of switching, then a call to /status-reporting/missing-statuses over a large date range will take a long time to respond, so you should break down the calls into a set of shorter periods, e.g. You might loop through the date range of the last 6 months, one week at a time and post the status of any of the returned switches where you have it available.
Monitoring for switches unresolved. Some supplier’s processes end up with some switches that never seem to resolve, i.e. months have gone past and they still have not resolved into a live/rejected/objected/cancelled status. If these switches are left long enough then Uswitch will contact you and provide a list of switches and ask you to investigate and post status appropriately, but the API gives you the ability to do this yourself. You can identify what is missing through the /status-reporting/missing-statuses endpoint. For this to work you’d have to set up a process to monitor for unresolved switches over a certain age and have someone resolve then into the appopriate final state. This is naturally part of your internal operations so we can’t determine how you do this, but please can you give it some consideration as it is an operational point sometimes neglected.