Sample Integration Flow

This guide demonstrates a typical end-to-end flow for integrating with the Netomnia Wholesale Gateway API.

1. Check Service Availability

GET /WholesaleGateway/v1.0/gateway/service-availability?address=%7B"id":"10025559646","type":"UPRN"%7D
Headers:
  X-Request-ID: req-1
  X-Conversation-ID: conv-1
  Tenant: YOUR_TENANT
  Authorization: Bearer YOUR_OAUTH_TOKEN

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"
  },
  "serviceSpecifications": [
    {
      "id": "fttp",
      "name": "FTTP",
      "serviceCharacteristics": [
        {
          "name": "LINE_PROFILE",
          "values": ["55/55", "80/20", "100/100"]
        },
        {
          "name": "AUTHENTICATION_AGENT",
          "values": ["DHCPRelayAgent"]
        },
        {
          "name": "MINIMUM_SPEED",
          "values": ["100", "200", "500"]
        }
      ]
    }
  ],
  "siteInformation": {
    "newLine": true,
    "installationType": "STANDARD",
    "enniId": "ENNI-001",
    "siteName": "Site A",
    "siteLocation": "Location B"
  }
}

2. Book an Appointment

POST /WholesaleGateway/v1.0/gateway/appointments
Headers:
  X-Request-ID: req-2
  X-Conversation-ID: conv-1
  Tenant: YOUR_TENANT
  Authorization: Bearer YOUR_OAUTH_TOKEN
Body:
{
  "id": 159,
  "address": { "id": "10025559646", "type": "UPRN" },
  "serviceSpecification": { "id": "fttp" },
  "purpose": "PROVIDE",
  "timeslot": {
    "timeslotStartDateTime": "2025-07-16T08:00:00.000Z",
    "timeslotEndDateTime": "2025-07-16T13:00:00.000Z"
  }
}

Response:

{
  "id": 159,
  "supplierReference": "APPT-2025-001",
  "address": { "id": "10025559646", "type": "UPRN" },
  "serviceSpecification": { "id": "fttp", "name": "FTTP" },
  "purpose": "PROVIDE",
  "timeslot": {
    "timeslotStartDateTime": "2025-07-16T08:00:00.000Z",
    "timeslotEndDateTime": "2025-07-16T13:00:00.000Z",
    "classification": "WEEKDAY_AM",
    "standard": true
  },
  "expiryDateTime": "2025-07-15T23:59:59.000Z"
}

3. Submit an Order

POST /WholesaleGateway/v1.0/gateway/service-orders
Headers:
  X-Request-ID: req-3
  X-Conversation-ID: conv-1
  Tenant: YOUR_TENANT
  Authorization: Bearer YOUR_OAUTH_TOKEN
Body:
{
  "id": 127,
  "orderType": "NEW",
  "tenant": "YOUR_TENANT",
  "address": { "id": "10025559646", "type": "UPRN" },
  "serviceOrderItem": {
    "serviceSpecification": { "id": "fttp" },
    "serviceCharacteristics": [
      { "name": "LINE_PROFILE", "value": "55/55" },
      { "name": "AUTHENTICATION_AGENT", "value": "DHCPRelayAgent" },
      { "name": "MINIMUM_SPEED", "value": "100" },
      { "name": "END_USER_TYPE", "value": "RESIDENTIAL" }
    ]
  },
  "primaryContact": { "name": "Jane Doe", "email": "jane@doe.com", "phoneNumber": "01234 567890" },
  "appointmentReservationId": 159,
  "requestedCompletionDate": "2025-07-28"
}

Response: Status Code: 202 Accepted

The order has been accepted for processing. No response body is returned.

Note: Order acknowledgment and status updates will be sent via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications.

4. Receive KCI/Webhook Events

Your endpoint will receive webhooks for order status updates via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications (see Webhooks).