KPN SMS API

API reference on SwaggerHub

Introduction

With the SMS API, anyone can build reliable SMS messaging services using our infrastructure. It is available as a free demo version too. Send some test SMS messages and experiment with the API before taking it into production. In your API Store account you can apply to take the SMS API into production.

Conceptual model

Conceptual model

Definitions

SMS

SMS is an abbreviation of Short Message Service. It's a service on mobile phones to send and receive short messages.

API workflow

API workflow

Features and constraints

Features

  • Send a text message to another mobile phone number.

Constraints

  • No images can be send with SMS.
  • Messages longer than 160 characters will be send as multiple SMS messages.
  • With this API, messages can only be send to mobile phones registered in the Netherlands. So the country code is locked to +31. Also 097 range is allowed.
    Note: 060xxxxxxx, 067xxxxxxx and 069xxxxxxx are not valid mobile numbers.
  • A single message can be send to a single recipient. Bulk messaging will be added in the future.

Getting started

Authentication

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:

cURL

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 \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -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 "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -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": "demo123@kpn.com",
    "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"
}

SwaggerHub

  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.

Postman

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

Send SMS

Send an SMS by calling the POST /send endpoint of the SMS API in Swaggerhub or Postman.

Note: Keep in mind that messages can only be sent to Dutch mobile phones (country code +31).

The payload uses following parameters:

  • content - Put your message here. Long messages will be split into multiple SMS.
  • mobile_number - The mobile phone number of the addressee. Use the country code +31 at the start.
  • sender - A text that should resemble the sender's origin. This string can have a maximum length of 11 characters.

Create your payload for the request using below snippet:

{
    "messages": [
        {
            "content": "Greetings from KPN!",
            "mobile_number": "+316********"
        }
    ],
   "sender": "Demo App"
 }

SwaggerHub:

  1. Select POST /send.
  2. Click Try it out.
  3. Edit the body parameter by providing the payload snippet above. In the payload change the content, mobile_number and sender to your own good. Make sure the content-type is set to application/json.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Select (POST) /send.
  2. In the Body section, set the type to raw and insert the payload snippet above. In the payload change the content, mobile_number and sender to your own good. Make sure the content-type is set to application/json.
  3. Click Send.
  4. Check the response code and message.

Result example:

{
  "document_id": "b4e905d4-774c-4c83-8360-01427e17a33a",
  "status": "OK"
}

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