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
Base URL
https://api-prd.kpn.com/wba
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
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. |