Skip to content
/
Service Availability
Last updated

Service Availability

A supplier may support 1 or more active services at an address. The number of services allowed will vary by supplier with some only allowing a single service at an address and others allowing multiple connections and/or multi-port ONTs.

When querying service availability for an address, the response will show if services are available by returning the available service specifications and underlying line profiles that can be used - see Services and Line Profiles. Whether a new line can be installed (either as the first service or as an additional service) will be indicated by the presence of siteInformation.line field on the service availability response.

API Versions

Two versions of the service availability endpoint are now available:

  • /service-availability (v1) - returns raw per-supplier availability data (service specifications, line profiles and site/line information). The tenant is responsible for applying ordering rules when working out which order type, service specification, line profile and characteristics to use for a subsequent order - see the worked examples (v1) below.
  • /v2/service-availability (v2) - a journey-led endpoint that pre-computes valid order options for the address, ready to drive an ordering journey directly without the tenant needing to implement supplier-specific product or ordering rules - see Service Availability V2 below.

Both endpoints remain available. New integrations should prefer v2 where the self-describing order options meet their needs; v1 remains supported for existing integrations.

Service Availability V2

The /v2/service-availability endpoint queries suppliers in parallel and returns a cross-supplier summary, details of any existing lines at the address, and a set of self-describing order options that can be used to construct a POST /service-orders request directly.

Response structure

  • address - the resolved address for the query.
  • availabilitySummary - a cross-supplier summary:
    • serviceAvailable - true if at least one supplier returned availability and order options exist.
    • supplierCount / supplierResults - the number of suppliers queried vs. the number that returned a usable result (AVAILABLE or UNAVAILABLE) - a supplier that fails or times out is excluded from supplierResults.
    • supplierStatus - the status of each supplier queried (AVAILABLE, UNAVAILABLE or FAILED), with unavailabilityReasons populated for UNAVAILABLE suppliers and error populated for FAILED suppliers.
  • existingLines - existing fibre (ONT) or copper lines found at the address, consolidated across suppliers. A line visible to multiple suppliers via shared underlying infrastructure (e.g. Openreach) is returned once, listing all suppliers that reported it. Omitted when there is no existing infrastructure at the address.
  • orderOptions - the self-describing order options available at the address - see below. Omitted when serviceAvailable is false.

Order Options

Order options are only returned for suppliers with an AVAILABLE status. Each order option contains:

  • orderTypes - one or more order types supported by this option (NEW, TRANSFER, TAKEOVER, START - see Order Type). Options that share the same supplier, service specification, characteristics and appointment requirements (e.g. TRANSFER and TAKEOVER) are collapsed into a single entry listing both order types.

  • description - a human-readable description of the option, suitable for display to the end user.

  • supplier and serviceSpecification - identify the supplier and service specification (see Services and Line Profiles) that will fulfil the order.

  • lineCharacteristics - informational characteristics about the option, such as lead time, install notes or minimum site visit reason.

  • appointment - whether an engineer appointment is required, plus the installationType and any optional engineerTasks that may be requested alongside it.

  • requiredServiceCharacteristics / optionalServiceCharacteristics - the service characteristics that apply to this option. Each carries a source:

    • AVAILABILITY - the value is pre-populated from availability data (e.g. an existing LINE_ID for a copper migration) and should be passed through to the order unchanged.
    • TENANT - the value must be collected from the end user; where present, allowedValues constrains what may be supplied.

    Optional characteristics may also carry a default value, a requiredWhen condition (the characteristic becomes required when the expression evaluates true, e.g. NAMED_ENGINEER=Y), and/or an allowedWhen condition (the characteristic only applies when the expression evaluates true, e.g. SITE_VISIT_REASON in [Premium, Advanced]).

Because v2 pre-computes valid order options directly, it removes the need for the tenant to replicate the rules covered in the v1 worked examples below - e.g. working out whether a provide, modify, swap, switch or takeover order applies, or which line profile combinations are valid for the address.

Example Responses

New line available, no existing infrastructure

A single supplier has availability for a new FTTP install. LINE_PROFILE must be supplied by the tenant from the allowedValues list, and CARE_LEVEL is an optional, tenant-sourced characteristic with a default.

{
  "address": {
    "identifier": {
      "id": "200004033694",
      "type": "UPRN"
    },
    "streetNumber": "20",
    "streetName": "Kingston Road",
    "city": "Staines-Upon-Thames",
    "postcode": "TW184LG",
    "country": "UK"
  },
  "availabilitySummary": {
    "serviceAvailable": true,
    "supplierCount": 1,
    "supplierResults": 1,
    "supplierStatus": [
      {
        "supplier": "SUPPLIER1",
        "status": "AVAILABLE"
      }
    ]
  },
  "orderOptions": [
    {
      "orderTypes": ["NEW"],
      "description": "Install a new FTTP service at this address. An engineer appointment is required.",
      "supplier": "SUPPLIER1",
      "serviceSpecification": {
        "id": "FTTP"
      },
      "lineCharacteristics": [
        {
          "name": "MINIMUM_LEAD_TIME",
          "value": "10"
        }
      ],
      "appointment": {
        "required": true,
        "installationType": "STANDARD",
        "engineerTasks": ["INSTALL_ROUTER", "TEST_SINGLE_DEVICE"]
      },
      "requiredServiceCharacteristics": [
        {
          "name": "LINE_PROFILE",
          "source": "TENANT",
          "allowedValues": ["80/20", "160/30", "330/50", "550/75", "1000/115"]
        }
      ],
      "optionalServiceCharacteristics": [
        {
          "name": "CARE_LEVEL",
          "source": "TENANT",
          "default": "Standard",
          "allowedValues": ["Standard", "Premium"]
        }
      ]
    }
  ]
}

Existing copper line - transfer/takeover, one supplier failed

SUPPLIER2 timed out and is excluded from supplierResults; only SUPPLIER1 (which has the existing line) returns an order option. The TRANSFER and TAKEOVER order types are collapsed into a single option since they share the same supplier, service specification and characteristics. LINE_ID is pre-populated from the existing line (source: AVAILABILITY), while SITE_VISIT_REASON and the conditional NAMED_ENGINEER/NAMED_ENGINEER_NOTES characteristics must be supplied by the tenant.

{
  "address": {
    "identifier": {
      "id": "200004033694",
      "type": "UPRN"
    },
    "streetNumber": "20",
    "streetName": "Kingston Road",
    "city": "Staines-Upon-Thames",
    "postcode": "TW184LG",
    "country": "UK"
  },
  "availabilitySummary": {
    "serviceAvailable": true,
    "supplierCount": 2,
    "supplierResults": 1,
    "supplierStatus": [
      {
        "supplier": "SUPPLIER1",
        "status": "AVAILABLE"
      },
      {
        "supplier": "SUPPLIER2",
        "status": "FAILED",
        "error": {
          "uuid": "0884e75c-5424-456d-ac61-bef2010b7962",
          "code": "SUPPLIER_TIMED_OUT",
          "messages": [
            "The Fibre Cafe did not receive a timely response from the supplier"
          ]
        }
      }
    ]
  },
  "existingLines": [
    {
      "lineType": "COPPER",
      "lineId": "OHP5738089O3",
      "status": "ACTIVE",
      "productType": "SOGEA",
      "suppliers": ["SUPPLIER1"]
    }
  ],
  "orderOptions": [
    {
      "orderTypes": ["TRANSFER", "TAKEOVER"],
      "description": "Take over or transfer the existing copper service at this address to SUPPLIER1.",
      "supplier": "SUPPLIER1",
      "serviceSpecification": {
        "id": "SOGEA"
      },
      "appointment": {
        "required": false
      },
      "requiredServiceCharacteristics": [
        {
          "name": "LINE_ID",
          "source": "AVAILABILITY",
          "value": "OHP5738089O3"
        }
      ],
      "optionalServiceCharacteristics": [
        {
          "name": "SITE_VISIT_REASON",
          "source": "TENANT",
          "allowedValues": ["Standard", "Premium", "Advanced"]
        },
        {
          "name": "NAMED_ENGINEER",
          "source": "TENANT",
          "default": "N",
          "allowedValues": ["Y", "N"],
          "allowedWhen": "SITE_VISIT_REASON in [Premium, Advanced]"
        },
        {
          "name": "NAMED_ENGINEER_NOTES",
          "source": "TENANT",
          "requiredWhen": "NAMED_ENGINEER=Y"
        }
      ]
    }
  ]
}

Worked Examples (v1)

Single Service Specification

Assuming a supplier has 1 type of product (service specification) e.g. FTTP and 4 different products/line speeds available (line profiles) e.g. 1, 2, 3, 4

TENANT1 queries an address for service availability:

If the address has no coverage and/or no products available:

  • Service availability returns no availability (unavailabilityReasons will be populated)

If the address has coverage with all 4 products available then service availability returns:

  • serviceSpecification: 'FTTP' with 4 LINE_PROFILE service characteristics: '1', '2', '3', '4'
  • siteInformation.line will be present to identify a new line can be installed

TENANT1 places a provide order for 1 of the 4 line profiles (e.g. 1) - this completes and the service is now live.

Supplier only allows 1 service per address

TENANT1 or a different tenant (TENANT2) queries the same address for service availability:

Service availability shows existing line is active and no new line is available:

  • serviceSpecification: 'FTTP' with 4 LINE_PROFILE service characteristics: '1', '2', '3', '4'
  • siteInformation.line will not be present as no new line can be installed
  • siteInformation.existingLines[1] will identify the existing line

Options for TENANT1:

  • Place a modify order to change to a different line profile (e.g. 2, 3 or 4)
  • Place a cease order to end service

Options for TENANT2:

  • Place a switch or takeover order for 1 of the 4 line profiles - this would cease the TENANT1 service (unsolicited cease)

Supplier allows multiple services per address

TENANT1 or a different tenant (TENANT2) queries the same address for service availability:

Service availability shows existing line is active and a new line is available:

  • serviceSpecification: 'FTTP' with 4 LINE_PROFILE service characteristics: '1', '2', '3', '4'
  • siteInformation.line will be present to identify a new line can be installed
  • siteInformation.existingLines[1] will identify the existing line

Options for TENANT1:

  • Place a provide order for a new service with 1 of the 4 line profiles
  • Place a modify order to change the active service to a different line profile (e.g. 2, 3 or 4)
  • Place a cease order to end service

Options for TENANT2:

  • Place a provide order for a new service with 1 of the 4 line profiles (this will not affect the current service).
  • Place a switch or takeover order on the active service for 1 of the 4 line profiles - this would cease the TENANT1 service (unsolicited cease)

Multiple Service Specifications

Assuming a supplier has 2 types of product (service specifications) e.g. FTTP-PRO and FTTP-LITE and 4 different products/line speeds available (line profiles) e.g. 1, 2, 3, 4 where FTTP-LITE only supports the slower line profiles 1 and 2. The supplier supports an uplift to FTTP-PRO from FTTP-LITE.

TENANT1 queries an address for service availability where they already have an active service (line profile 1)

The address has an existing FTTP-LITE service installed so service availability returns:

  • serviceSpecification: 'FTTP-LITE' with 2 LINE_PROFILE service characteristics: '1', '2'
  • serviceSpecification: 'FTTP-PRO' with 4 LINE_PROFILE service characteristics: '1', '2', '3', '4'
  • siteInformation.line will identify if a new line can be installed alongside the existing line
  • siteInformation.existingLines[1] will identify the existing line with lineCharacteristics showing the current capabilities.

Options for TENANT1:

  • Place a modify order to change the line profile for the existing FTTP-LITE service to the other (i.e. 2)
  • Place a new provide order for FTTP-LITE for 1 of the 2 line profiles (e.g. 1) - this will be a new service alongside the existing FTTP-LITE service.
  • Place a new provide order for FTTP-PRO for 1 of the 4 line profiles (e.g. 4) - this will be a new service alongside the existing FTTP-LITE service.
  • Place a swap provide order to upgrade the existing FTTP-LITE service to FTTP-PRO with 1 of the 4 line profiles (e.g. 3)
  • Place a cease order to end the existing FTTP-LITE service
Previous page
Next page