# Return available services and ordering options for a given address.

Journey-led service availability check. Returns a summary of supplier availability,
details of any existing lines at the address, and a set of self-describing order
options that drive the ordering journey without requiring the consuming system to
implement product eligibility or ordering rules.

Each order option includes the supported order types (NEW, TRANSFER, TAKEOVER, START)
as an array — options that share the same supplier, service specification and
characteristics (e.g. TRANSFER and TAKEOVER) are collapsed into a single entry.
Each option also carries appointment requirements and the full set of required and
optional service characteristics — pre-populated where the value is known from
availability, or flagged as TENANT-sourced where the user must supply them.

Suppliers are queried in parallel. If a supplier fails or has no availability this
is reflected in the availabilitySummary; order options are only returned for
suppliers with AVAILABLE status.

Endpoint: GET /v2/service-availability
Version: 1.20
Security: oauth2

## Header parameters:

  - `X-Request-ID` (string, required)
    Unique identifier to link request and response events across the Fibre Cafe gateway

  - `X-Conversation-ID` (string, required)
    Identifier to track message journey across the Fibre Cafe gateway

## Query parameters:

  - `address` (object, required)
    Address identifier of provided type e.g. UPRN to check for service availability
    Example: {"id":"200004033694","type":"UPRN"}

  - `suppliers` (array)
    If specified, the request will be sent only to the specified supplier(s)
    Example: ["SUPPLIER1","SUPPLIER2"]

  - `serviceTypes` (array)
    If specified, filters the service availability check to only include the specified service types
    Enum: "BROADBAND", "ETHERNET"

## Response 200 fields (application/json):

  - `address` (object, required)
    Address for location associated with the service order.

  - `address.identifier` (object, required)
    Address identifier for location including type of identifier.

  - `address.identifier.id` (string, required)
    Address identifier of given type
    Example: "A00000031882"

  - `address.identifier.type` (string, required)
    Type of address identifier e.g. UPRN, NAD, DistrictCode, ROBT
    Example: "NAD"

  - `address.identifier.additionalIdentifiers` (array)
    Additional address identifiers where available/required for subsequent operations

  - `address.name` (string)
    Identifying name of the sub unit
    Example: "TWENTY"

  - `address.streetNumber` (string)
    Discriminator used to identify the property on a street
    Example: "20"

  - `address.streetName` (string)
    Name used to identify the street
    Example: "Kingston Road"

  - `address.locality` (string)
    Name used to identify the area

  - `address.city` (string)
    Name used to identify the town or city
    Example: "Staines-Upon-Thames"

  - `address.postcode` (string)
    Postal code
    Example: "TW184LG"

  - `address.country` (string)
    Name used to identify the country
    Example: "UK"

  - `address.subAddress` (object)
    More specific definition of a property within an urban area.

  - `address.subAddress.unitNumber` (string)
    Discriminator used to identify the sub unit
    Example: "Floor 3"

  - `address.qualifier` (string)
    Optional qualifier for this address
    Example: "Gold"

  - `address.source` (string)
    System identifier for the source of this address information
    Example: "OPENREACH"

  - `address.additionalAttributes` (array)
    Additional attributes of an address (where available)
e.g.

- UNINHABITED
- HOTSITE
- TEMPORARY

  - `address.additionalAttributes.name` (string, required)
    Name of the attribute
    Example: "UNINHABITED"

  - `address.additionalAttributes.value` (string, required)
    Value for this attribute
    Example: "true"

  - `availabilitySummary` (object, required)
    Cross-supplier availability summary for the queried address.
    Example: {"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"]}}]}

  - `availabilitySummary.serviceAvailable` (boolean, required)
    True if at least one supplier returned availability and order options exist.
    Example: true

  - `availabilitySummary.supplierCount` (integer, required)
    Total number of suppliers queried.
    Example: 2

  - `availabilitySummary.supplierResults` (integer, required)
    Number of suppliers that returned a result (AVAILABLE or UNAVAILABLE — excludes FAILED).
    Example: 1

  - `availabilitySummary.supplierStatus` (array, required)
    Per-supplier availability status.
    Example: [{"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"]}}]

  - `availabilitySummary.supplierStatus.supplier` (string, required)
    System identifier for a supplier on the Fibre Cafe.
    Example: "SUPPLIER1"

  - `availabilitySummary.supplierStatus.status` (string, required)
    The availability status returned for a supplier:
- AVAILABLE : Supplier has services available and order options have been returned.
- UNAVAILABLE : Supplier has no services available at this address.
- FAILED : The Fibre Cafe could not obtain a result from this supplier.
    Enum: "AVAILABLE", "UNAVAILABLE", "FAILED"

  - `availabilitySummary.supplierStatus.unavailabilityReasons` (array)
    Reasons for unavailability. Present when status is UNAVAILABLE.

  - `availabilitySummary.supplierStatus.unavailabilityReasons.code` (string, required)
    Reason why service is unavailable (hard LOC):

- NOT_PLANNED
- IN_PLANNING
- UNDER_CONSTRUCTION
- OUT_OF_OPTIC_RANGE
- WAYLEAVE_ISSUE
- UNECONOMIC_LENGTH
- UNECONOMIC_SURFACE
- UNECONOMIC_OTHER
- OTHER
    Example: "OUT_OF_OPTIC_RANGE"

  - `availabilitySummary.supplierStatus.unavailabilityReasons.text` (string)
    Text explaining reason for no availability (optional)

  - `availabilitySummary.supplierStatus.error` (object)
    Represents an error with code to denote origin/cause.

- INVALID_REQUEST : Request was well-formed/syntactically correct but did not pass validation requirements
- MALFORMED_REQUEST : Request was not valid JSON or missing mandatory parameters
- NOT_AUTHORISED : User was not authenticated and/or authorised to use endpoint
- NOT_FOUND : Requested entity was not found
- SUPPLIER_FAULT : An unexpected problem originating from the supplier API
- SUPPLIER_TIMED_OUT : The Fibre Cafe did not receive a timely response from the supplier
- GATEWAY_FAULT : An unexpected problem originating on the Fibre Cafe gateway

  - `availabilitySummary.supplierStatus.error.uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `availabilitySummary.supplierStatus.error.code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `availabilitySummary.supplierStatus.error.messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

  - `existingLines` (array)
    Physical lines or ONTs found at the address across all queried suppliers.
Omitted when no existing infrastructure is present.

  - `orderOptions` (array)
    Self-describing order options available at this address. Omitted when
serviceAvailable is false.

  - `orderOptions.orderTypes` (array, required)
    One or more order types supported by this option. Options that share identical
supplier, service specification, characteristics and appointment requirements
(e.g. TRANSFER and TAKEOVER) are returned as a single entry with both types listed.
    Example: ["TRANSFER","TAKEOVER"]

  - `orderOptions.description` (string, required)
    Human-readable description of this order option for portal display.
    Example: "Install a new FTTP service at this address. An engineer appointment is required."

  - `orderOptions.supplier` (string, required)
    Supplier that will fulfil this order.
    Example: "SUPPLIER1"

  - `orderOptions.serviceSpecification` (object, required)
    Details of a service the supplier provides at the selected address.

  - `orderOptions.serviceSpecification.id` (string, required)
    Unique identifier for this service specification
    Example: "ftthl2r"

  - `orderOptions.serviceSpecification.name` (string)
    Name of the service
    Example: "FTTH"

  - `orderOptions.lineCharacteristics` (array)
    Informational characteristics about this order option (e.g. lead time, install notes, minimum site visit reason).

  - `orderOptions.lineCharacteristics.name` (string, required)
    Name of the line characteristic
    Example: "DOWNSTREAM_BANDWIDTH"

  - `orderOptions.lineCharacteristics.value` (string, required)
    Value for this characteristic
    Example: "68700"

  - `orderOptions.appointment` (object, required)
    Appointment requirements for this order option.

  - `orderOptions.appointment.required` (boolean, required)
    Whether an engineer appointment must be booked before this order can be placed.
    Example: true

  - `orderOptions.appointment.installationType` (string)
    Installation is necessary and hence an appointment is required - ensure this is reserved and included in the order.
Type of installation involved:

- STANDARD
- EXTENDED_STANDARD
- NON_STANDARD
    Example: "STANDARD"

  - `orderOptions.appointment.engineerTasks` (array)
    Engineer tasks to be performed at installation appointment.

- INSTALL_ROUTER
- TEST_SINGLE_DEVICE
- ADDITIONAL_CABLING
- TEST_MULTIPLE_DEVICES
- INSTALL_BBU
- VOICE_REINJECTION
- PROVE_IP_VOICE
- ENSURE_TELECARE
    Example: ["TEST_SINGLE_DEVICE"]

  - `orderOptions.requiredServiceCharacteristics` (array, required)
    Characteristics that must be included in the order.
- source AVAILABILITY : value is pre-populated and should be passed through unchanged.
- source TENANT : value must be collected from the user; allowedValues constrains what is permitted.

  - `orderOptions.requiredServiceCharacteristics.name` (string, required)
    Characteristic name.
    Example: "LINE_PROFILE"

  - `orderOptions.requiredServiceCharacteristics.source` (string)
    Indicates where a service characteristic value originates:
- TENANT : The value must be collected from the user.
- AVAILABILITY : The value is pre-populated from the availability response and should be passed through to the order unchanged.
    Enum: "TENANT", "AVAILABILITY"

  - `orderOptions.requiredServiceCharacteristics.value` (string)
    Pre-populated value. Present for AVAILABILITY-sourced characteristics and where only one value is possible.
    Example: "1000/115"

  - `orderOptions.requiredServiceCharacteristics.allowedValues` (array)
    The permitted values for this characteristic. Required characteristics with source TENANT must use one of these values.
    Example: ["80/20","160/30","330/50","550/75","1000/115"]

  - `orderOptions.requiredServiceCharacteristics.default` (string)
    Default value applied if this optional characteristic is not specified in the order.
    Example: "Standard"

  - `orderOptions.requiredServiceCharacteristics.description` (string)
    Human-readable explanation. Used for optional characteristics that represent a meaningful journey choice (e.g. migration trigger).

  - `orderOptions.requiredServiceCharacteristics.requiredWhen` (string)
    Conditional expression. This characteristic becomes required when the expression evaluates to true (e.g. NAMED_ENGINEER=Y).
    Example: "NAMED_ENGINEER=Y"

  - `orderOptions.requiredServiceCharacteristics.allowedWhen` (string)
    Conditional expression. This characteristic is only applicable when the expression evaluates to true (e.g. SITE_VISIT_REASON in [Premium, Advanced]).
    Example: "SITE_VISIT_REASON in [Premium, Advanced]"

  - `orderOptions.optionalServiceCharacteristics` (array, required)
    Characteristics that may optionally be included in the order. May carry a pre-populated
AVAILABILITY value (e.g. LINE_ID for copper migration), conditional requirement rules
(requiredWhen), and conditional availability rules (allowedWhen).

## Response 400 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

## Response 401 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

## Response 422 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]

## Response 500 fields (application/json):

  - `uuid` (string, required)
    Unique identifier of this error - for tracing purposes
    Example: "87432dfb-2e47-4532-a1b7-4b113d48867d"

  - `code` (string, required)
    Fibre Cafe error codes
    Enum: "GATEWAY_FAULT", "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_FAULT", "SUPPLIER_TIMED_OUT", "TENANT_FAULT"

  - `messages` (array, required)
    Message describing the error
    Example: ["e.g. Invalid value for field x - accepted values are y"]


## Response 403 fields

## Response 503 fields