Encrypted Short URLs - KPN


Communicate URLs securely via SMS

Easy and user-friendly encrypted URLs

  • Security

API reference on SwaggerHub


The Encrypted Short URL API helps you safely encrypt any sensitive data that you send through SMS.

The API provides you with a KPN messaging service through which you can secure messages that contain sensitive data, e.g. a URL that contains an address, id or other personal data. The API takes the sensitive data and encrypts it into a token that is then appended to a URL. The resulting URL takes the receiver of the SMS to a page on your domain where you have implemented the decryption part of the API. This part will then decrypt the token back into the original data for further use.

Conceptual Model

Conceptual model

API workflow

API workflow


Make sure you've read Getting Started for more info on how to register your application and start trying out our APIs.

Access token: read more below under Authentication > Get Access Token for more information on how to obtain an access token.

Landing URL: you should have a URL where the receiver of your SMS goes to to decrypt the token. In other words, this is where the decryption part of the API should be implemented.

URL shortener key: if you want to use your own key, you have to obtain one from from



As of now the Encrypted Short URL API only supports SMS as a messaging channel.

The API does not support bulk SMS messages.

The max number of characters allowed per SMS is 800.

The identifier to encrypt allows up to 150 characters.

Country restriction

With this API, messages can only be send to mobile phones registered in the Netherlands. So the country code is locked to 31.

Mobile phone number

The mobile phone number should be formatted as follows:

  • Dutch mobile phone number: 0612345678 or 0031612345678 (00 + Dutch country code 31 + phone number)

Landing URL

The landing URL should be less than 300 characters.

Expiry timestamp

The expiry timestamp should conform to the ISO 8601 format with the complete date plus hours, minutes and seconds (YYYY-MM-DDTHH-MM-SS). The timezone should be UTC+0. Example: 2019-12-11T23:59:59.

URL shortener key

The URL shortener key field allows for a maximum of 100 characters.

When using your own key, the key should be obtained from

Getting started


To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:


Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

curl -X POST \
 '' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

If you are using cURL for Windows, please use the command below instead.

curl -X POST "" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authentication service returns a JSON message that contains the access token field.

    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    "organization_name": "kpn",
    "developer_email": "",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"


  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.


When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

How to...

Encrypt a URL

Send an encrypted token with url to a mobile phone number.
Note: Keep in mind that messages can only be send to Dutch mobile phones (country code +31).

Example request body:

  "message": {
    "mobile_number": "06xxxxxxxx",
    "content": "Please click here: {url}"
  "url_details": {
    "identifier": "id=12345678",
    "landing_url": "",
    "expiry_timestamp": "2019-12-11T23:59:59",
    "url_shortener_key": "",
    "sender": "KPN"

Example response:

    "document_id": "3ad86db3-6d26-45cf-9002-fe1cd8940b9e",
    "status": "OK"

Decrypt a URL

Decrypt a given encrypted token value.

Example encrypted token:

curl -X GET ".../decrypt?token={encrypted_token_value}" -H "accept: application/json"

Example response:

    "identifier": "id=12345678"

Return codes

Code   Meaning
200   Success
201   Created
202   Accepted
400   Bad request
401   Unauthorized
404   Not Found
405   Method not Allowed
412   Precondition failed
429   Too many requests
500   Internal server error
502   Bad gateway
503   Service unavailable