Introduction¶

Welcome to the KeenDelivery API documentation. Here you will find the resource addresses and the explanation on how to use our API.

All of the endpoints start with https://portal.keendelivery.com/api/v2 and all the requests must use the following headers:

Header	Value	Comments
Accept	application/json
Content-Type	application/json	Not required for GET requests

Examples¶

The examples as listed in the documentation can also be found on GitHub: https://github.com/keendelivery/api

Authentication¶

Our API uses an API token as a parameter in the URL to authenticate the user. The API token has to be supplied for every request as a query parameter.

To retrieve your token, login in our portal at https://portal.keendelivery.com/ with your credentials and go to Instellingen > Koppelingen. The token can be found in the field labeled ‘API Key’

Verifying your API token¶

To verify if you if the API token is correct, you can make a call to our API to verify the credentials. To do this, you have to use the following endpoint:

$ curl "https://portal.keendelivery.com/api/v2/authorization?api_token=YourAPIToken" \
  -H 'Accept: application/json'

If the API token is correct, you will receive the following response:

{
  "authorized": true,
  "authorized_as": "developer@keendelivery.com"
}

Error codes¶

Code	Cause
401	The supplied API token is incorrect

Example in PHP with Guzzle¶

<?php

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://portal.keendelivery.com/api/v2/',
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'query' => ['api_token' => 'YourApiToken'],
]);

$response = $client->get('authorization');

Shipping methods¶

To create a shipment, you have to supply a shipping method and a service. Because the shipping methods can be enabled and disabled in the portal, you should rely on the results of this endpoint and never hard code these values within your application. The available shipping methods could change, but we highly encourage your to cache the result of this request for 24 hours.

Retrieving a list of available shipping methods¶

To retrieve the list of available shipping methods and services, you should make to following request

$ curl "https://portal.keendelivery.com/api/v2/shipping_methods?api_token=YourAPIToken" \
  -H 'Accept: application/json'

Return values¶

The response will be like this (shortened for readability):

{
 "shipping_methods": {
   "1": {
     "value": "DPD",
     "text": "DPD",
     "services": {
       "1": {
         "value": "DPD_HOME_DROP_OFF",
         "text": "Home (naar particulieren) - Inleveren",
         "options": {
           "1": {
             "field": "predict",
             "text": "Predict ",
             "type": "selectbox",
             "mandatory": 1,
             "choices": {
               "sms": {
                 "value": 1,
                 "text": "SMS notificatie"
               },
               "email": {
                 "value": 2,
                 "text": "E-mail notificatie"
               }
             }
           },
           "2": {
             "field": "weight",
             "text": "Gewicht ",
             "type": "textbox",
             "mandatory": 1,
             "choices": null
           },
           "3": {
             "field": "saturday_delivery",
             "text": "Zaterdaglevering ",
             "type": "checkbox",
             "mandatory": 0,
             "choices": null
           },
           "4": {
             "field": "cod",
             "text": "Rembours ",
             "type": "checkbox",
             "mandatory": 0,
             "choices": null
           },
           "5": {
             "field": "cod_value",
             "text": "Rembours waarde ",
             "type": "textbox",
             "mandatory": 0,
             "choices": null
           },
           "6": {
             "field": "send_track_and_trace_email",
             "text": "Verstuur track&trace e-mail ",
             "type": "checkbox",
             "mandatory": 0,
             "choices": null
           },
           "7": {
             "field": "bcc_email",
             "text": "BCC e-mailadres voor track&trace e-mail ",
             "type": "email",
             "mandatory": 0,
             "choices": null
           }
         }
       }
     }
   }
 }

shipping_methods¶

Property	Description
value	The value to be entered in the `product` field when creating a shipment
text	The textual representation of the shipping method
services	The list with all the services that are available for the shipping method

services¶

Property	Description
value	The value the be entered in the `service` field when creating a shipment
text	The textual representation of the service
options	The available options for the service

options¶

Property	Description
field	The field to be included in the request to create a shipment
text	The textual representation of the options
type	The type of form field to be used. This is used in our plug-ins.
mandatory	Whether of nor the field is required. `1` means the field is required, `0` means it can be omitted
choices	Contains a list of choices which can be entered as a value for the field. If this is `null` there are no choices available

choices¶

Property	Description
value	The value to be entered in the field for the option
text	The textual representation of the choice

Error codes¶

Code	Cause
401	The supplied API token is incorrect

Example in PHP with Guzzle¶

<?php


use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://portal.keendelivery.com/api/v2/',
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'query' => ['api_token' => 'YourAPIToken'],
]);

$response = $client->get('shipping_methods');

Shipments¶

Create a shipment¶

To create a shipment, you should make the following request:

 curl -X "POST" "https://portal.keendelivery.com/api/v2/shipment?api_token=YourAPIToken" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "product": "DPD",
  "service": "DPD_HOME_DROP_OFF",
  "amount": 1,
  "reference": "Shipment reference",
  "company_name": "KeenDelivery",
  "contact_person": "John Doe",
  "street_line_1": "Wiltonstraat",
  "number_line_1": "41",
  "number_line_1_addition": "",
  "zip_code": "3905 KW",
  "city": "Veenendaal",
  "country": "NL",
  "phone": "0318-513813",
  "email": "developer@keendelivery.com"
  "comment": "This is a comment",
  "predict": 1,
  "weight": 1
}'

Request values¶

Field	Type	Description
product	string	The shipment to be used. Possible values can be found on shipping_methods.
service	string	The service to be used. Possible values can be found on shipping_methods.
amount	int	The amount of parcels of this shipment
reference	string	Your own reference of the shipment
company_name	string	The company name of the addressee
contact_person	string	The name of the addressee
street_line_1	string	The street of the addressee
number_line_1	string	The house number of the addressee
number_line_1_addition	string	The addition of the house number of the addressee
zip_code	string	The postal code of the addressee
city	string	The city of the addressee
country	string	The country code of the addressee in ISO-3166-1 format
phone	string	The phone number of the addressee
email	string	The e-mail address of the addressee
comment	string	A comment of the address. Will be used as second address line on the label if possible.
weight	int	The weight of the parcel in kilograms. Must be entered as an integer.

Besides these request values, other field must be supplied to the request according the response of the shipping_methods endpoint. In the example above you can see that the field predict is included. This field is a required field for this specific service, as you can see in the example response of the shipping_methods endpoint.

Response values¶

The response wil be like this (shortened for readability):

{
  "shipment_id": 12345678,
  "label": "",
  "track_and_trace": {
    "09988914957226": "https:\/\/tracking.dpd.de\/parcelstatus?locale=nl_NL&query=09988914957226"
  }
}

Property	Description
shipment_id	The id of the generated shipment.
label	A base64 encoded string of the label in the requested format
track_and_trace	List of parcel numbers with the corresponding links to the track and trace page

Error codes¶

Code	Cause
401	The supplied API token is incorrect
422	Something is wrong with the request. The errors are returned in the response body as a JSON object

Example in PHP with Guzzle¶

<?php

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://portal.keendelivery.com/api/v2/',
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'query' => ['api_token' => KEENDELIVERY_API_TOKEN],
]);

$response = $client->post(
    'shipment',
    [
        'body' => [
            "company_name"=> "KeenDelivery",
            "street_line_1"=> "Wiltonstraat",
            "number_line_1"=> "41",
            "number_line_1_addition"=> "",
            "zip_code"=> "3905 KW",
            "city"=> "Veenendaal",
            "country"=> "NL",
            "contact_person"=> "John Doe",
            "phone"=> "0318-513813",
            "comment"=> "This is a comment",
            "email"=> "developer@keendelivery.com",
            "reference"=> "Referentie",
            "product"=> "DPD",
            "service"=> "DPD_HOME_DROP_OFF",
            "amount"=> 1,
            "weight"=> 1,
            "predict"=> 1,
        ]
    ]
);

Print labels¶

To combine the labels of multiple shipments into one file to print them, you should make to following request:

$ curl -X "POST" "https://portal.keendelivery.com/api/v2/label?api_token=YourAPIToken" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d $'{
      "shipments": [
         1234567,
         1234568,
         1234569
      ]
    }'

Request values¶

Field	Type	Description
shipments	array	The array with one or more ID’s of the shipment to fetch the labels for

Reponse values¶

The response will be like this (shortened for readability):

{
  "labels": "",
}

Property	Description
labels	Contains the labels encoded with base64. The format of the labels is according to the settings in the portal. (Instellingen > Print instellingen)

Error codes¶

Code	Cause
401	The supplied API token is incorrect
422	Something is wrong with the request. The errors are returned in the response body as a JSON object

<?php

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://portal.keendelivery.com/api/v2/',
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'query' => ['api_token' => 'YourApiToken'],
]);

$response = $client->post(
    'label',
    ['body' => ['shipments' => [123456, 123457, 123458]]]
);

file_put_contents('labels.pdf', base64_decode(json_decode($response->getBody())->labels));

Parcel Shops finder¶

It is possible to offer your customer the possibility to let the shipment be delivered on a parcel shop. In order to find the closest parcel shop, you should use this endpoint, as you need the ID of the parcel shop when creating a shipment.

Get the parcel shops¶

To get the closest parcel shops, you should make the following request

$ curl -X "POST" "https://portal.keendelivery.com/api/v2/parcel-shop/search?api_token=YourAPIToken" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d $'{
  "country": "NL",
  "street_line_1": "Wiltonstraat",
  "city": "Veenendaal",
  "number_line_1": "41",
  "products": [
    "DPD",
    "DHL"
  ]
}'

Request values¶

Field	Type	Description
street_line_1	string	The street name of the address
number_line_1	string	The house number of the address
zip_code	string	The postal code of the address
city	string	The city of the address
country	string	The country code of the address. This field is always required.
limit	int	The amount of parcel shops you’d like to receive. If this field is not included, it defaults to 5.
products	array	Which carriers you’d like the parcel shops of. Currently only DPD and DHL are supported.
latitude	float	The latitude of the address
longitude	float	The longitude of the address

Note that not all fields are required. When you already have the latitude and the longitude off the address, you don’t have to include the street_line_1, number_line_1, zip_code and city fields.

The field for zip code is only required if you don’t include street_line_1, number_line_1 and city in the request.

Response values¶

The response will be like this (shortened for readability):

{
  "parcel_shops":{
    "DPD":[
      {
        "id":480004,
        "name":"A12TOYS",
        "street":"STORKSTRAAT",
        "house_number":"1A",
        "country":"NL",
        "zip_code":"3905KX",
        "city":"Veenendaal",
        "longitude":5.55926,
        "latitude":52.03905,
        "opening_hours":[
          {
            "afternoon_close":"17:00",
            "afternoon_open":"16:00",
            "morning_open":"11:00",
            "morning_close":"15:00",
            "weekday":1
          }
        ]
      }
    ]
  }
}

Field	Description
parcelshops	Holds the parcelshops seperated by carrier. (DPD or DHL)
id	The id of the parcel shop. You will need this when creating a shipment.
name	The name of the parcel shop.
street	The street of the parcel shop.
house_number	The house number of the parcel shop.
country	The country code of the parcel shop.
zip_code	The zip code of the parcel shop
city	The city of the parcel shop
longitude	The longitude of the parcel shop. This can be used to place the parcel shops on a map.
latitude	The latitude of the parcel shop. This can be used to place the parcel shops on a map.
opening_hours	An array with the opening hours of the parcel shop. Each day the shop is open, is listed as an item in this array. If a day misses, you can safely assume the shop is’nt open on that day.

Error codes¶

Code	Cause
401	The supplied API token is incorrect

Example in PHP with Guzzle¶

<?php


use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://portal.keendelivery.com/api/v2/',
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'query' => ['api_token' => 'YourAPIToken'],
]);

$response = $client->post(
    'parcel-shop/search',
    [
        'form_params' => [
            'zip_code' => '3905KW',
            'street_line_1' => 'Wiltonstraat',
            'number_line_1' => '41',
            'country' => 'NL',
            'city' => 'Veenendaal',
            'products' => ['DPD', 'DHL'],
        ]
    ]
);