{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/www.ismybillfair.com" } ], "info": { "name": "ismybillfair Partner API Documentation", "_postman_id": "085eb758-8f49-4b1d-9558-91b0f233f8b4", "description": "Partner API for retrieving and converting eligible ismybillfair offers. Version 1 supports energy.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Quotes", "description": "", "item": [ { "name": "Create an energy quote from an address.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/partner\/quotes\/address", "query": [], "raw": "{{baseUrl}}\/api\/v1\/partner\/quotes\/address" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"service\":\"energy\",\"postcode\":\"SW1A 1AA\",\"address\":\"10 Downing Street\",\"customer_reference\":\"customer_12345\",\"idempotency_key\":\"07c4b96e-c8e8-4b91-9fd2-24e2d1591268\"}" }, "description": "Starts a partner quote journey using an address and postcode. If ismybillfair\nalready knows the current tariff and payment method, eligible offers are returned.\nOtherwise, the response contains the tariff and\/or payment-method choices required\nto continue the quote. Each available offer includes a time-limited hosted checkout\nURL that can be opened in a browser or webview for the customer to complete their switch." }, "response": [ { "header": [], "code": 200, "body": "{\"quote_id\":\"4db7e203-7a94-40c6-a7e2-72d8422d5995\",\"service\":\"energy\",\"status\":\"offers_available\",\"offers\":[{\"reference\":\"8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2\",\"supplier\":\"Example Energy\",\"fuel\":\"dual_fuel\",\"title\":\"Example Fixed 12M\",\"annual_price\":1200,\"monthly_price\":100,\"annual_saving\":180,\"monthly_saving\":15,\"contract_length_months\":12,\"expires_at\":\"2026-08-21\",\"actions\":{\"hosted_checkout_url\":\"https:\/\/your-domain.example\/partner\/checkout\/4db7e203-7a94-40c6-a7e2-72d8422d5995\/8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2?expires=1780000000&signature=example-signature\"}}]}", "name": "Offers available" }, { "header": [], "code": 200, "body": "{\"quote_id\":\"4db7e203-7a94-40c6-a7e2-72d8422d5995\",\"service\":\"energy\",\"status\":\"details_required\",\"requirements\":[{\"field\":\"dual_fuel.current_tariff\",\"message\":\"Select the customer\u2019s current tariff.\",\"options\":[{\"reference\":\"b30c32a8-4558-4e8c-a914-c8ed70a6a5a3\",\"name\":\"Example Standard Variable\",\"expires_at\":\"2026-12-31\"}]}]}", "name": "Details required" }, { "header": [], "code": 200, "body": "{\"quote_id\":\"4db7e203-7a94-40c6-a7e2-72d8422d5995\",\"service\":\"energy\",\"status\":\"unavailable\",\"reason\":{\"code\":\"energy_supply_not_found\",\"message\":\"We could not identify a supported energy supply for this address.\"}}", "name": "No quote available" }, { "header": [], "code": 401, "body": "{\"success\":false,\"error\":{\"code\":\"invalid_partner_api_key\",\"message\":\"A valid partner API key is required.\"}}", "name": "" }, { "header": [], "code": 403, "body": "{\"success\":false,\"error\":{\"code\":\"service_not_authorised\",\"message\":\"This partner is not authorised to access the requested service.\"}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"The postcode field format is invalid.\",\"errors\":{\"postcode\":[\"The postcode field format is invalid.\"]}}", "name": "" }, { "header": [], "code": 500, "body": "{\"success\":false,\"error\":{\"code\":\"quote_calculation_failed\",\"message\":\"We could not calculate a quote at this time.\"}}", "name": "" } ] }, { "name": "Complete a quote with tariff and payment selections.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/partner\/quotes\/:quoteId\/details", "query": [], "raw": "{{baseUrl}}\/api\/v1\/partner\/quotes\/:quoteId\/details", "variable": [ { "id": "quoteId", "key": "quoteId", "value": "4db7e203-7a94-40c6-a7e2-72d8422d5995", "description": "The public quote ID returned by the address endpoint." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"selections\":[\"architecto\"],\"usage\":{\"electricity_annual_kwh\":2900,\"gas_annual_kwh\":12000},\"idempotency_key\":\"5a2a6ab5-c236-42e7-a1cc-2dac4b80f78b\"}" }, "description": "Submit the opaque option references returned by an earlier\n`details_required` response. Do not submit internal tariff or payment IDs. Each\navailable offer includes a time-limited hosted checkout URL for the customer." }, "response": [ { "header": [], "code": 200, "body": "{\"quote_id\":\"4db7e203-7a94-40c6-a7e2-72d8422d5995\",\"service\":\"energy\",\"status\":\"offers_available\",\"offers\":[{\"reference\":\"8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2\",\"supplier\":\"Example Energy\",\"fuel\":\"dual_fuel\",\"title\":\"Example Fixed 12M\",\"annual_price\":1200,\"monthly_price\":100,\"annual_saving\":180,\"monthly_saving\":15,\"contract_length_months\":12,\"expires_at\":\"2026-08-21\",\"actions\":{\"hosted_checkout_url\":\"https:\/\/your-domain.example\/partner\/checkout\/4db7e203-7a94-40c6-a7e2-72d8422d5995\/8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2?expires=1780000000&signature=example-signature\"}}]}", "name": "Offers available" }, { "header": [], "code": 404, "body": "{\"success\":false,\"error\":{\"code\":\"quote_not_found\",\"message\":\"The requested quote was not found.\"}}", "name": "" }, { "header": [], "code": 409, "body": "{\"success\":false,\"error\":{\"code\":\"quote_not_waiting_for_details\",\"message\":\"This quote is not waiting for additional details.\"}}", "name": "" }, { "header": [], "code": 410, "body": "{\"success\":false,\"error\":{\"code\":\"quote_expired\",\"message\":\"This quote has expired. Create a new quote to continue.\"}}", "name": "" }, { "header": [], "code": 422, "body": "{\"success\":false,\"error\":{\"code\":\"invalid_option_reference\",\"message\":\"One or more submitted option references are invalid.\"}}", "name": "" }, { "header": [], "code": 500, "body": "{\"success\":false,\"error\":{\"code\":\"quote_calculation_failed\",\"message\":\"We could not calculate a quote at this time.\"}}", "name": "" } ] } ] }, { "name": "Conversions", "description": "", "item": [ { "name": "Submit an offer conversion directly.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/partner\/quotes\/:quoteId\/conversions", "query": [], "raw": "{{baseUrl}}\/api\/v1\/partner\/quotes\/:quoteId\/conversions", "variable": [ { "id": "quoteId", "key": "quoteId", "value": "4db7e203-7a94-40c6-a7e2-72d8422d5995", "description": "The public quote ID returned by the quote endpoint." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"offer_reference\":\"8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2\",\"idempotency_key\":\"9d6d7f75-00a4-4596-8766-0ee9354019ba\",\"customer\":{\"email\":\"jane.smith@example.com\",\"first_name\":\"Jane\",\"last_name\":\"Smith\",\"title\":\"Ms\",\"phone_number\":\"07123456789\",\"date_of_birth\":\"1985-06-15\"},\"direct_debit\":{\"bank_account_number\":\"12345678\",\"bank_sort_code\":\"11-22-33\",\"bank_payment_day\":\"15\"}}" }, "description": "Submit customer details for an offer returned by this partner quote. Only\nsend Direct Debit details when the selected offer requires them. To avoid\nsending customer or bank data to the API, use the offer's\n`actions.hosted_checkout_url` instead." }, "response": [ { "header": [], "code": 200, "body": "{\"submission_id\":\"a1e5e588-b8c9-412a-b01c-9501e92cb3ef\",\"quote_id\":\"4db7e203-7a94-40c6-a7e2-72d8422d5995\",\"offer_reference\":\"8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2\",\"status\":\"PROCESSING\"}", "name": "" }, { "header": [], "code": 404, "body": "{\"success\":false,\"error\":{\"code\":\"quote_not_found\",\"message\":\"The requested quote was not found.\"}}", "name": "" }, { "header": [], "code": 409, "body": "{\"success\":false,\"error\":{\"code\":\"quote_not_ready_for_conversion\",\"message\":\"This quote does not have an offer available for conversion.\"}}", "name": "" }, { "header": [], "code": 410, "body": "{\"success\":false,\"error\":{\"code\":\"quote_expired\",\"message\":\"This quote has expired. Create a new quote to continue.\"}}", "name": "" }, { "header": [], "code": 422, "body": "{\"success\":false,\"error\":{\"code\":\"invalid_offer_reference\",\"message\":\"The selected offer does not belong to this quote.\"}}", "name": "" }, { "header": [], "code": 500, "body": "{\"success\":false,\"error\":{\"code\":\"conversion_submission_failed\",\"message\":\"We could not submit this conversion at this time.\"}}", "name": "" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }