Create an order to provide, cease or modify a service.

This endpoint is called to place an order with the supplier to provision a new service or cease/modify an existing service.

The supplier should validate the order request and accept the order if the validation is successful or otherwise reject the order. If the order is rejected, a 422 code should be returned with reason(s) for the rejection in the response.

If the order is accepted, the supplier may return a 202 accepted response without acknowledging the order if further validation/processing is required. In this scenario, the supplier must then send an order update (KCI) to later acknowledge the order and provide the order number.

Alternatively, the supplier can synchronously acknowledge the order by returning a 201 created response with the returned order containing the supplier order number and status of ACKNOWLEDGED. The order can also be committed at this stage by returning the order status of IN_PROGRESS.

SecuritybearerAuth
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

Tenant
required
string

The tenant that has placed the request on the gateway

Example: TENANT1
Request Body schema: application/json
One of:

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

id
required
number >= 1

Unique id identifying this service order - generated by gateway

orderType
required
string (ProvideOrderType)

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

Enum: "NEW" "START" "TAKEOVER" "TRANSFER"
tenant
required
string [ 1 .. 50 ] characters

The tenant that has placed the order on the gateway

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)

appointmentReservationReference
string [ 1 .. 50 ] characters

Unique reference identifying the appointment - supplier reference (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(s) will be installed

onSiteRestrictions
string [ 1 .. 1000 ] characters

Information about restrictions on the site where the service(s) 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 acknowledged - returned order should contain the supplier order number and appropriate status

202

Order was accepted 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

Invalid or failed response from the supplier

503

Supplier API is temporarily unavailable

post/service-orders
Request samples
application/json
{
  • "id": 123,
  • "orderType": "NEW",
  • "tenant": "TENANT1",
  • "address": {
    • "id": "200004033694",
    • "type": "UPRN"
    },
  • "serviceOrderItem": {
    • "serviceSpecification": {
      • "id": "ftthl2r"
      },
    • "serviceCharacteristics": [
      • {
        • "name": "ENNI_ID",
        • "value": "1"
        }
      ]
    },
  • "primaryContact": {
    • "name": "John Smith",
    • "email": "john@smith.com",
    • "phoneNumber": "01234 567890"
    },
  • "secondaryContact": {
    • "name": "John Smith",
    • "email": "john@smith.com",
    • "phoneNumber": "01234 567890"
    },
  • "appointmentReservationId": 234,
  • "appointmentReservationReference": "A234X",
  • "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
{
  • "status": "PENDING_CANCELLATION",
  • "supplierReference": "A123X",
  • "committedDate": "2022-01-01T09:09:33.001Z",
  • "targetDate": "2022-01-01T09:09:33.001Z",
  • "id": 123,
  • "orderType": "NEW",
  • "tenant": "TENANT1",
  • "address": {
    • "id": "200004033694",
    • "type": "UPRN"
    },
  • "serviceOrderItem": {
    • "serviceSpecification": {
      • "id": "ftthl2r",
      • "name": "FTTH"
      },
    • "serviceCharacteristics": [
      • {
        • "name": "ENNI_ID",
        • "value": "1"
        }
      ]
    },
  • "primaryContact": {
    • "name": "John Smith",
    • "email": "john@smith.com",
    • "phoneNumber": "01234 567890"
    },
  • "secondaryContact": {
    • "name": "John Smith",
    • "email": "john@smith.com",
    • "phoneNumber": "01234 567890"
    },
  • "appointmentReservationId": 234,
  • "appointmentReservationReference": "A234X",
  • "requestedCompletionDate": "2022-01-10",
  • "engineerTasks": [
    • "TEST_SINGLE_DEVICE"
    ],
  • "hazards": "Hazardous materials stored on site",
  • "onSiteRestrictions": "Restricted access",
  • "notes": "Lorem ipsum dolor sit amet..."
}