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

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_uri provided in the response must be accessed.

Responses

• 200 OK: The insights request was successful.

Polling Example Response

      
      
        Code copied
        
            
      

{

"device_match": {

"session_uri": "http://server/v1/dm/session/e46714d908600d8cf9f3abbf9f4056ff",

"polling_uri": "https://server/v1/dm/polling/e46714d908600d8cf9f3abbf9f4056ff"

},

	"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

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.

Request Header

• session_uri (string): The URI you received in the response of /insights/{msisdn}, found under the device_match/session_uri field.

Example Request

      
      
        Code copied
        
            
      

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

-H 'session_uri: https://server/v1/dm/session/your_session_id' \

-H 'Authorization: Bearer {access_token}'

Example Response

      
      
        Code copied
        
            
      
{

	"status": "OK"

}

Polling Request

Endpoint: /polling

Method: GET

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

Request Header

• polling_uri (string): The URI you received under the device_match/polling_uri field from the /insights/{msisdn} response.

Example Request

      
      
        Code copied
        
            
      

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

-H 'polling_uri: https://server/v1/dm/polling/your_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.