Endpoint to receive an update (KCI).

post/kcis

This endpoint is called by the Fibre Cafe to send an update (KCI) to the tenant.

Each KCI will have timestamps showing when issued by the supplier and the Fibre Cafe as appropriate. The reason for the KCI will be provided along with the updated associated entity.

Securityoauth2
Request
header Parameters
X-Request-ID
required
string

Unique identifier to link request and response events across the Fibre Cafe gateway - this will change with each request

X-Conversation-ID
required
string

Identifier to track message journey across the Fibre Cafe gateway - this will match equivalent header from order creation

Request Body schema: application/json
Any of:

An update for a provide service order

Any of:

KCI update - informational, no action required.

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

Unique identifier for this update (UUID)

supplier
required
string^\w{1,20}$

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

sequenceNumber
required
number >= 1

Sequence number of this KCI to ensure ordering

issuedOn
string <date-time>

Date/time when supplier issued this update

receivedOn
string <date-time>

Date/time when Fibre Cafe received this update

deliveredOn
required
string <date-time>

Date/time when Fibre Cafe delivered this update to the tenant API

Array of objects (SupplierNote)

The supplier has added these note(s) about the order relating to this KCI

updateType
required
string (InformationalUpdateType)

The type of update - informational

Value: "INFORMATIONAL"
required
object (Information)

Represents an informational update from the supplier - these are given a reason type to aid with any process/flows on the tenant system.

entityType
required
string (ProvideOrderEntityType)

The primary entity type this KCI regards (will be supplied in entity field) - provide service order

Value: "PROVIDE_ORDER"
required
object (ProvideServiceOrder)

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

Responses
204

Operation successful - update was received and will be processed

400

Order update was rejected - request was malformed or missing mandatory parameters

401

Update was rejected - unauthorised

403

The client is not permitted to access this resource.

422

Update was rejected - request was invalid or failed validation rules

500

Unexpected system error

503

Tenant Update API is temporarily unavailable

Request samples
application/json
{
  • "entityType": "PROVIDE_ORDER",
  • "entity": {
    • "id": 123,
    • "orderType": "NEW",
    • "supplier": "DUMMY_SUPPLIER",
    • "supplierOrderNumber": "A123X",
    • "status": "PENDING_CANCELLATION",
    • "address": {
      • "id": "A00000031882",
      • "type": [
        • "UPRN",
        • "NAD",
        • "ROBT",
        • "DistrictCode"
        ],
      • "additionalIdentifiers": [
        • {
          • "id": "A00000031882",
          • "type": [
            • "UPRN",
            • "NAD",
            • "ROBT",
            • "DistrictCode"
            ]
          }
        ]
      },
    • "serviceOrderItem": {
      • "serviceSpecification": {
        • "id": "ftthl2r",
        • "name": "FTTH"
        },
      • "serviceCharacteristics": [
        • {
          • "name": "LINE_PROFILE",
          • "value": "1G_1G"
          }
        ]
      },
    • "primaryContact": {
      • "name": "John Smith",
      • "email": "john@smith.com",
      • "phoneNumber": "01234 567890"
      },
    • "secondaryContact": {
      • "name": "John Smith",
      • "email": "john@smith.com",
      • "phoneNumber": "01234 567890"
      },
    • "appointmentReservationId": 345,
    • "appointmentSupplierReference": "123456543",
    • "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...",
    • "created": "2022-01-01T09:09:33.001Z",
    • "updated": "2022-01-01T09:45:39.001Z",
    • "serviceOrderAmendment": {
      • "id": 345,
      • "orderId": 123,
      • "appointmentReservationId": 234,
      • "status": "REJECTED"
      },
    • "serviceOrderCancellation": {
      • "id": 234,
      • "orderId": 123,
      • "supplierReference": "A123X-1",
      • "reasonCode": "CUSTOMER_CHANGED_MIND",
      • "text": "Delivery too long",
      • "status": "REJECTED"
      }
    },
  • "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",
  • "supplierNotes": [
    • {
      • "note": "Lorem ipsum dolor sit amet...",
      • "type": [
        • "Engineer Note",
        • "Site Visit Note",
        • "Customer Update"
        ],
      • "created": "2022-01-01T09:09:33.001Z"
      }
    ],
  • "updateType": "INFORMATIONAL",
  • "information": {
    • "type": "CREATED",
    • "code": "NETWORK_ISSUE",
    • "text": "Resolving network issue",
    • "supplierCode": "313",
    • "supplierCodes": [
      • "313"
      ]
    }
}
Response samples
application/json
{
  • "uuid": "ae2b3f5b-9fe1-4127-a4e5-13eac457080d",
  • "code": "MALFORMED_REQUEST",
  • "messages": [
    • "Problems parsing JSON"
    ]
}