KPN Wholesale Wholesale Broadband Access API

  • beta

Introduction

KPN Wholesale Broadband Access (WBA) is a KPN Wholesale product offering copper and fiber access to wholesale customers. There are 2 WBA APIs:

  • 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


Requirements

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

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

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

Make sure you've read What's in it for you for more info on how to register and start testing APIs.

Authentication

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.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a website tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting code from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback