KPN Number Verify API
With KPN Number Verify, you can quickly check whether the mobile number someone provides is the same as their SIM card.
OpenAPI Specification
openapi: 3.0.0
info:
title: Number Verify - KPN
description: >-
With KPN Number Verify, you can quickly check whether the mobile number someone provides is the same as their SIM card.
**Important Notes:**
- It is advised to use **Postman** for testing this API, as it involves a redirect call. SwaggerHub does not handle redirect flows well.
- Please **download this Swagger file** and import it into your Postman client for best results.
---
**Testing the `/session` endpoint:**
- Make sure that the call is made using your mobile client or via the hostspot.
- In **Postman**, disable **automatic redirects** to ensure the `Location` header is visible in the response.
- In **cURL**, avoid using the `--location` flag. A correct example request:
```bash
curl -v GET https://api-prd.kpn.com/communication/kpn/numberverify/session/bc74adca8f761*******
```
---
## [Source view](https://app.swaggerhub.com/apis/kpn/match-kpn/)<br/>
[Documentation view](https://app.swaggerhub.com/apis-docs/kpn/match-kpn/)
---
## [KPN API Store](https://developer.kpn.com/)<br/>
[Getting Started](https://developer.kpn.com/getting-started)
---
contact:
name: API Support
email: api_developer@kpn.com
url: 'https://developer.kpn.com/support'
termsOfService: 'https://developer.kpn.com/legal'
version: 1.2.1
servers:
- url: https://api-prd.kpn.com/communication/kpn/numberverify
- description: SwaggerHub API Auto Mocking
url: https://virtserver.swaggerhub.com/kpn/NumberVerify-KPN/1.2.1
paths:
/token:
post:
summary: Token Request
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- client_id
- client_secret
- scopes
properties:
client_id:
type: string
description: Your client ID
example: your client id
client_secret:
type: string
description: Your client secret
example: your client secret
scopes:
type: string
description: |
- Scopes determine what the token can access. Valid scopes include `operator_lookup`, `device_match`, and `device_match_notify`.
- device_match_notify scope should be used for *Notification* and device_match for *Polling*.
- Choose either device_match or device_match_notify at a time
- Enter the values in a comma-separated format.
example: operator_lookup,device_match
examples:
credentials_scopes:
summary: credentials
value:
client_id: your_client_id
client_secret: your_client_secret
scope: operator_lookup,device_match
credentials_scopes_notify:
summary: credentials + correlation_id
value:
client_id: your_client_id
client_secret: your_client_secret
scope: operator_lookup,device_match_notify
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/insights/{msisdn}:
post:
summary: Insights Request
parameters:
- name: msisdn
in: path
required: true
schema:
type: string
example: '31630000001'
requestBody:
required: true
content:
application/json:
examples:
polling:
summary: Polling Example
description: Body can be empty for polling
value:
{}
notification:
summary: Notification Example
description: |
- You will need to pass the “notification_token” which is used as the “bearer” token when posting the results to “notification_uri.”
- To see the notification in the provided webhook, the session_uri must be accessed.
value:
device_match_notify:
notification_token: "abcd1234"
notification_uri: "https://your_webhook_url/"
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/InsightsResponse'
- $ref: '#/components/schemas/InsightsResponseNotify'
examples:
polling:
summary: Polling Example
value:
device_match:
session_id: "e46714d908600d8cf9f3abbf9f4056ff"
polling_id: "e46714d908600d8cf9f3abbf9f4056ff"
operator_lookup:
regionCode: "NL"
operatorName: "KPN"
mcc: null
mnc: null
notification:
summary: Notification Example
description: |
- You will need to pass the “notification_token” which is used as the “bearer” token when posting the results to “notification_uri.”
- To see the notification in the provided webhook, the session_uri must be accessed.
value:
device_match_notify:
session_uri: "http://server/v1/dm/session/5f563a0bbb61c93748f773b744bf19c6"
operator_lookup:
regionCode: "NL"
operatorName: "KPN"
mcc: null
mnc: null
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- BearerAuth: []
/session/{session_id}:
get:
summary: Session Request
description: >
Invoke the session using the session ID returned from the `/insights/{msisdn}` endpoint,
specifically under the `device_match.session_id`. This endpoint returns a `302 Found` response
with a `Location` header that the client must follow to continue the process.
parameters:
- name: session_id
in: path
required: true
description: |
The session ID extracted from the URI provided in the `/insights/{msisdn}` response.
Example: `de32343b3fe474515429d487f6989628`
schema:
type: string
example: 'de32343b3fe474515429d487f6989628'
responses:
'302':
description: Found — The session was successfully initiated.
The client must follow the `Location` header to continue.
headers:
Location:
description: URL to follow to continue the session or retrieve further information.
schema:
type: string
format: uri
example: 'https://server/v1/dm/session/next-step'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/polling/{polling_id}:
get:
summary: Polling Request
description: Retrieve the polling information using the `polling_id` provided in the header.
parameters:
- name: polling_id
in: path
required: true
description: |
- Enter the Polling Id you received in the response of `/insights/{msisdn}`, specifically located under the `device_match/polling_id` field.
schema:
type: string
example: 'e46714d908600d8cf9f3abbf9f4056ff'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PollingResponse'
examples:
polling:
summary: Polling Example
value:
msisdn: "316xxxxxxxx"
device_match: null
remote_addr: "xx.xx.x.xx"
user_agent: "Mozilla/5.0..."
errors:
- device_match: "AVAILABLE or UNAVAILABLE"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- BearerAuth: []
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
TokenRequest:
type: object
properties:
client_id:
type: string
client_secret:
type: string
scopes:
type: array
items:
type: string
description: Scopes determine what the token can access.
TokenResponse:
type: object
properties:
access_token:
type: string
example: "ewuriwerewrew"
token_type:
type: string
example: "Bearer"
expires_in:
type: integer
example: 3600
Error:
type: object
properties:
error_code:
type: integer
description: HTTP status code representing the error
example: 400
enum:
- 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
message:
type: string
description: A short description of the error
example: Bad Request
enum:
- Bad Request
- Unauthorized
- Forbidden
- Not Found
- Method Not Allowed
- Precondition Failed
- Too Many Requests
- Internal Server Error
- Bad Gateway
- Service Unavailable
InsightsRequest:
type: object
properties:
device_match_notify:
type: object
properties:
notification_token:
type: string
example: 'asf32423432'
notification_uri:
type: string
example: 'https://your-webhook-endpoint'
InsightsResponse:
type: object
properties:
device_match:
type: object
properties:
session_uri:
type: string
example: "http://server/v1/dm/session/e46714d908600d8cf9f3abbf9f4056ff"
polling_uri:
type: string
example: "https://server/v1/dm/polling/e46714d908600d8cf9f3abbf9f4056ff"
description: Polling would only work when the /token flow has device_match in scopes, and notification would work as expected only when the scopes have device_match_notify. operator_lookup works in both examples.
operator_lookup:
type: object
properties:
regionCode:
type: string
example: "NL"
operatorName:
type: string
example: "KPN"
mcc:
type: string
nullable: true
example: null
mnc:
type: string
nullable: true
example: null
InsightsResponseNotify:
type: object
properties:
device_match_notify:
type: object
properties:
session_uri:
type: string
example: "http://server/v1/dm/session/5f563a0bbb61c93748f773b744bf19c6"
description: To see the notification in the provided webhook, the session_uri must be accessed. Also, notification would work as expected only when the scopes have device_match_notify.
operator_lookup:
type: object
properties:
regionCode:
type: string
example: "NL"
operatorName:
type: string
example: "KPN"
mcc:
type: string
nullable: true
example: null
SessionResponse:
type: object
properties:
status:
type: string
example: "OK"
PollingResponse:
type: object
properties:
msisdn:
type: string
example: "31620028461"
device_match:
type: string
nullable: true
example: null
remote_addr:
type: string
example: "199.103.8.50"
user_agent:
type: string
example: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
errors:
type: array
items:
type: object
properties:
device_match:
type: string
example: "AVAILABLE"