Create an order for provide, cease or modify service.

post/service-orders

This endpoint can be called to place a order with a supplier to provide, cease or modify a service.

The gateway will validate the request and generate an order number which is returned. If the order is rejected immediately then a 400 code will be returned with reason(s) for the rejection in the response.

The order will then be sent to the supplier for processing and further updates will be sent via KCIs - this could include a rejection if the order does not meet supplier validation/processing rules. Once the order is acknowledged, the supplier may assign their own order number which will be returned in the KCI.

Securityoauth2
Request
header Parameters
X-Request-ID
required
string

Unique identifier to identify request and response events across the gateway

X-Conversation-ID
required
string

Identifier to track message journey across the gateway

Request Body schema: application/json
One of:

Represents an order for new service(s) at a particular address.

orderType
required
string (ProvideOrderType)

The type of order - new, (re)start, takeover or transfer

Enum: "NEW" "START" "TAKEOVER" "TRANSFER"
supplier
required
string^\w{1,20}$

System identifier for a supplier on the gateway that is associated with this order

required
object (AddressIdentifier)

Address identifier for location including type of identifier.

required
object (ServiceOrderItem)

Order for a service that the supplier provides at the selected address.

required
object (Contact)

Represents a contact available at the given address - primary contact must be provided.

object (Contact)

Represents a contact available at the given address - primary contact must be provided.

appointmentReservationId
number >= 1

Unique identifier for the reserved appointment (if applicable)

requestedCompletionDate
string <date>

Where not appointed, allows a date to be requested for the service activation.

engineerTasks
Array of strings (EngineerTasks)

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
hazards
string [ 1 .. 1000 ] characters

Hazard information about the site where the service will be installed

onSiteRestrictions
string [ 1 .. 1000 ] characters

Information about restrictions on the site where the service will be installed

notes
string [ 1 .. 1000 ] characters

Any notes about the order. This may include additional information that is required

Responses
201

Order was received by the gateway and will be acknowledged later via a KCI

400

Bad request - supplied request was malformed or missing mandatory parameters

401

Unauthorised access

403

The client is not permitted to access this resource.

422

Unprocessable entity - invalid data was provided

500

Unexpected Fibre Gateway error

503

Fibre Gateway is temporarily unavailable

Request samples
application/json
{
  • "orderType": "NEW",
  • "supplier": "DUMMY_SUPPLIER",
  • "address": {
    • "id": "A00000031882",
    • "type": "NAD",
    • "additionalIdentifiers": [
      • {
        • "id": "A00000031882",
        • "type": "NAD"
        }
      ]
    },
  • "serviceOrderItem": {
    • "serviceSpecification": {
      • "id": "ftthl2r"
      },
    • "serviceCharacteristics": [
      • {
        • "name": "LINE_PROFILE",
        • "value": "1G1G"
        }
      ]
    },
  • "primaryContact": {
    • "name": "John Smith",
    • "email": "john@smith.com",
    • "phoneNumber": "01234 567890"
    },
  • "secondaryContact": {
    • "name": "John Smith",
    • "email": "john@smith.com",
    • "phoneNumber": "01234 567890"
    },
  • "appointmentReservationId": 345,
  • "requestedCompletionDate": "2022-01-10",
  • "engineerTasks": [
    • "TEST_SINGLE_DEVICE"
    ],
  • "hazards": "Hazardous materials stored on site",
  • "onSiteRestrictions": "Restricted access",
  • "notes": "Lorem ipsum dolor sit amet..."
}
Response samples
application/json
{
  • "id": 123,
  • "status": "ACKNOWLEDGED",
  • "supplierOrderNumber": "A123X",
  • "appointmentSupplierReference": "123456543",
  • "appointmentTimeslot": {
    • "timeslotStartDateTime": "2022-01-10T09:00:00.000Z",
    • "timeslotEndDateTime": "2022-01-10T13:00:00.000Z",
    • "classification": "SATURDAY_AM",
    • "standard": true
    },
  • "created": "2022-01-01T09:09:33.001Z",
  • "updated": "2022-01-01T09:45:39.001Z",
  • "updates": [
    • {
      • "serviceOrderAmendment": {
        • "id": 234,
        • "supplierReference": "A123X-1",
        • "status": "REJECTED",
        • "orderId": 123,
        • "supplier": "DUMMY_SUPPLIER",
        • "serviceCharacteristics": [
          • {
            • "name": "LINE_PROFILE",
            • "value": "1G1G"
            }
          ],
        • "primaryContact": {
          • "name": "John Smith",
          • "email": "john@smith.com",
          • "phoneNumber": "01234 567890"
          },
        • "secondaryContact": {
          • "name": "John Smith",
          • "email": "john@smith.com",
          • "phoneNumber": "01234 567890"
          },
        • "appointmentReservationId": 345,
        • "requestedCompletionDate": "2022-01-10",
        • "engineerTasks": [
          • "TEST_SINGLE_DEVICE"
          ],
        • "hazards": "string",
        • "onSiteRestrictions": "string",
        • "notes": "Lorem ipsum dolor sit amet..."
        },
      • "id": "3456cf7d-4471-42e4-a5be-c24ed58a7aa6",
      • "supplier": "SUPPLIER1",
      • "sequenceNumber": 1,
      • "issuedOn": "2022-01-10T09:00:00.000Z",
      • "receivedOn": "2022-01-10T09:00:00.000Z",
      • "deliveredOn": "2022-01-10T09:00:00.000Z",
      • "deliveryStatus": "PENDING",
      • "updateType": "ACTION_REQUIRED",
      • "supplierNotes": [
        • {
          • "note": "Lorem ipsum dolor sit amet...",
          • "type": "Engineer Note",
          • "created": "2022-01-01T09:09:33.001Z"
          }
        ],
      • "information": {
        • "type": "CREATED",
        • "code": "NETWORK_ISSUE",
        • "text": "Resolving network issue",
        • "supplierCode": "313"
        },
      • "action": {
        • "type": "INFORMATION_REQUIRED",
        • "code": "NETWORK_ISSUE",
        • "text": "Fault between Node and Toby.",
        • "supplierCode": "313"
        },
      • "error": {
        • "uuid": "87432dfb-2e47-4532-a1b7-4b113d48867d",
        • "code": "GATEWAY_FAULT",
        • "messages": [
          • "e.g. Invalid value for field x - accepted values are y"
          ]
        },
      • "serviceOrderCancellation": {
        • "id": 234,
        • "supplierReference": "A123X-1",
        • "status": "REJECTED",
        • "supplier": "DUMMY_SUPPLIER",
        • "orderId": 123,
        • "reasonCode": "CUSTOMER_CHANGED_MIND",
        • "text": "Delivery too long"
        }
      }
    ],
  • "committedDate": "2022-01-01T09:09:33.001Z",
  • "targetDate": "2022-01-01T09:09:33.001Z",
  • "orderType": "NEW",
  • "supplier": "DUMMY_SUPPLIER",
  • "address": {
    • "id": "A00000031882",
    • "type": "NAD",
    • "additionalIdentifiers": [
      • {
        • "id": "A00000031882",
        • "type": "NAD"
        }
      ]
    },
  • "serviceOrderItem": {
    • "serviceSpecification": {
      • "id": "ftthl2r",
      • "name": "FTTH"
      },
    • "serviceCharacteristics": [
      • {
        • "name": "LINE_PROFILE",
        • "value": "1G1G"
        }
      ]
    },
  • "primaryContact": {
    • "name": "John Smith",
    • "email": "john@smith.com",
    • "phoneNumber": "01234 567890"
    },
  • "secondaryContact": {
    • "name": "John Smith",
    • "email": "john@smith.com",
    • "phoneNumber": "01234 567890"
    },
  • "appointmentReservationId": 345,
  • "requestedCompletionDate": "2022-01-10",
  • "engineerTasks": [
    • "TEST_SINGLE_DEVICE"
    ],
  • "hazards": "Hazardous materials stored on site",
  • "onSiteRestrictions": "Restricted access",
  • "notes": "Lorem ipsum dolor sit amet..."
}