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:
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 along with the latest updated entity (serviceOrder, serviceProblem, serviceTest, reportableIncident).

  • CREATED : Supplier has created a new entity e.g. unsolicited cease or reportable incident
    • new serviceOrder containing the unsolicited cease order (as applicable)
    • status can be ACKNOWLEDGED or IN_PROGRESS as appropriate for unsolicited cease
    • new reportableIncident with appropriate status (as applicable)
  • ACKNOWLEDGED : Acknowledge receipt without committing
    • entity status should be ACKNOWLEDGED
  • COMMITTED : Commit to fulfilment
    • serviceOrder committedDate must be updated (as applicable)
    • entity status should be IN_PROGRESS
  • UPDATE : A general update
    • entity must be updated
  • INFORMATION_REQUIRED : Tenant must pass an amend 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
    • entity status may be updated (usually this is accompanied with a status change to HELD)
  • RESUBMIT : Tenant must resubmit the request
  • RESUMED : The problem has been resolved without impact on target date
    • entity status should be IN_PROGRESS
  • REAPPOINT : Tenant must reserve a new appointment and pass an amend 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
    • entity appointmentTimeslot / appointmentSupplierReference provided
    • serviceOrder targetDate updated (as applicable)
  • RESOLVED : The request is resolved
    • entity status should be RESOLVED.
  • ADDITIONAL : Supplier is flagging that new information has been provided
    • entity contains new service characteristics or additional information
  • 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 amendment
    • serviceOrder or serviceProblem must be updated
    • serviceOrderAmendmentId or serviceProblemAmendmentId should be provided
  • CANCELLED : Supplier has cancelled the order or service problem
    • problemCode must be provided
    • supplierCode can be provided if available
    • serviceOrderCancellationId or serviceProblemCancellationId 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
  • REJECTED : The service test or problem request 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 or serviceProblemAmendmentId must be provided
  • CANCELLATION_REJECTED : Tenant has previously sent a cancellation request that has been rejected
    • reason must be stated in text
    • serviceOrderCancellationId or serviceProblemCancellationId must be provided
  • FAILED : The request has failed to complete successfully
    • problemCode must be provided
    • supplierCode can be provided if available
    • entity status should be FAILED
  • COMPLETED : The request is complete
    • entity status should be COMPLETED or PARTIAL
Enum: "CREATED" "ACKNOWLEDGED" "COMMITTED" "UPDATE" "INFORMATION_REQUIRED" "DELAY" "RESUBMIT" "RESUMED" "REAPPOINT" "REAPPOINTED" "RESOLVED" "ADDITIONAL" "WARNING" "AMENDED" "CANCELLED" "ORDER_REJECTED" "REJECTED" "AMENDMENT_REJECTED" "CANCELLATION_REJECTED" "FAILED" "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" "PARTIAL_INSTALL" "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
Deprecated

Supplier's reason or problem code - deprecated: replaced by supplierCodes array to allow for multiple underlying supplier codes

supplierCodes
Array of strings

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",
  • "supplierCodes": [
    • "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": [
      • "TEST_SINGLE_DEVICE"
      ],
    • "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"
    ]
}