KPN Encrypted Short URL API

Introduction

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.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com//security/kpn/encrypted-url


Conceptual Model

Conceptual model


API workflow

API workflow


Prerequisites

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 decrypt the token. In other words, this is where the decryption part of the API should be implemented.


Features and constraints

Features

Shortened URLs

All the shortened URLs will have the following domain "ga.kpn". Example: https://ga.kpn/He5ABk

Constraints

Country restriction

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

Expiry timestamp

The expiry timestamp must 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.

Landing URL

The landing URL should be less than 300 characters.

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)

Sandbox limitation

The sandbox version of this API will overwrite the submitted url with https://developer.kpn.com, so every short URL generated and returned by the API, will link to the KPN API Store (https://developer.kpn.com).

Support

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


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 the 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": "https://www.example.com",
    "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.

Mopinion feedback