Skip to content
/Appointments

CityFibre - Ticketing API

Introduction

This documentation provides information on the Ticketing API and how to access it.

Please note:

  • Ticket requests for multiple ServiceID’s at the same time is not currently catered for.

  • When Tickets are raised, they will then be handled by CityFibre, and updates will be provided to a previously configured endpoint provided by the Ticket Reporter.

  • In this document, we use Buyer and Supplier for the Service Provider / CityFibre respectively and Reporter as the person within the Buyers Organisation.

  • This document describes the messages which can pass between Buyer and Supplier, and the various status changes and updates for ticket requests throughout the process.

  • We recommend that you always perform the Supplier Service Diagnostic request before you raise a Ticket, this will ensure the Buyer is not charged for faults on their own network. You can find the Service Diagnostics API document here.

Design Overview

See diagram Ticketing_API_v1.1 for an overview of the flow.

Ticketing API v1.1
Ticketing API v1.1

  1. The Buyer detects or is informed of a problem on the network. Reporter gathers any relevant information. The fault is then determined to be within Suppliers network.

  2. The Reporter on the Buyer side can call the API addFaultReport which will validate the details and the ServiceID, once the issue is confirmed a Ticket is raised automatically and then progresses through the workflow until it is resolved.

  3. The Reporter on the Buyer side initiates the process by calling the ticketing API (addFaultReport) to raise a ticket with the Supplier. This ticket should include all relevant information that could be gathered at the time and can include the details for the files to upload.

    a. The ticketing API responds with the message ID and status “Pending”.

    b. The ticketing API may also respond with a status “Rejected” if the ticket is missing mandatory information or the Service ID is not valid.

    c. The ticketing API may also respond with a status “Rejected” if the fault detail type is "Service Outage" (TLOS: Total Loss Of Service) without an Appointment Reservation Key or any other types (Non-TLOS) with an Appointment Reservation Key.

  4. The Supplier stores the ticket information.

  5. Once validated and stored, a notification is sent to the Buyer saying that the ticket status is “Accepted” and has been successfully created. This notification also includes the maintainerFaultReference, which is used along with the buyerFaultReference to identify the ongoing fault. Please note the change from ‘Pending’ to ‘Accepted’ is almost instant if no issues are identified.

  6. At this point the Suppliers Triage is performed on the Service and the fault details are confirmed to the Buyer in the Triage section of the XML using the NotifyFaultReportUpdate. If a fault is found on the Suppliers network, it continues in the Workflow.

  7. When there is more information available, the Supplier can add this information to the ticket. A notification will be sent to the Buyer’s notification endpoint containing a full update using the notifyFaultReportUpdate API.

  8. If the Reporter finds more information, they too can add it using the amendFaultReport API. The Buyer will get a confirmation message for each amendment received by the Supplier.

  9. The Supplier continues to update the Buyer with ticket progress until resolved.

  10. When the ticket is deemed resolved, Supplier will update the ticket status to “Resolved”.

  11. The Buyer should respond with a resolveResponse either accepting or rejecting the solution. If the resolution is rejected, the ticket will be re-opened with status “Re-Opened”.

  12. Once confirmed ‘Resolved’ the ticket can be closed.

  13. If no reply is received from the Buyer after a fault is resolved for 48 hours, then the fault status is changed to ‘Closed’ and it is automatically Accepted from the Suppliers standpoint.

Contacting the Customer

If the Supplier needs more information from either the Buyer or the Buyer’s End User the Ticket is put into an ‘on-hold’ status that will pause the SLA. The reasons for pausing are only when delays are out of the Suppliers hands.

To contact the Buyer’s End User, the Suppliers NOC (Network Operational Centre) team makes the appointment, they would call the Customer and make arrangements if a site visit is needed. They follow the process of leaving a message if possible and a further two call attempts. Once the information is received or the appointment is booked the SLA can be aligned to start again and the Ticket status will be moved back to ‘In Progress’.

Accessing the API

The API is accessed via HTTPS. Calls are made by POST, sending XML as the HTTP body.

Messages are exchanged using SOAP exchanges over HTTPS POST, where the request is in the POST body and the response is in the HTTP response body. Messages are encapsulated in a SOAP envelope using Document/Literal style following WS-Basic Profile 1.0.

        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
            <soap:Body>
                 ... single request or response element goes here ...
            </soap:Body>
        </soap:Envelope>

Authentication

Authentication is by means of HTTPS client certificate. It is also restricted to pre-agreed source IP addresses.

Integration Environments

CityFibre provides two pre-production environments for the Buyer to integrate with, to allow the Buyer to test the API endpoint before going live.

Below are the details for these environments:

CFSIT: https://api-gw.cityfibre.com:41223/cfsit/api2

CFStaging: https://api-gw.cityfibre.com:41223/cfstaging/api2

Production: https://api-gw.cityfibre.com:41223/prod/api2

Ticketing Notification End Point

Buyer must provide the endpoint to receive Ticket update notifications.

Closure Code Reference

CodeDescription
FRFault Resolved
FNRFault Not Resolved
HAZSite Unsafe
NANo access
NAPUVNo Access Possible Hazard
ASQSales Query
NDTNo dial tone
UNFUnforeseen Circumstance e.g. Asbestos
MBORCMatters Beyond Reasonable Control
FTAFailed to Attend
SREQService Request
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://www.cityfibre.com
API Development Team
apiteam@cityfibre.com
License
Apache 2.0
Terms of Service
Languages
Servers
Mock server
https://ticketing.docs.cityfibre.com/_mock/openapi
Main (production) server
https://api-gw.cityfibre.com:41223/prod/api2
CFStaging server
https://api-gw.cityfibre.com:41223/cfstaging/api2
CFSit server
https://api-gw.cityfibre.com:41223/cfsit/api2

Appointments

The buyer can query appointment availability, reserve an appointment and include the reservation key in the order request. If this is not done, the order will go into a waiting state and not progress, the buyer will need to reserve an appointment and then amend the order to include the appointment reservation key before the order can complete. Reappoint is an additional query and reserve, then an amend with the new CAMS ID on the appointment reservation key field.

Operations

Appointing flow

Where the ticketing flow says "get appointment info" this flow describes all the appointment related steps.

AppointingDiagram
AppointingDiagram

Query Appointment Availability

Request

To check the availability for an appointment on a given location, timeframe, and product, the buyer should send a request containing a UPRN.

The seller is then going to respond with detailed information about available appointment slots.

Security
Certificate
Bodyapplication/xml
messageobject(message)required

The meta-data of the request. It includes information regarding the message UUID, transaction ID and the sent timestamp

messageIdstring<= 36 charactersrequired

A unique ID to identify the message

Example: "b68b2cf4-475e-11e1-a92e-fb2ff6467c99"
correlationIdstring<= 36 charactersrequired

A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and messages that allow reference to a particular transaction or event chain

Example: "bac72cfa-475e-11e1-a92e-fb2ff6467c99"
sentAtstring(date-time)required

The timestamp when the message has been sent

Example: "2012-01-20T18:30:43Z"
buyerobject(buyer)required

The Service Provider who consumes the service is the buyer

buyerIdentifierstring<= 36 charactersrequired

Unique identifier of the buyer

Example: "SPDEV1"
cfh:resellerIdstring<= 36 characters

Unique identifier of the reseller. Sourced from the Ofcom Reseller Identification List

Example: "BAQ"
sellerobject(seller)required

The Active Network Operator who provides the service is the seller

sellerIdentifierstring<= 36 charactersrequired

Unique identifier of the seller

Example: "CITYFIBRE"
addressKeystring(addressKey)<= 63 charactersrequired

Unique identifier of the address (UPRN)

appointmentsFromstring(date)<= 10 charactersrequired

Appointments in the future from this date

Example: "2017-10-18"
appointmentTypeOrder (object) or Fault (object)(appointmentType)required
One of:
ordernull
cfh:productNamestring<= 254 charactersrequired

Name of the Product

Example: "ftthl2r"
cfh:reappointmentstring

Indicates whether the appointment is reappointing a previous appointment

Example: "true"
cfh:projectReferencestring<= 80 characters
Example: "CST1234567"
application/xml
<queryAppointmentAvailabilityRequest xmlns="http://www.niccstandards.org.uk/ala_1.0.xsd" xmlns:cfh="http://www.cityfibre.com/ala/ext1">
  <message>
    <messageId>b68b2cf4-475e-11e1-a92e-fb2ff6467c99</messageId>
    <correlationId>bac72cfa-475e-11e1-a92e-fb2ff6467c99</correlationId>
    <sentAt>2012-01-20T18:30:43Z</sentAt>
  </message>
  <buyer>
    <buyerIdentifier>SPDEV1</buyerIdentifier>
  </buyer>
  <seller>
    <sellerIdentifier>CITYFIBRE</sellerIdentifier>
  </seller>
  <addressKey>10002491172</addressKey>
  <appointmentsFrom>2017-10-18</appointmentsFrom>
  <appointmentType>
    <fault/>
  </appointmentType>
  <cfh:productName>ftthl2r</cfh:productName>
  <cfh:reappointment>false</cfh:reappointment>
</queryAppointmentAvailabilityRequest>

Responses

Appointment Availability Response

Bodyapplication/xml
One of:
messageobject(message)required

The meta-data of the request. It includes information regarding the message UUID, transaction ID and the sent timestamp

messageIdstring<= 36 charactersrequired

A unique ID to identify the message

Example: "b68b2cf4-475e-11e1-a92e-fb2ff6467c99"
correlationIdstring<= 36 charactersrequired

A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and messages that allow reference to a particular transaction or event chain

Example: "bac72cfa-475e-11e1-a92e-fb2ff6467c99"
sentAtstring(date-time)required

The timestamp when the message has been sent

Example: "2012-01-20T18:30:43Z"
buyerobject(buyer)required

The Service Provider who consumes the service is the buyer

buyerIdentifierstring<= 36 charactersrequired

Unique identifier of the buyer

Example: "SPDEV1"
cfh:resellerIdstring<= 36 characters

Unique identifier of the reseller. Sourced from the Ofcom Reseller Identification List

Example: "BAQ"
sellerobject(seller)required

The Active Network Operator who provides the service is the seller

sellerIdentifierstring<= 36 charactersrequired

Unique identifier of the seller

Example: "CITYFIBRE"
queryAppointmentAvailabilityAcceptedobject(queryAppointmentAvailabilityAccepted)required
appointmentSlotsArray of objectsrequired
appointmentSlotobject(appointmentSlot)

Represents the appointment slot details (date, start time, end time)

Response
application/xml
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <queryAppointmentAvailabilityResponse xmlns="http://www.niccstandards.org.uk/ala_1.0.xsd" xmlns:cfh="http://www.cityfibre.com/ala/ext1">
      <message>
        <messageId>bf1efe1f-f5fc-47e7-9d53-d2b16529aa4c</messageId>
        <correlationId>bac72cfa-475e-11e1-a92e-fb2ff6467c99</correlationId>
        <sentAt>2022-05-18T11:23:07.710Z</sentAt>
      </message>
      <buyer>
        <buyerIdentifier>SPDEV1</buyerIdentifier>
      </buyer>
      <seller>
        <sellerIdentifier>CITYFIBRE</sellerIdentifier>
      </seller>
      <queryAppointmentAvailabilityAccepted>
        <appointmentSlots></appointmentSlots>
      </queryAppointmentAvailabilityAccepted>
    </queryAppointmentAvailabilityResponse>
  </soap:Body>
</soap:Envelope>

Reserve Appointment

Request

In order to reserve an appointment, the buyer should provide the UPRN, product and the appointment slot that they desire to the seller.

Security
Certificate
Bodyapplication/xml
messageobject(message)required

The meta-data of the request. It includes information regarding the message UUID, transaction ID and the sent timestamp

messageIdstring<= 36 charactersrequired

A unique ID to identify the message

Example: "b68b2cf4-475e-11e1-a92e-fb2ff6467c99"
correlationIdstring<= 36 charactersrequired

A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and messages that allow reference to a particular transaction or event chain

Example: "bac72cfa-475e-11e1-a92e-fb2ff6467c99"
sentAtstring(date-time)required

The timestamp when the message has been sent

Example: "2012-01-20T18:30:43Z"
buyerobject(buyer)required

The Service Provider who consumes the service is the buyer

buyerIdentifierstring<= 36 charactersrequired

Unique identifier of the buyer

Example: "SPDEV1"
cfh:resellerIdstring<= 36 characters

Unique identifier of the reseller. Sourced from the Ofcom Reseller Identification List

Example: "BAQ"
sellerobject(seller)required

The Active Network Operator who provides the service is the seller

sellerIdentifierstring<= 36 charactersrequired

Unique identifier of the seller

Example: "CITYFIBRE"
appointmentSlotobject(appointmentSlot)required

Represents the appointment slot details (date, start time, end time)

appointmentDatestring(appointmentDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}.*$required

Date of the appointment

appointmentStartTimestring(appointmentStartTime)<= 5 charactersrequired

Appointment start time

appointmentEndTimestring(appointmentEndTime)<= 5 charactersrequired

Appointment end time

appointmentTypeOrder (object) or Fault (object)(appointmentType)required
One of:
ordernull
cfh:productNamestring<= 254 charactersrequired

This is the product name

Example: "ftthl2r"
cfh:addressKeystring<= 254 charactersrequired

The address key (UPRN)

Example: "123456789012"
cfh:reappointmentstring

Indicates whether the appointment is reappointing a previous appointment

Example: "true"
cfh:projectReferencestring<= 80 characters
Example: "CST1234567"
application/xml
<reserveAppointmentRequest xmlns="http://www.niccstandards.org.uk/ala_1.0.xsd" xmlns:cfh="http://www.cityfibre.com/ala/ext1">
  <message>
    <messageId>b68b2cf4-475e-11e1-a92e-fb2ff6467c99</messageId>
    <correlationId>bac72cfa-475e-11e1-a92e-fb2ff6467c99</correlationId>
    <sentAt>2012-01-20T18:30:43Z</sentAt>
  </message>
  <buyer>
    <buyerIdentifier>SPDEV1</buyerIdentifier>
  </buyer>
  <seller>
    <sellerIdentifier>CITYFIBRE</sellerIdentifier>
  </seller>
  <appointmentSlot>
    <appointmentDate>2012-01-20</appointmentDate>
    <appointmentStartTime>08:00</appointmentStartTime>
    <appointmentEndTime>13:00</appointmentEndTime>
  </appointmentSlot>
  <appointmentType>
    <fault/>
  </appointmentType>
  <cfh:productName>ftthl2r</cfh:productName>
  <cfh:addressKey>123456789012</cfh:addressKey>
  <cfh:reappointment>false</cfh:reappointment>
</reserveAppointmentRequest>

Responses

Reserve Appointment Response

Bodyapplication/xml
One of:
messageobject(message)required

The meta-data of the request. It includes information regarding the message UUID, transaction ID and the sent timestamp

messageIdstring<= 36 charactersrequired

A unique ID to identify the message

Example: "b68b2cf4-475e-11e1-a92e-fb2ff6467c99"
correlationIdstring<= 36 charactersrequired

A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and messages that allow reference to a particular transaction or event chain

Example: "bac72cfa-475e-11e1-a92e-fb2ff6467c99"
sentAtstring(date-time)required

The timestamp when the message has been sent

Example: "2012-01-20T18:30:43Z"
buyerobject(buyer)required

The Service Provider who consumes the service is the buyer

buyerIdentifierstring<= 36 charactersrequired

Unique identifier of the buyer

Example: "SPDEV1"
cfh:resellerIdstring<= 36 characters

Unique identifier of the reseller. Sourced from the Ofcom Reseller Identification List

Example: "BAQ"
sellerobject(seller)required

The Active Network Operator who provides the service is the seller

sellerIdentifierstring<= 36 charactersrequired

Unique identifier of the seller

Example: "CITYFIBRE"
reserveAppointmentAcceptedobject(reserveAppointmentAccepted)required
appointmentobject(appointmentAccepted)required
appointmentDatestring(appointmentDate)^[0-9]{4}-[0-9]{2}-[0-9]{2}.*$

Date of the appointment

appointmentStartTimestring(appointmentStartTime)<= 5 characters

Appointment start time

appointmentEndTimestring(appointmentEndTime)<= 5 characters

Appointment end time

appointmentReservationKeystring(appointmentReservationKey)<= 36 charactersrequired

The unique key for appointment reservation

appointmentReservationValidUntilstring(date-time)

Reservation until date

Example: "2012-01-20T18:30:43Z"
Response
application/xml
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <reserveAppointmentResponse xmlns="http://www.niccstandards.org.uk/ala_1.0.xsd" xmlns:cfh="http://www.cityfibre.com/ala/ext1">
      <message>
        <messageId>c6d0b303-625a-4ee3-ab53-5e616d728755</messageId>
        <correlationId>bac72cfa-475e-11e1-a92e-fb2ff6467c99</correlationId>
        <sentAt>2022-05-20T09:58:23.439Z</sentAt>
      </message>
      <buyer>
        <buyerIdentifier>SPDEV1</buyerIdentifier>
      </buyer>
      <seller>
        <sellerIdentifier>CITYFIBRE</sellerIdentifier>
      </seller>
      <reserveAppointmentAccepted>
        <appointment>
          <appointmentDate>2022-05-24</appointmentDate>
          <appointmentStartTime>08:00</appointmentStartTime>
          <appointmentEndTime>13:00</appointmentEndTime>
          <appointmentReservationKey>EI7PBRU6TL8KN1YNGO8ICEUI0UDFE9M8</appointmentReservationKey>
          <appointmentReservationValidUntil>2022-05-20T21:58:26.822Z</appointmentReservationValidUntil>
        </appointment>
      </reserveAppointmentAccepted>
    </reserveAppointmentResponse>
  </soap:Body>
</soap:Envelope>

Fault Report

Operations

Resolve Response

Operations

Request Update

Operations

FaultReport

Webhooks

Appointment

Webhooks

Amendment

Webhooks

XSD File

Operations

Revision History

Operations