Number Verify - KPN API Documentation

Overview

The Number Verify - KPN API lets you verify if the mobile number provided by a user matches their SIM card. It's perfect for applications that need to confirm mobile number validity for secure logins, fraud prevention, and identity verification.

API specification

Test the API on SwaggerHub

How to Test the Number Verify API

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 the 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.

• In Postman, disable automatic redirects to ensure the Location header is visible in the response.

• In cURL, avoid using the --location flag.

Please refer to swagger documentation for details.

Authentication

This API uses Bearer Token Authentication. To authenticate, you'll need to get an access token by calling the /token endpoint. Use this token in the Authorization header for all future requests.

Example Header

      
      
        Code copied
        
            
      
Authorization: Bearer {access_token}

How to Get an Access Token

To obtain an access token, you need to call the /token endpoint with your client credentials. The token is scoped to the operations you specify in your request.

API Endpoints

1. Token Request

Endpoint: /token

Method: POST

Description: This endpoint is used to obtain an access token that is required for authenticated requests to other endpoints.

Request Body

You need to send the request body as URL-encoded parameters:

• client_id (string): Your client ID.

• client_secret (string): Your client secret.

• scopes (comma-separated string): Defines the operations the token can access. Valid scopes include:

• operator_lookup

• device_match (for Polling)

• device_match_notify (for Notification)

Example Requests

Polling Example

      
      
        Code copied
        
            
      

curl -X POST \
'https://api-prd.kpn.com/communication/kpn/numberverify/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=your_client_id&client_secret=your_client_secret&scopes=operator_lookup,device_match'

• Description: Use this request when you need to perform polling operations.

Notification Example

      
      
        Code copied
        
            
      

curl -X POST \

'https://api-prd.kpn.com/communication/kpn/numberverify/token' \

-H 'Content-Type: application/x-www-form-urlencoded' \

-d 'client_id=your_client_id&client_secret=your_client_secret&scopes=operator_lookup,device_match_notify'

• Description: Use this request when you need to receive notifications.

Responses

• 200 OK: Returns an access token.

      
      
        Code copied
        
            
      

{
	"access_token": "ewuriwerewrew",
	"token_type": "Bearer",
	"expires_in": 3600
}

2. Insights Request

Endpoint: /insights/{msisdn}

Method: POST

Description: This endpoint allows you to request insights based on the provided mobile number (msisdn).

Path Parameters

• msisdn (string): The mobile number in E.164 format (e.g., 31630000001).

Request Body

The request body varies depending on the use case:

Polling

The request body can be empty if you are polling for results.

      
      
        Code copied
        
            
      

{}

Notification

When using notifications, the request body should include the following fields:

      
      
        Code copied
        
            
      

{
	"device_match_notify": {
	"notification_token": "abcd1234",
	"notification_uri": "https://your_webhook_url/"
	}
}

• notification_token (string): The token used as the Bearer token when posting results to notification_uri.

• notification_uri (string): The webhook URL where the notification should be sent.

Example Requests

Polling Example

      
      
        Code copied
        
            
      

{}

• Description: The request body is empty for polling.

Notification Example

      
      
        Code copied
        
            
      

{
	"device_match_notify": {
	"notification_token": "abcd1234",
	"notification_uri": "https://your_webhook_url/"
	}
}

• Description:

• The notification_token is used as the Bearer token when posting results to notification_uri.

Please note:

To receive notifications, the session_id provided in the response must be used.

Responses

• 200 OK: The insights request was successful.

Polling Example Response

      
      
        Code copied
        
            
      

{
"device_match": {
  "session_id": "IDKFA",
  "polling_id": "IDKFA"
  },
	"operator_lookup": {
  	"regionCode": "NL",
	  "operatorName": "KPN",
	  "mcc": null,
	  "mnc": null
	}
}

• Description: Polling will only work when the /token flow has device_match in scopes. operator_lookup works in both polling and notification scenarios.

Notification Example Response

      
      
        Code copied
        
            
      

{
  "device_match_notify": {
	 "session_uri": "http://server/v1/dm/session/5f563a0bbb61c93748f773b744bf19c6"
  },
	"operator_lookup": {
	 "regionCode": "NL",
	 "operatorName": "KPN",
	 "mcc": null,
	 "mnc": null
	}
}

• Description: The session_uri must be accessed to trigger the notification to the provided notification_uri.

Session Request

Endpoint: /session/{session_id}

Method: GET

Description: You can use this endpoint once you have the response from /insights/{msisdn}. This endpoint is used to initiate a session for device matching.

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.

Example Request

      
      
        Code copied
        
            
      

'https://api-prd.kpn.com/communication/kpn/numberverify/session/{session_id}'

Example Response

302 Found — Location header with the url will be returned.

The client must follow the Location header to continue.

Polling Request

Endpoint: /polling{polling_id}

Method: GET

Description: This endpoint is used to retrieve polling results using the polling_uri from the /insights response.

Example Request

      
      
        Code copied
        
            
      

'https://api-prd.kpn.com/communication/kpn/numberverify/polling/{polling_id}' \

-H 'Authorization: Bearer {access_token}'

Example Response

      
      
        Code copied
        
            
      
{

	"msisdn": "316xxxxxxxx",
	"device_match": null,
	"remote_addr": "xx.xx.xx.xx",
	"user_agent": "Mozilla...",
	"errors": [
	 {
	  "device_match": "AVAILABLE or UNAVAILABLE"
	 }
	]
}

Check responses for device match status, and take further actions based on whether you're polling or waiting for notifications.