KPN Encrypted Short URL API


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.



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.

Shortened URLs

All the shortened URLs will have the following domain "". Example:

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 sent to Dutch mobile phones (country code +31).

The payload uses following parameters:

Parameter Description
content Put your message here. Add the resulting URL to the message.
mobile_number The mobile phone number of the addressee. Use the country code +31 at the start.
identifier The data that is to be encrypted (e.g. personal data). This information will be encrypted into a token that is appended to the landing_url. The identifier can also be in the form of a URL if that URL for example contains potentially hackable data. This field is optional. If no identifier is provided, no encryption will take place and the message will be sent through as is.
landing_url The URL to which the encrypted token will be appended. This should also be where the decryption part of the API is implemented. Allows only for valid URLs starting with http:// or https:// with a maximum length of 300 characters. This field is mandatory.
expiry_timestamp Date and time by which the encrypted token will expire, following the format YYYY-MM-DDTHH:MM:SS in UTC+0. After this time, decryption will no longer be possible. The default value means it will virtually never expire.
sender A text that should resemble the sender's origin. This string can have a maximum length of 11 characters.

^^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",
    "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   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.