openapi: 3.1.0 info: title: 'ismybillfair Partner API Documentation' description: 'Partner API for retrieving and converting eligible ismybillfair offers. Version 1 supports energy.' version: 1.0.0 servers: - url: 'https://www.ismybillfair.com' tags: - name: Quotes description: '' - name: Conversions description: '' components: securitySchemes: default: type: http scheme: bearer description: 'Partners receive an API key from ismybillfair. Send it with every request as a Bearer token in the Authorization header.' security: - default: [] paths: /api/v1/partner/quotes/address: post: summary: 'Create an energy quote from an address.' operationId: createAnEnergyQuoteFromAnAddress 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." parameters: [] responses: 200: description: '' content: application/json: schema: oneOf: - description: 'Offers available' type: object properties: quote_id: type: string examples: - 4db7e203-7a94-40c6-a7e2-72d8422d5995 service: type: string examples: - energy status: type: string examples: - offers_available offers: type: array items: type: object properties: reference: type: string examples: - 8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2 supplier: type: string examples: - 'Example Energy' fuel: type: string examples: - dual_fuel title: type: string examples: - 'Example Fixed 12M' annual_price: type: integer examples: - 1200 monthly_price: type: integer examples: - 100 annual_saving: type: integer examples: - 180 monthly_saving: type: integer examples: - 15 contract_length_months: type: integer examples: - 12 expires_at: type: string examples: - '2026-08-21' actions: type: object properties: hosted_checkout_url: type: string examples: - 'https://your-domain.example/partner/checkout/4db7e203-7a94-40c6-a7e2-72d8422d5995/8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2?expires=1780000000&signature=example-signature' examples: - - 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' examples: - 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' - description: 'Details required' type: object properties: quote_id: type: string examples: - 4db7e203-7a94-40c6-a7e2-72d8422d5995 service: type: string examples: - energy status: type: string examples: - details_required requirements: type: array items: type: object properties: field: type: string examples: - dual_fuel.current_tariff message: type: string examples: - 'Select the customer’s current tariff.' options: type: array items: type: object properties: reference: type: string examples: - b30c32a8-4558-4e8c-a914-c8ed70a6a5a3 name: type: string examples: - 'Example Standard Variable' expires_at: type: string examples: - '2026-12-31' examples: - - reference: b30c32a8-4558-4e8c-a914-c8ed70a6a5a3 name: 'Example Standard Variable' expires_at: '2026-12-31' examples: - - field: dual_fuel.current_tariff message: 'Select the customer’s current tariff.' options: - reference: b30c32a8-4558-4e8c-a914-c8ed70a6a5a3 name: 'Example Standard Variable' expires_at: '2026-12-31' examples: - quote_id: 4db7e203-7a94-40c6-a7e2-72d8422d5995 service: energy status: details_required requirements: - field: dual_fuel.current_tariff message: 'Select the customer’s current tariff.' options: - reference: b30c32a8-4558-4e8c-a914-c8ed70a6a5a3 name: 'Example Standard Variable' expires_at: '2026-12-31' - description: 'No quote available' type: object properties: quote_id: type: string examples: - 4db7e203-7a94-40c6-a7e2-72d8422d5995 service: type: string examples: - energy status: type: string examples: - unavailable reason: type: object properties: code: type: string examples: - energy_supply_not_found message: type: string examples: - 'We could not identify a supported energy supply for this address.' examples: - 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.' 401: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - invalid_partner_api_key message: type: string examples: - 'A valid partner API key is required.' examples: - success: false error: code: invalid_partner_api_key message: 'A valid partner API key is required.' 403: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - service_not_authorised message: type: string examples: - 'This partner is not authorised to access the requested service.' examples: - success: false error: code: service_not_authorised message: 'This partner is not authorised to access the requested service.' 422: description: '' content: application/json: schema: type: object properties: message: type: string examples: - 'The postcode field format is invalid.' errors: type: object properties: postcode: type: array items: type: string examples: - - 'The postcode field format is invalid.' examples: - message: 'The postcode field format is invalid.' errors: postcode: - 'The postcode field format is invalid.' 500: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - quote_calculation_failed message: type: string examples: - 'We could not calculate a quote at this time.' examples: - success: false error: code: quote_calculation_failed message: 'We could not calculate a quote at this time.' tags: - Quotes requestBody: required: true content: application/json: schema: type: object properties: service: type: string description: 'The requested service. Currently only `energy` is supported.' examples: - energy postcode: type: string description: 'A valid UK postcode.' examples: - 'SW1A 1AA' address: type: string description: 'The full selected address.' examples: - '10 Downing Street' customer_reference: type: - string - 'null' description: 'Optional partner-side customer reference.' examples: - customer_12345 idempotency_key: type: - string - 'null' description: 'Optional unique key used to safely retry the same request.' examples: - 07c4b96e-c8e8-4b91-9fd2-24e2d1591268 required: - service - postcode - address '/api/v1/partner/quotes/{quoteId}/details': post: summary: 'Complete a quote with tariff and payment selections.' operationId: completeAQuoteWithTariffAndPaymentSelections 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." parameters: [] responses: 200: description: 'Offers available' content: application/json: schema: type: object properties: quote_id: type: string examples: - 4db7e203-7a94-40c6-a7e2-72d8422d5995 service: type: string examples: - energy status: type: string examples: - offers_available offers: type: array items: type: object properties: reference: type: string examples: - 8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2 supplier: type: string examples: - 'Example Energy' fuel: type: string examples: - dual_fuel title: type: string examples: - 'Example Fixed 12M' annual_price: type: integer examples: - 1200 monthly_price: type: integer examples: - 100 annual_saving: type: integer examples: - 180 monthly_saving: type: integer examples: - 15 contract_length_months: type: integer examples: - 12 expires_at: type: string examples: - '2026-08-21' actions: type: object properties: hosted_checkout_url: type: string examples: - 'https://your-domain.example/partner/checkout/4db7e203-7a94-40c6-a7e2-72d8422d5995/8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2?expires=1780000000&signature=example-signature' examples: - - 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' examples: - 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' 404: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - quote_not_found message: type: string examples: - 'The requested quote was not found.' examples: - success: false error: code: quote_not_found message: 'The requested quote was not found.' 409: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - quote_not_waiting_for_details message: type: string examples: - 'This quote is not waiting for additional details.' examples: - success: false error: code: quote_not_waiting_for_details message: 'This quote is not waiting for additional details.' 410: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - quote_expired message: type: string examples: - 'This quote has expired. Create a new quote to continue.' examples: - success: false error: code: quote_expired message: 'This quote has expired. Create a new quote to continue.' 422: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - invalid_option_reference message: type: string examples: - 'One or more submitted option references are invalid.' examples: - success: false error: code: invalid_option_reference message: 'One or more submitted option references are invalid.' 500: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - quote_calculation_failed message: type: string examples: - 'We could not calculate a quote at this time.' examples: - success: false error: code: quote_calculation_failed message: 'We could not calculate a quote at this time.' tags: - Quotes requestBody: required: true content: application/json: schema: type: object properties: selections: type: array description: 'Opaque tariff and payment-method references returned by the quote.' items: type: string examples: - - architecto usage: type: - object - 'null' description: 'Optional annual energy usage overrides.' properties: electricity_annual_kwh: type: - number - 'null' description: 'Optional annual electricity usage in kWh.' examples: - 2900.0 gas_annual_kwh: type: - number - 'null' description: 'Optional annual gas usage in kWh.' examples: - 12000.0 examples: - [] idempotency_key: type: - string - 'null' description: 'Optional unique key used to safely retry this details submission.' examples: - 5a2a6ab5-c236-42e7-a1cc-2dac4b80f78b required: - selections parameters: - in: path name: quoteId description: 'The public quote ID returned by the address endpoint.' required: true schema: type: string examples: - 4db7e203-7a94-40c6-a7e2-72d8422d5995 '/api/v1/partner/quotes/{quoteId}/conversions': post: summary: 'Submit an offer conversion directly.' operationId: submitAnOfferConversionDirectly 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." parameters: [] responses: 200: description: '' content: application/json: schema: type: object properties: submission_id: type: string examples: - a1e5e588-b8c9-412a-b01c-9501e92cb3ef quote_id: type: string examples: - 4db7e203-7a94-40c6-a7e2-72d8422d5995 offer_reference: type: string examples: - 8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2 status: type: string examples: - PROCESSING examples: - submission_id: a1e5e588-b8c9-412a-b01c-9501e92cb3ef quote_id: 4db7e203-7a94-40c6-a7e2-72d8422d5995 offer_reference: 8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2 status: PROCESSING 404: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - quote_not_found message: type: string examples: - 'The requested quote was not found.' examples: - success: false error: code: quote_not_found message: 'The requested quote was not found.' 409: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - quote_not_ready_for_conversion message: type: string examples: - 'This quote does not have an offer available for conversion.' examples: - success: false error: code: quote_not_ready_for_conversion message: 'This quote does not have an offer available for conversion.' 410: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - quote_expired message: type: string examples: - 'This quote has expired. Create a new quote to continue.' examples: - success: false error: code: quote_expired message: 'This quote has expired. Create a new quote to continue.' 422: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - invalid_offer_reference message: type: string examples: - 'The selected offer does not belong to this quote.' examples: - success: false error: code: invalid_offer_reference message: 'The selected offer does not belong to this quote.' 500: description: '' content: application/json: schema: type: object properties: success: type: boolean examples: - false error: type: object properties: code: type: string examples: - conversion_submission_failed message: type: string examples: - 'We could not submit this conversion at this time.' examples: - success: false error: code: conversion_submission_failed message: 'We could not submit this conversion at this time.' tags: - Conversions requestBody: required: true content: application/json: schema: type: object properties: offer_reference: type: string description: 'The offer reference selected by the customer.' examples: - 8c628b23-21a3-4a1a-b541-d1bbd9d1f2f2 idempotency_key: type: string description: 'A unique key used to safely retry this conversion.' examples: - 9d6d7f75-00a4-4596-8766-0ee9354019ba customer: type: object description: "The customer's details." properties: email: type: string description: "The customer's email address." examples: - jane.smith@example.com first_name: type: - string - 'null' description: "The customer's first name." examples: - Jane last_name: type: - string - 'null' description: "The customer's last name." examples: - Smith title: type: - string - 'null' description: "The customer's title." examples: - Ms phone_number: type: - string - 'null' description: "The customer's phone number." examples: - '07123456789' date_of_birth: type: - string - 'null' description: "The customer's date of birth in YYYY-MM-DD format." examples: - '1985-06-15' required: - email examples: - [] direct_debit: type: - object - 'null' description: 'Direct Debit details, only when required by the offer.' properties: bank_account_number: type: - string - 'null' description: 'Bank account number.' examples: - '12345678' bank_sort_code: type: - string - 'null' description: 'Bank sort code, with or without spaces or hyphens.' examples: - 11-22-33 bank_payment_day: type: - string - 'null' description: 'Preferred payment day, from 01 to 28.' examples: - '15' examples: - [] required: - offer_reference - idempotency_key - customer parameters: - in: path name: quoteId description: 'The public quote ID returned by the quote endpoint.' required: true schema: type: string examples: - 4db7e203-7a94-40c6-a7e2-72d8422d5995