KPN Wholesale Wholesale Broadband Access API

Introduction

KPN Wholesale Broadband Access (WBA) is a KPN Wholesale product offering copper and fiber access to wholesale customers. WBA has the following APIs available:

  • Functional Product Information API.

  • Carrier Information Product API.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/wba


Conceptual Model

Conceptual model


Prerequisites

The Wholesale Broadband Access API is available to KPN Wholesale customers only.


Definitions

FPI

Functional Product Information. This is the name of one of WBA's APIs.

CIP

Carrier Information Product. This is the name of one of WBA's APIs.

ISRA

Infrastructuur Randapparatuur, which is Dutch for demarcation point. This is is the point at which the public switched telephone network ends and connects with the customer's on-premises wiring.

MDF

Main Distribution Frame. This terminates the cables leading to subscribers on the one hand, and cables leading to active equipment (such as DSLAMs and telephone switches) on the other in the local telephone exchange.

SDF

Subloop Distribution Frame. This terminates the cables leading to subscribers on the one hand, and fiber connections to active equipment (such as DSLAMs and telephone switches) on the other in a local street cabinet.

WSO

Wholesale Organization.


API workflow

Workflow diagram


Constraints

  • FPI limitations: For the FPI API, a maximum of 1.000 API calls per day applies.

  • CIP limitations: For the CIP API, a maximum of 100 API calls per day applies.


Functional Product Information API

Note: This API is in line with WBA FPI v26.

The Functional Product Information (FPI) service is used to provide Wholesale Broadband Access (WBA) information for new and existing WBA connections. FPI provides carrier vendor information and WBA technology availability, with actual up and down bit rates with a reliability per technology type.

The reliability is defined as the probability that the bit rate can be achieved and is only applicable for WBA connections on copper lines. The provided reliability in FPI is within 50% to 100%. The reliability for fiber WBA connections is always 100%. It is allowed to request different reliability per copper technology type.

An address is mandatory in the FPI request. For an existing WBA broadband connection, the WSO specifies the xdf-access-serviceid, provided by KPN when the connection was delivered. The xdf-access-serviceid is the unique identifier for the current access connection. The bit rates up/down are determined by measurement on the broadband connection of the xdf-access-serviceid.

An address can have one or more carrier vendors. FPI provides information for the following carrier vendors:

  • MDF: WBA services on copper lines from central office (MDF).
  • SDF: WBA services on copper lines from street cabinet (SDF).
  • REGG: WBA Fiber to the Home (FttH) services from Reggefiber.
  • KPNFO: WBA Fiber to the Office (FttO) services form KPNFO.


Carrier Information Product API

Note: This API is in line with WBA CIP v46.

The Carrier Information Product (CIP) API provides information about the infrastructure and active services on the physical connection of a customers address. For physical carrier copper, the ISRA with the current and future connection details of all copper lines are shown. For the physical carrier fiber, all fiber-termination points are shown, including current and future connection details.

To support WSO’s clean order process, a list of house number extensions per carrier-vendor will be provided when a house number extension is wrong or missing and there are no other identifiers (i.a. phonenumber or xdf-access-service-id) specified for the connection.

The CIP can be used for several scenarios:

  • For an address connected to physical carrier copper. The user creates a CIP request for physical carrier copper and the connection details for the copper connection will be shown.
  • For an address connected to physical carrier fiber. The user creates a CIP request for physical carrier fiber and the connection details for the fiber connection will be shown.
  • For an address connected to both copper and fiber. The user creates a CIP request without specifying the physical carrier (empty field) and the connection details for both copper and fiber connections will be shown.

When the user requests information for a copper carrier, an optional phonenumber, xdf-service-id or a connectionpointnumber can be provided. The CIP provides current and future types of services on all copper lines of the ISRA-connection point.

Please note that there may be more than one ISRA-connection point on the customer’s address:

  • In case one or two ISRA-connection points exist, all connection details of those ISRA’s will be shown.
  • If more than two ISRA-connection points exist, the list of ISRA’s is shown without connection details and error code 642 will be returned.

When the user requests information for a fiber carrier, an optional fiber-terminationpoint-id can be provided. The CIP provides current and future types of services on the specified fiber-terminationpoint-id. If no fiber-termination point was specified, the CIP provides current and future types of services on all fiber-termination points.


Getting started

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.


How to...

Retrieve Functional Product Information

The following endpoint retrieves the Functional Product Information:

GET ​/fpi/addresses


Request

The API request should be of this form:

/fpi/addresses?{query-parameters}


^^Request example^^
/fpi/addresses?requested-zipcode=1234AB&requested-housenumber=118


Mandatory parameters are:

  • requested-zipcode
  • requested-housenumber

For more parameter options, go to the API specification of the API on SwaggerHub.


Response

The expected response contains a variety of information objects:

Object Description
enduserinfo This object has the address details with xdf-access-serviceid, connectionpointnumber and fiber-terminationpoint-id as provided in the FPI request. The fields requested-housenumber and requested-zipcode are mandatory, the other fields are optional.
actualuserinfo This object is copied from the user-provided address (requested address). This object is not filled when an error is returned.
carriervendor This object contains carrier vendor information (MDF, SDF, REGG or KPNFO) for the requested address.
technologyavailability The technologyavailability array can have multiple occurrences. The available technology-types, bitrates with reliability are shown.
errorinfo This object includes a list of comment- and error codes. Information about these comment- and error codes can be found in the document WBA Fulfillment Error Comment Code List, which is provided to every KPN Wholesale Broadband Access customer.


Retrieve Carrier Information Product

The following endpoint retrieves the Carrier Information Product:

GET ​/cip/addresses


Request

The API request should be of this form:

/cip/addresses?{query-parameters}


^^Request example^^
/cip/addresses?requested-zipcode=1234AB&requested-housenumber=118


Mandatory parameters are:

  • requested-zipcode
  • requested-housenumber

For more parameter options, go to the API specification of the API on SwaggerHub.


Response

The expected response contains a variety of information objects:

Object Description
enduserinfo The requested elements are echoed from the input. The optional field requested-phonenumber is included, since this may be a different phonenumber (i.e. an ISDN-2 subnumber) than the main-phonenumber.
planneduserinfo The planned user-info is the customer address from the installed base. The parameters zipcode and housenumber may be corrected in case a phonenumber or xdf-access-serviceid was specified in the request.
carriervendor The optional carriervendor object is used when the requested housenumber-extension does not exist and there is no other identifier ( phonenumber or xdf-access-serviceid) in the request to identify the connection. All known addresses per carrier-vendor or physical-carrier will be provided, including carrier-status (Open, Closed, or Planned) and planned-nl-type for fiber. The error code 251 is returned in case the requested zipcode and housenumber exists, but the requested housenumber extension is missing or incorrect. The list of known housenumber extensions on the requested addresses is provided for each carrier-vendor (MDF, SDF, REGG, non-network). The WSO can choose a valid housenumber extension from the list. The error code 202 will be returned in case the requested zipcode and housenumber is unknown.
copperinfo This object is present in the response for physical-carrier copper and will be returned when the requested address has copper connections.
fiberinfo This object is present in the message for physical-carrier fiber.
errorinfo This object includes a list of comment- and error codes. Information about these comment- and error codes can be found in the document WBA Fulfillment Error Comment Code List, which is provided to every KPN Wholesale Broadband Access customer.


Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.

Mopinion feedback