Send an update (KCI).

post/kcis

This endpoint is called to send an update (KCI) about an inflight service provide, cease or modify order back to the tenant.

Each KCI must have a unique reference and a timestamp when issued. The reason for the KCI must also be provided along with related fields.

The KCI must contain the latest version of the related order which must be identifiable by gateway generated order ID and/or supplier order reference.

More information is available in the Developer Portal.

Securityoauth2
Request
header Parameters
X-Request-ID
required
string

Unique identifier to link request and response events across the gateway

X-Conversation-ID
string

Identifier to track message journey across the gateway

Request Body schema: application/json
One of:

Represents an KCI update to an order to provide a new service at a particular address.

id
required
string^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique identifier for this service order update (UUID)

sequenceNumber
required
number >= 1

Sequence number of this KCI to ensure ordering

issuedOn
required
string <date-time>

Date/time when supplier issued this update

reasonCode
required
string (ReasonCode)

Reason for this KCI - this must be provided:

  • CREATED : Supplier has created a new unsolicited cease
    • serviceOrder contains the new unsolicited cease order
    • serviceOrder status can be ACKNOWLEDGED or IN_PROGRESS as appropriate
  • ACKNOWLEDGED : The order has been acknowledged but not committed yet
    • serviceOrder status should be ACKNOWLEDGED
  • COMMITTED : The order has been committed
    • serviceOrder committedDate must be updated
    • serviceOrder status should be IN_PROGRESS
  • UPDATE : Supplier has updated the order
    • serviceOrder must be updated
  • INFORMATION_REQUIRED : Tenant must pass an amend order request with the specified additional information
    • problemCode can be provided
    • supplierCode can be provided if available
    • required information must be stated in text
  • DELAY : There is a problem causing a delay
    • problemCode must be provided (optionally with text description)
    • supplierCode can be provided if available
    • serviceOrder status may be updated (usually this is accompanied with a status change to HELD)
  • RESUMED : The problem has been resolved without impact on target date
    • serviceOrder status should be IN_PROGRESS
  • REAPPOINT : Tenant must reserve a new appointment and pass an amend order request with the new reservation id
    • problemCode must be provided
    • supplierCode can be provided if available
    • further information can be provided in text
  • REAPPOINTED : Supplier has arranged a new appointment with the end customer
    • serviceOrder appointmentTimeslot / appointmentSupplierReference provided
    • serviceOrder targetDate updated
  • ADDITIONAL : Supplier is flagging that new information has been provided
    • serviceOrder contains new service characteristics
  • WARNING : There is a (potential) problem that is not causing a delay yet
    • problemCode must be provided (optionally with text description)
    • supplierCode can be provided if available
  • AMENDED : Supplier has accepted and applied the requested order amendment
    • serviceOrder must be updated
    • serviceOrderAmendmentId should be provided
  • CANCELLED : Supplier has cancelled the order
    • problemCode must be provided
    • supplierCode can be provided if available
    • serviceOrderCancellationId should be provided where cancellation was requested by tenant
  • ORDER_REJECTED : The order has been rejected
    • reason must be stated in text
    • problemCode can be provided
    • supplierCode can be provided if available
  • AMENDMENT_REJECTED : Tenant has previously sent an amendment request that has been rejected
    • reason must be stated in text
    • serviceOrderAmendmentId must be provided
  • CANCELLATION_REJECTED : Tenant has previously sent a cancellation request that has been rejected
    • reason must be stated in text
    • serviceOrderCancellationId must be provided
  • COMPLETED : The order is complete
    • serviceOrder status should be COMPLETED or PARTIAL
Enum: "CREATED" "ACKNOWLEDGED" "COMMITTED" "UPDATE" "INFORMATION_REQUIRED" "DELAY" "RESUMED" "REAPPOINT" "REAPPOINTED" "ADDITIONAL" "WARNING" "AMENDED" "CANCELLED" "ORDER_REJECTED" "AMENDMENT_REJECTED" "CANCELLATION_REJECTED" "COMPLETED"
problemCode
string (ProblemCode)

Codes representing types of problems.

Enum: "ACCESS_ISSUE" "ACTIVATION_FAILED" "ADDITIONAL_WORK" "APPOINTMENT_NOT_REQUIRED" "CAPACITY_ISSUE" "COST_ISSUE" "CUSTOMER_CHANGED_MIND" "FAULT_AT_NODE" "FAULT_AT_ONT" "FAULT_AT_POP" "INFORMATION_REQUIRED" "INSTALL_FAILED" "INVALID_REQUEST" "LINKED_ORDER_ISSUE" "NETWORK_ISSUE" "NETWORK_UNAVAILABLE" "NO_LONGER_REQUIRED" "OTHER" "PLANNING_ISSUE" "PROPERTY_UNOCCUPIED" "ROUTER_NOT_AVAILABLE" "SITE_UNSAFE" "SUPPLIER_FAULT" "SURVEY_REQUIRED" "TIMED_OUT" "UNABLE_TO_ATTEND" "UNKNOWN_FAULT" "WAYLEAVE_ISSUE"
text
string [ 1 .. 1000 ] characters

Textual information about this update - e.g. reason for the delay

supplierCode
string [ 1 .. 50 ] characters

Supplier's reason or problem code - where available

Array of objects (SupplierNote)

Note(s) about the order relating to this KCI

required
object (ProvideServiceOrder)

Represents the current details of an order to provide a new service at a particular address. Orders must be identifiable via the gateway generated ID and unique supplier reference if available.

Responses
204

Operation successful - update was received and will be processed

400

KCI was rejected - request was malformed or missing mandatory parameters

401

KCI was rejected - unauthorised

403

The client is not permitted to access this resource.

422

KCI was rejected - request was invalid or failed validation rules

500

Unexpected system error

503

Fibre Gateway KCI API is temporarily unavailable

Request samples
application/json
{
  • "id": "5251cf7d-7971-42e4-a5be-c24ed58a7aa6",
  • "sequenceNumber": 1,
  • "issuedOn": "2022-01-10T09:00:00.000Z",
  • "reasonCode": "CREATED",
  • "problemCode": "NETWORK_ISSUE",
  • "text": "Resolving network issue",
  • "supplierCode": "313",
  • "supplierNotes": [
    • {
      • "note": "Lorem ipsum dolor sit amet...",
      • "type": "Engineer Note",
      • "created": "2022-01-01T09:09:33.001Z"
      }
    ],
  • "provideServiceOrder": {
    • "id": 123,
    • "orderType": "NEW",
    • "tenant": "TENANT1",
    • "supplierOrderReference": "A123X",
    • "status": "PENDING",
    • "address": {
      • "id": "200004033694",
      • "type": "UPRN"
      },
    • "serviceOrderItem": {
      • "serviceSpecification": {
        • "id": "ftthl2r",
        • "name": "FTTH"
        },
      • "serviceCharacteristics": [
        • {
          • "name": "SERVICE_VLAN_ID",
          • "value": "20"
          }
        ]
      },
    • "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",
    • "appointmentTimeslot": {
      • "timeslotStartDateTime": "2022-01-10T09:00:00.000Z",
      • "timeslotEndDateTime": "2022-01-10T13:00:00.000Z"
      },
    • "requestedCompletionDate": "2022-01-10",
    • "committedDate": "2022-01-01T09:09:33.001Z",
    • "targetDate": "2022-01-01T09:09:33.001Z",
    • "engineerTasks": [
      • "INSTALL_ROUTER"
      ],
    • "hazards": "Hazardous materials stored on site",
    • "onSiteRestrictions": "Restricted access",
    • "notes": "Lorem ipsum dolor sit amet...",
    • "serviceOrderAmendmentId": 345,
    • "serviceOrderAmendmentReference": "123-1",
    • "serviceOrderCancellationId": 345,
    • "serviceOrderCancellationReference": "123-1"
    }
}
Response samples
application/json
{
  • "uuid": "ae2b3f5b-9fe1-4127-a4e5-13eac457080d",
  • "code": "MALFORMED_REQUEST",
  • "messages": [
    • "Problems parsing JSON"
    ]
}