API Documentation & Guides

# Appointment Management

The Appointment Management API supports the full lifecycle of appointment handling, including:

  • Retrieving available appointment slots for a given address and service specification.
  • Booking appointments for new installations, repairs, or modifications.
  • Providing clear enum values, field requirements, and example payloads for integration.

# Quick Start Workflow

  1. Check Service Availability:
  2. Retrieve Available Slots:
    • Call GET /WholesaleGateway/v1.0/gateway/available-appointments with the required parameters.
  3. Book Appointment:
    • Use POST /WholesaleGateway/v1.0/gateway/appointments with the selected slot and required details.
  4. Use Appointment Reference:
    • Include the returned id or supplierReference in your order payload.

# Example Scenarios

  • Book a New Install:
    1. Check Service Availability to determine available services.
    2. Retrieve available slots with appointmentPurpose=PROVIDE.
    3. Book the slot and use the returned reference in your order.
  • Book a Repair:
    1. Use appointmentPurpose=REPAIR and follow the same process.
  • Handle Slot Conflict:
    1. If you receive a 409 Conflict, re-query available slots and retry booking.

# Available Appointments Endpoint

# GET /WholesaleGateway/v1.0/gateway/available-appointments

# Description:

Retrieve available appointment slots for a given address and service specification.

# 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:

Name Type Required Description
address string Yes Encoded JSON, e.g. { "id": "<uprn>", "type": "UPRN" }
appointmentPurpose string Yes Purpose of appointment (see enum: PROVIDE, REPAIR, MODIFY)
serviceSpecification string Yes Encoded JSON, e.g. { "id": "fttp", "name": "FTTP" }
appointmentFromDate string No Date to search from (ISO 8601 date)
classifications string No Timeslot classification (see enum below)

# Example Request:

GET {{baseUrl}}/WholesaleGateway/v1.0/gateway/available-appointments?address=%7B"id":"10025559646","type":"UPRN"%7D&appointmentPurpose=PROVIDE&serviceSpecification=%7B"id":"fttp","name":"FTTP"%7D&appointmentFromDate=2025-01-25&classifications=WEEKDAY_AM
X-Request-ID: qwerty
X-Conversation-ID: abcde
Tenant: TENANT-ID
Authorization: Bearer <token>

# Example Response:

{
  "address": {
    "id": "10025559646",
    "type": "UPRN"
  },
  "serviceSpecification": {
    "id": "fttp",
    "name": "FTTP"
  },
  "availableTimeslots": [
    {
      "timeslotStartDateTime": "2025-01-18T08:00:00.000Z",
      "timeslotEndDateTime": "2025-01-18T13:00:00.000Z",
      "classification": "WEEKDAY_AM",
      "standard": true
    }
  ]
}

# Appointments Endpoint

# POST /WholesaleGateway/v1.0/gateway/appointments

# Description:

Book an appointment for a given address and service specification.

# 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.

# Request 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"
  }
}

# Example Response:

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

# Field Descriptions

Field Type Required Description
address object Yes Address identifier (e.g., UPRN)
└─ id string Yes Unique property reference number
└─ type string Yes Address type (e.g., UPRN)
serviceSpecification object Yes Service type
└─ id string Yes Service specification ID (e.g., fttp)
└─ name string No Service name (e.g., FTTP)
appointmentPurpose / purpose string Yes Purpose of appointment (see enum)
appointmentFromDate string No Date to search from (ISO 8601)
classifications string No Timeslot classification (see enum)
availableTimeslots[] array Yes List of available timeslots
└─ timeslotStartDateTime string Yes Start of timeslot (ISO 8601)
└─ timeslotEndDateTime string Yes End of timeslot (ISO 8601)
└─ classification string Yes Timeslot classification (see enum)
└─ standard boolean Yes Whether the timeslot is standard
timeslot object Yes Timeslot object for booking
id integer Yes Unique identifier for the booked appointment
supplierReference string Yes Unique reference generated by the supplier
expiryDateTime string No Date/time when the reservation will expire

# 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 parameters, 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 appointmentPurpose, 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": "d9bb42fa-a6c4-4537-8e05-e8387638cf31",
  "code": "INVALID_REQUEST",
  "messages": ["Information about validation here..."]
}

# Enum Values

# appointmentPurpose

Value Description
PROVIDE New service installation
REPAIR Fault repair appointment
MODIFY Service modification

# Field Requirements and Example Values

Field Required Example Value Notes/Enum Values
address Yes { "id": "10025559646", "type": "UPRN" } Must be valid JSON, URL-encoded
appointmentPurpose Yes PROVIDE PROVIDE, REPAIR, MODIFY
serviceSpecification Yes { "id": "fttp", "name": "FTTP" } Must be valid JSON, URL-encoded
appointmentFromDate No 2025-01-25 ISO 8601 date
classifications No WEEKDAY_AM See table below

# Classification Details

Classification Applicable Timeslot
WEEKDAY Mon-Fri (full day)
WEEKDAY_AM Mon-Fri 0800-1300
WEEKDAY_PM Mon-Fri 1300-1800
WEEKDAY_EARLY Mon-Fri early morning
WEEKDAY_EVENING Mon-Fri evening
SATURDAY Sat (full day)
SATURDAY_AM Sat 0800-1300
SATURDAY_PM Sat 1300-1800
SATURDAY_EARLY Sat early morning
SATURDAY_EVENING Sat evening
SUNDAY Sun (full day)
SUNDAY_AM Sun 0800-1300
SUNDAY_PM Sun 1300-1800
SUNDAY_EARLY Sun early morning
SUNDAY_EVENING Sun evening

← Order Management →