# Return available services for given address.

This endpoint is called to find what services are available at a given
address with a supplier.

An address query parameter will be supplied specifying address ID and type.

All parameters are mandatory and will always be supplied by the Fibre Cafe.

Endpoint: GET /service-availability
Version: 1.15
Security: oauth2

## Header parameters:

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

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

  - `Tenant` (string, required)
    The tenant that has placed the request on the Fibre Cafe
    Example: "TENANT1"

## Query parameters:

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

  - `serviceTypes` (array)
    If specified, filter the service availability check to only include the specified service type(s)
    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 provided type e.g. UPRN
    Example: "200004033694"

  - `address.identifier.type` (string, required)
    Type of addressId provided e.g. UPRN
    Example: "UPRN"

  - `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, required)
    Discriminator used to identify the sub unit
    Example: "Floor 3"

  - `serviceSpecifications` (array, required)
    List of services that are available at this address

  - `serviceSpecifications.id` (string, required)
    Unique identifier for this service specification (if available)
    Example: "ftthl2r"

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

  - `serviceSpecifications.serviceCharacteristics` (array)
    Service characteristics supported by this service

  - `serviceSpecifications.serviceCharacteristics.name` (string, required)
    Name of the service characteristic
    Example: "LINE_PROFILE"

  - `serviceSpecifications.serviceCharacteristics.values` (array, required)
    Supported values for this characteristic
    Example: ["100/20"]

  - `siteInformation` (object)
    Describes site installation details and any constraints that may apply, along with any existing lines.

  - `siteInformation.newLine` (boolean)
    Indicates a new line can be installed even if there is an existing service

  - `siteInformation.installationType` (string)
    Type of installation required for a new line
    Enum: "STANDARD", "EXTENDED_STANDARD", "NON_STANDARD"

  - `siteInformation.constraints` (array)
    Where there are constraints that must be satisfied (soft LOC)

  - `siteInformation.constraints.code` (string, required)
    Service has availability with these constraints.
- SURVEY_REQUIRED
- BUSINESS_PARK
- FEASIBILITY_CHECK
- WAYLEAVE_REQUIRED
- WAYLEAVE_OWNER
- WAYLEAVE_SHARED
- WAYLEAVE_PRIVATE
- WAYLEAVE_UNADOPTED
- WAYLEAVE_REFUSED
- UNECONOMIC_LENGTH
- UNECONOMIC_SURFACE
- OTHER
    Example: "WAYLEAVE_SHARED"

  - `siteInformation.constraints.text` (string)
    Text explaining any constraint or LOC (optional)

  - `siteInformation.serviceReadyDate` (string)
    Date service will be/was ready
    Example: "2022-01-01"

  - `siteInformation.enniId` (string)
    Unique identifier of the ENNI (if available)
    Example: "S1889"

  - `siteInformation.siteName` (string)
    Unique identifier for point of presence/handover point (if available)

  - `siteInformation.siteLocation` (string)
    Site address for the point of presence/handover point (if available)

  - `siteInformation.lineCharacteristics` (array)
    Available characteristics of this new line (as supported)

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

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

  - `siteInformation.existingLines` (array)

  - `siteInformation.existingLines.installationType` (string)
    Type of installation/appointment required for a switch or restart of an existing line - omit if not required
    Enum: "STANDARD", "EXTENDED_STANDARD", "NON_STANDARD"

  - `siteInformation.existingLines.ont` (object)
    An existing ONT device that can be used for a (re)start or line takeover.

  - `siteInformation.existingLines.ont.ontReference` (string, required)
    ONT reference number
    Example: "ONT0000123123"

  - `siteInformation.existingLines.ont.serialNumber` (string)
    ONT serial number
    Example: "1234567890"

  - `siteInformation.existingLines.ont.manufacturer` (string)
    ONT manufacturer (if available)
    Example: "Nokia"

  - `siteInformation.existingLines.ont.floor` (string)
    ONT location - floor (if available/applicable)
    Example: "1"

  - `siteInformation.existingLines.ont.room` (string)
    ONT location - room (if available/applicable)
    Example: "Reception"

  - `siteInformation.existingLines.ont.position` (string)
    ONT location - position (if available/applicable)

  - `siteInformation.existingLines.ont.ports` (array, required)
    ONT port number(s)

  - `siteInformation.existingLines.ont.ports.portNumber` (number, required)
    ONT port number
    Example: 2

  - `siteInformation.existingLines.ont.ports.description` (string)
    Description/identifier/type of ONT port if available
    Example: "Data"

  - `siteInformation.existingLines.ont.ports.status` (string)
    Specify if this port is active (takeover), stopped (restart) or not available (e.g. fault)"
    Enum: "ACTIVE", "STOPPED", "UNAVAILABLE"

  - `siteInformation.existingLines.ont.ports.tenantActive` (boolean)
    True if this port is active on the tenant's network or false if a different tenant - omit if information is not available

  - `siteInformation.existingLines.ont.ports.stoppedDate` (string)
    The date the port was previously stopped (if applicable)
    Example: "2022-01-01T13:45:00.000Z"

  - `siteInformation.existingLines.lineId` (string)
    Where the line has a unique access identifier - usually reserved for FTTC i.e. copper-based lines
    Example: "OHP5738089O3"

  - `siteInformation.existingLines.lineCharacteristics` (array)
    Available characteristics of this line (as supported)

  - `unavailabilityReasons` (array)
    Where there is no availability, provides the reason(s)

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

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

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

## 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: "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_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: "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_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: "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_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: "INVALID_REQUEST", "MALFORMED_REQUEST", "NOT_AUTHORISED", "NOT_FOUND", "NOT_IMPLEMENTED", "SUPPLIER_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