Endpoint to receive an update (KCI).

post/kcis

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

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

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 - this will change with each request

X-Conversation-ID
required
string

Identifier to track message journey across the 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 gateway 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 gateway received this update

deliveredOn
required
string <date-time>

Date/time when gateway 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 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"
    }
}
Response samples
application/json
{
  • "uuid": "ae2b3f5b-9fe1-4127-a4e5-13eac457080d",
  • "code": "MALFORMED_REQUEST",
  • "messages": [
    • "Problems parsing JSON"
    ]
}