API Documentation & Guides

# Service Availability

This API allows you to check which broadband services are available at a given address, using a Unique Property Reference Number (UPRN) or other supported address identifiers.

# Service Availability Endpoint

# GET /WholesaleGateway/v1.0/gateway/service-availability

# Description

Checks the availability of broadband services at a specified address. Returns a list of available services, their characteristics, and relevant notes for ordering.

# Headers

  • X-Request-ID (string, required): Unique request identifier for tracing.
  • X-Conversation-ID (string, required): Conversation/session identifier.
  • Tenant (string, required): Tenant identifier.
  • Authorization (string, required): Bearer token for authentication.

# Query Parameters

  • address (required): Encoded JSON string specifying the address. Example: { "id": "<uprn>", "type": "UPRN" }

# Example Request

GET {{baseUrl}}/WholesaleGateway/v1.0/gateway/service-availability?address=%7B"id":"10025559646","type":"UPRN"%7D
X-Request-ID: 123
X-Conversation-ID: conversation-456
Tenant: TENANT-ID
Authorization: Bearer <token>

# Example Response

{
  "address": {
    "identifier": {
      "id": "10025559646",
      "type": "UPRN"
    },
    "name": "Unit H",
    "streetNumber": "1",
    "streetName": "The Courtyard",
    "locality": "Tewkesbury Business Park",
    "city": "Tewkesbury",
    "postcode": "GL20 8GD",
    "country": "UK",
    "subAddress": {
      "name": "Netomnia",
      "unitNumber": "H"
    }
  },
  "serviceSpecifications": [
    {
      "id": "fttp",
      "name": "FTTP",
      "serviceCharacteristics": [
        {
          "name": "LINE_PROFILE",
          "values": ["55/55", "80/20", "100/100"]
        },
        {
          "name": "MINIMUM_SPEED",
          "values": ["100", "200", "500"]
        }
      ]
    }
  ],
  "siteInformation": {
    "newLine": true,
    "installationType": "STANDARD",
    "constraints": [
      {
        "code": "SURVEY_REQUIRED",
        "text": "Site survey required before installation"
      }
    ],
    "serviceReadyDate": "2025-02-15",
    "enniId": "ENNI-001",
    "siteName": "Tewkesbury POP",
    "siteLocation": "Tewkesbury Business Park",
    "existingLines": [
      {
        "enniId": "ENNI-001",
        "siteName": "Tewkesbury POP",
        "siteLocation": "Tewkesbury Business Park",
        "installationType": "STANDARD",
        "ont": {
          "ontReference": "ONT-123",
          "serialNumber": "SN123456789",
          "manufacturer": "Huawei",
          "floor": "Ground",
          "room": "Communications Room",
          "position": "Rack A",
          "ports": [
            {
              "portNumber": 1,
              "description": "GE Port 1",
              "status": "ACTIVE",
              "tenantActive": true
            }
          ]
        },
        "lineId": "LINE-001",
        "lineCharacteristics": [
          {
            "name": "LINE_PROFILE",
            "value": "55/55"
          }
        ]
      }
    ]
  },
  "unavailabilityReasons": []
}

# Field Descriptions

  • address: object — Complete address information including identifier and full address details
    • identifier: { id: string, type: string } — Address identifier (e.g., UPRN)
    • name: string — Identifying name of the sub unit (e.g., "Unit H")
    • streetNumber: string — Property number on the street
    • streetName: string — Name of the street
    • locality: string — Area name
    • city: string — Town or city name
    • postcode: string — Postal code
    • country: string — Country name
    • subAddress: object — More specific property definition
      • name: string — Identifying name of the sub unit
      • unitNumber: string — Discriminator for the sub unit
  • serviceSpecifications[]: array — List of services available at this address
    • id: string — Unique identifier for the service specification
    • name: string — Name of the service
    • serviceCharacteristics[]: array — Service characteristics supported by this service
      • name: string — Name of the service characteristic (e.g., LINE_PROFILE, MINIMUM_SPEED)
      • values[]: array — Array of possible values for this characteristic
  • siteInformation: object — Describes site installation details and constraints
    • newLine: boolean — Indicates if a new line can be installed
    • installationType: string — Type of installation required (STANDARD, EXTENDED_STANDARD, NON_STANDARD)
    • constraints[]: array — Soft constraints that must be satisfied
      • code: string — Constraint code (e.g., SURVEY_REQUIRED, WAYLEAVE_REQUIRED)
      • text: string — Text explaining the constraint
    • serviceReadyDate: string — Date service will be/was ready
    • enniId: string — Unique identifier of the ENNI
    • siteName: string — Point of presence/handover point identifier
    • siteLocation: string — Site address for the point of presence
    • existingLines[]: array — Existing lines data
      • enniId: string — Unique identifier of the ENNI
      • siteName: string — Point of presence identifier
      • siteLocation: string — Site address
      • installationType: string — Type of installation required
      • ont: object — Existing ONT device information
        • ontReference: string — ONT reference number
        • serialNumber: string — ONT serial number
        • manufacturer: string — ONT manufacturer
        • floor: string — ONT location floor
        • room: string — ONT location room
        • position: string — ONT location position
        • ports[]: array — ONT port information
          • portNumber: number — Port number
          • description: string — Port description/type
          • status: string — Port status (ACTIVE, STOPPED, UNAVAILABLE)
          • tenantActive: boolean — Whether port is active on tenant's network
      • lineId: string — Unique access identifier for the line
      • lineCharacteristics[]: array — Available characteristics of this line
        • name: string — Name of the line characteristic
        • value: string — Value for this characteristic
  • unavailabilityReasons[]: array — Reasons why service is unavailable (hard LOC)
    • code: string — Reason code (e.g., IN_PLANNING, UNDER_CONSTRUCTION, OUT_OF_OPTIC_RANGE)
    • text: string — Text explaining reason for no availability

# Error Handling

HTTP Status Error Code Description When it Occurs
400 MALFORMED_REQUEST The request could not be understood by the server due to malformed syntax Invalid or missing address parameter, malformed JSON
401 NOT_AUTHORISED The request was not authorised Missing or invalid OAuth token
422 INVALID_REQUEST The request did not satisfy validation Invalid address format, missing required fields
500 SUPPLIER_FAULT An internal error occurred Unexpected server error
504 SUPPLIER_TIMED_OUT The Netomnia API timed out Request timeout

# Example Error Response

{
  "uuid": "6caf4987-63db-4d5b-bbce-b7ec14f2dbf9",
  "code": "MALFORMED_REQUEST",
  "messages": ["Information about malformed request here..."]
}

← Appointment Management →