NAV

Shippinglabel API Reference

Welcome to the documentation of our Shippinglabel-API.
This guide explains REST request and response mechanics including sample requests and responses. It also provides other information that you'll need as you write applications with the API.

If you have some questions or if you find any errors, please feel free to contact us. If you need assistance with the implementation of the API, then we will of course also be happy to help: https://shippinglabel.de/kontakt

1. Endpoint & Authentication

1.1 Endpoint

All requests described here must use the following URL as endpoint: https://api.shippinglabel.de

1.2. Authentication

Shippinglabel uses API keys to allow access to the API. You can register a new Shippinglabel API key in your personal settings.

For all requests, the API expects the API key to be included in the request header, which looks like this:
Authorization: ApiKey KEYPLACEHOLDER

Optionally, you can append your ApiKey to each URL of a request via a query parameter. The identifier for the parameter is Token.
e.g. GET /v1/shipment/S1234?Token=KEYPLACEHOLDER

1.3. Localization

Some endpoints return texts in the response body, especially when errors occur. These texts are available in German as well as in English. Users can select one of the two languages that affects the response body texts in the settings in the member panel.

You can also force a language by specifying the Accept-Language-Request header with the value de (for German) or en (for English).

Sample header to force a german locale:
Accept-Language: de

1.4 Expiration date of an API key

An Api key has no expiration date and is therefore valid until it is deleted in the member panel.

2. DHL

2.0. Models / Enums

AddressTypeEnum

AddressTypeEnum

[
  "normal",
  "station",
  "filiale"
]

DHL offers three delivery-destination-types

AddressModel

sample Address

{
  "Name1": "EDV-Biela",
  "Street": "Musterstraße",
  "StreetNumber": "123",
  "AddressAddition": "second floor, first door on the left",
  "City": "Köln",
  "Zip": "51147",
  "CountryCode": "DE"
}
property type required details
Name1 string yes first name-line on the label
Name2 string no second name-line on the label
Name3 string no third name-line on the label
AddressType AddressTypeEnum no "normal" is being used as default when not provided in the request
Street string see details required when AddressType = normal
StreetNumber string see details required when AddressType = normal
PostNumber int see details required when AddressType != normal
PackstationNumber int see details required when AddressType = station
PostfilialNumber int see details required when AddressType = filiale
AddressAddition string no contains additional address-information (e.g. second floor)
City string yes
Zip string yes zip / postal-code
State string see details may be required for some countries (e.g. USA)
CountryCode ISO 3166-2 string yes
Mail string see details required when using service "Notification"
PhoneNumber string no

ParcelModel

sample ParcelModel

{
  "Weight": 3,
  "Reference": "Order #12452",
  "ExportDocument": {
    "Type": "COMMERCIAL_GOODS",
    "Positions": [
      {
        "ItemDescription": "Nintendo 3DS screen assembly",
        "ItemAmount": 3,
        "ItemWeight": 1,
        "ItemValue": 15
      }
    ]
  }
}
property type required details
Weight positive float/int yes unit: kg - Use a dot as decimal-separator when providing a float-value.
Length positive int no unit: cm
Height positive int no unit: cm
Width positive int no unit: cm
Reference string no will be printed on the shippinglabel
ExportDocumentModel string see details may be required for international shipments

Available Services

Services

[
  {
    "Type": "BulkyGoods"
  },
  {
    "Type": "IdentCheck",
    "SurName": "string - maxlength 255",
    "FirstName": "string - maxlength 255",
    "DateOfBirth": "date - ISO 8601 string"
  },
  {
    "Type": "InsuranceAmount",
    "Value": "2500 || 25000"
  },
  {
    "Type": "NamedPersonOnly"
  },
  {
    "Type": "NoNeighbourDelivery"
  },
  {
    "Type": "PreferredLocation",
    "Value": "string - maxlength 100"
  },
  {
    "Type": "PreferredNeighbour",
    "Value": "string - maxlength 100"
  },
  {
    "Type": "VisualCheckOfAge",
    "Value": "'A16' || 'A18'"
  },
  {
    "Type": "StrongValidation"
  },
  {
    "Type": "GoGreen"
  },
  {
    "Type": "Notification"
  },
  {
    "Type": "CashOnDelivery",
    "Value": "float/int",
    "BankOwner": "string - maxlength 80",
    "BankIban": "string - maxlength 22",
    "BankName": "string - maxlength 80"
  }
]

You can use several dhl-services for your shipments.

service description additional parameters
BulkyGoods DHL’s bulky goods service makes it possible for business customers to send merchandise that does not conform to standard dimensions or has an unusual format, special packaging features or uses certain packaging materials. Items are processed individually to ensure your parcels are transported quickly and securely to their recipient. -
NamedPersonOnly Gifts, health products or erotic items: Some purchases call for particular discretion. DHL's "Named Person Only" service is an easy and cost-effective way to make sure your parcels are only released to the recipient in person. -
NoNeighbourDelivery Protect your customers' privacy and deactivate delivery to neighbors in the case of sensitive shipment content such as adult entertainment or hygiene articles. -
StrongValidation Even when weak validation-errors occur the creation of the shipment gets prevented -
GoGreen Use the GoGreen service for your carbon-neutral shipping needs and help support climate protection initiatives to offset emissions. -
Notification The receiver gets a dhl-shipmentnotification. An email needs to be provided in the receiver-address -
PreferredLocation Your customers specify a drop-off location on their premises (such as the garage) at which the shipment can be deposited. Value: string (maxlength 100) - the preferred delivery location for the parcel (e.g. garage)
PreferredNeighbour Your customers can specify a neighbor in their immediate vicinity. If the recipient is not at home at the time of delivery, the delivery agent attempts to deliver to this designated neighbor. Value: string (maxlength 100) - the name / address of your preferred neighbour
InsuranceAmount Use supplementary transport insurance to protect parcels with valuable contents. AdditionalInsuranceAmount enables you to insure your parcels against damage and loss beyond the EUR 500 liability cap - up to a maximum amount of EUR 25,000. Value: the insurance-amount. Possible Values are 2500 and 25000 (int)
VisualCheckOfAge Special care must be taken when sending adult-only goods (for example alcohol, tobacco products or media with a 16/18 age rating). DHL's Visual Age Check service is a way to ensure that your goods don't fall into the wrong hands. Value: string - accepted values:
"A16" -> minimum age of receiver needs to be 16 years.
"A18" -> minimum age of the receiver needs to be 18 years.
IdentCheck For certain product groups such as high-value goods, it is extremely important that they are delivered to your customers in person. Use the DHL Ident-Check service to make sure your parcels are only released to the recipient in person - after proof of identity and (where relevant) age are checked and documented. Surname: string (maxlength 255)
FirstName: string (maxlength 255)
DateOfBirth - ISO 8601 string
CashOnDelivery With the Cash on delivery service, the DHL parcel is only handed over to the customer once the outstanding sum has been paid. This means that, as the sender, you can be certain that you will get your money. The cash on delivery sum received will be transferred to your specified account. Value: float/int - the amount that will get payed by the customer
BankOwner: string (maxlength 50) - The owner of the bank account to which the money should be transferred.
BankIban - string (maxlength 22) - The iban of the bank account to which the money should be transferred.
BankName - string (maxlength 80) - The name of the bank account to which the money should be transferred.

ExportDocumentModel

sample ExportDocumentModel

{
  "Type": "COMMERCIAL_GOODS",
  "Positions": [
    {
      "ItemDescription": "Gameboy Advance",
      "ItemAmount": 1,
      "ItemWeight": 0.15,
      "ItemValue": 30
    }
  ]
}
property type required details
Type one of the following strings:
OTHER
PRESENT
COMMERCIAL_SAMPLE
COMMERCIAL_GOODS
DOCUMENT
RETURN_OF_GOODS
yes Depending on what items you are shipping you need to pick the correct type
TypeDescription string see details this field is required when the Type OTHRER is chosen
Positions array of ExportDocumentPositionModel yes the length of the array needs to be at least 1

ExportDocumentPositionModel

sample ExportDocumentPositionModel

{
  "ItemDescription": "Gameboy Advance",
  "ItemAmount": 3,
  "ItemWeight": 0.15,
  "ItemValue": 30
}
property type required details
ItemDescription string - maxlength 256 yes depending on what items you are shipping you need to pick the correct type
ItemAmount positive yes quantity of the given item
ItemWeight positive float/int yes the weight of one item (total weight = ItemAmount * ItemWeight)
ItemValue positive float/int yes customs-value in EUR of one item (total value = ItemAmount * ItemValue)

Notice: The total weight of all ExportDocumentPositionsModels must not exceed the total weight specified in the ParcelModel.
Weight calculation per ExportDocumentPositionModel: ItemWeight x Amount

2.1. Retrieving available products

sample response-body - 200 (OK)

[
  {
    "Id": "V01PAK",
    "Name": "DE - Paket National"
  },
  {
    "Id": "V01PRIO",
    "Name": "DE - Paket Prio"
  },
  {
    "Id": "V06PAK",
    "Name": "DE - Paket Taggleich"
  },
  {
    "Id": "V06TG",
    "Name": "DE - Paket Kurier Taggleich"
  },
  {
    "Id": "V62WP",
    "Name": "DE - Warenpost"
  }
]

GET /v1/shipment/dhl/products

With this method you can obtain all available DHL products with which you can interact.

Response-Model - 200 (OK)

property type details
Id string
Name string the displayname of the product

2.2. Single shipment - validation

sample SingleValidateShipmentRequest

{
  "Reference": "Ebay-order 123",
  "Provider": "DHL",
  "Receiver": {
    "Mail": "kontakt@shippinglabel.de",
    "PhoneNumber": "0123456789",
    "Name1": "EDV-Biela",
    "Street": "Musterstraße",
    "StreetNumber": "65d",
    "City": "Köln",
    "Zip": "51147",
    "CountryCode": "DE"
  },
  "Parcel": {
    "Weight": 1
  },
  "Services": [
    {"Type": "BulkyGoods"}
  ]
}

POST /v1/shipment/validate

Request-Model:

Property type required details
Provider string yes when using dhl use 'dhl' as value
Product string - productId no if you want to select manually the product, you can provide the id of the product as seen in 2.1. Retrieving available products. If not provided the API will try to determine the product automatically. E.g. - if you want to use Warenpost you have to provide V62WP as value.
ParticipationId int no you can manually select a participation-Id of a selected product. Check 7.3 Providersettings to determine the id of a saved participation. It is not necessary to use this property, when you only have one participation of the selected product or if you want to use your default participation of the selected product.
Shipper AddressModel no optional, because a default-address needs to be set in the user-settings
Receiver AddressModel yes
Parcel ParcelModel yes
Services ServiceModelArray no you can provide an array of services. e.g. one element might be {"Type": "BulkyGoods"} or {"Type": "AdditionalInsurance", "Value": 25000}. Check 2.0. Models / Enums for all available services.
Reference string no will be returned in the response
ShipmentDate ISO 8601 string no the date on which the shipments are handed over to DHL - the default, when missing, is the current date

Response-Model - 200 (OK)

sample response-body - 200 (OK)

{
  "Success": true,
  "Provider": "dhl"
}
property type optional details
Success bool - true no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Details string-array yes when some weak validation-warnings occur they will present in this property
Reference string yes equals the reference from the request. The Property is only present when provided in request

Response-Model - 400 (Bad request)

sample response-body - 400 (Bad request)

{
  "Success": false,
  "Provider": "dhl",
  "Message": "A hard validation error occurred.",
  "Details": ["Unknown City"]
}
property type optional details
Success bool - false no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Message string no a general message describing the problem
Details string-array yes when more details are available, they will be in this property
Reference string yes equals the reference from the request. The Property is only present when provided in request

2.3. Single shipment - creation

POST /v1/shipment

Request-Model:

sample SingleCreateShipmentRequest

{
  "Reference": "Ebay-order 123",
  "Provider": "DHL",
  "Receiver": {
    "Mail": "kontakt@shippinglabel.de",
    "PhoneNumber": "0123456789",
    "Name1": "EDV-Biela",
    "Street": "Musterstraße",
    "StreetNumber": "65d",
    "City": "Köln",
    "Zip": "51147",
    "CountryCode": "DE"
  },
  "Parcel": {
    "Weight": 1
  },
  "Services": [
    {"Type": "BulkyGoods"}
  ]
}
Property type required details
Provider string yes when using dhl use 'dhl' as value
Product string - productId no if you want to select manually the product, you can provide the id of the product as seen in 2.1. Retrieving available products. If not provided the API will try to determine the product automatically. E.g. - if you want to use Warenpost you have to provide V62WP as value.
ParticipationId int no you can manually select a participation-Id of a selected product. Check 7.3 Providersettings to determine the id of a saved participation. It is not necessary to use this property, when you only have one participation of the selected product or if you want to use your default participation of the selected product.
Shipper AddressModel no optional, because a default-address needs to be set in the user-settings
Receiver AddressModel yes
Parcel ParcelModel yes
Services ServiceModelArray no you can provide an array of services. e.g. one element might be {"Type": "BulkyGoods"} or {"Type": "AdditionalInsurance", "Value": 25000}. Check 2.0. Models / Enums for all available services.
Reference string no will be returned in the response
ShipmentDate ISO 8601 string no the date on which the shipments are handed over to DHL - the default, when missing, is the current date

Response-Model - 200 (OK):

sample response-body - 200 (OK)

{
  "Success": true,
  "Provider": "dhl",
  "Id": "S334",
  "Details": ["Unknown street-number"],
  "CreationDate": "2020-01-01T00:57:40+00:00",
  "Label": "JVBERi0xLjQKJeLG9iago8PC9G(...)aWx0ZXIvRmUxPj5zdHJlY==",
  "ShipmentNumber": "222201010038174409",
  "Reference": "Ebay-order 123"
}
property type optional details
Success bool - true no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Id string no the internal shippinglabel-id used for retrieving shipments via get-shipment
CreationDate ISO 8601 string no the creation-date of the shippinglabel in utc-format
Label string - b64 no PDF-shippinglabel encoded as base64
ShipmentNumber string no the shipping-number returned for the provider - can be used for tracking
Reference string yes equals the reference from the request. The Property is only present when provided in request
Details string-array yes when some weak validation-warnings occur they will present in this property

Response-Model - 400 (Bad request):

sample response-body - 400 (Bad request)

{
  "Success": false,
  "Provider": "dhl",
  "Message": "A hard validation error occurred.",
  "Details": ["Unknown street-number"]
}
property type optional details
Success bool - false no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Message string no a general message describing the problem
Details string-array yes when more details are available, they will be in this property
Reference string yes equals the reference from the request. The Property is only present when provided in request

2.4. Single shipment - delete / cancel

DELETE /v1/shipment/ID

In order to cancel a dhl-shipment you can use this endpoint. When successful you'll receive a 201 status-code otherwise 400.

2.5. Multiple shipments - validate

POST /v1/shipments/validate

Request-Model:

sample MultiValidateShipmentRequest

{
  "Provider": "dhl",
  "Shipments": [
    {
      "Reference": "Ebay-order 123",
      "Receiver": {
        "Mail": "kontakt@shippinglabel.de",
        "PhoneNumber": "0123456789",
        "Name1": "EDV-Biela",
        "Street": "Musterstraße",
        "StreetNumber": "65d",
        "City": "Köln",
        "Zip": "51147",
        "CountryCode": "DE"
      }
    },
    {
      "Reference": "Ebay-order 124",
      "Receiver": {
        "Name1": "John Doe",
        "Street": "Samplestreet",
        "StreetNumber": "12",
        "City": "SampleCity",
        "Zip": "12345",
        "CountryCode": "DE"
      }
    }
  ]
}
Property type required details
Provider string yes when using dhl use 'dhl' as value
Shipments array of shipments yes the same model for each element as in the request body of 2.2. Single shipment - validation but without the Provider property

Response-Model - 200 (OK):

sample response-body for BundleLabels set to true - 200 (OK)

{
  "Shipments": [
    {
      "Success": true,
      "Provider": "dhl",
      "Reference": "Ebay-order 123"
    },
    {
      "Success": true,
      "Provider": "dhl",
      "Reference": "Ebay-order 124"
    }
  ]
}
property type optional details
Shipments array of shipments no the same model for each element as in the response body of 2.2. Single shipment - validation

2.6. Multiple shipments - creation

POST /v1/shipments

Request-Model:

sample MultiCreateShipmentRequest with BundleLabels set to true

{
  "Provider": "dhl",
  "BundleLabels": true,
  "Shipments": [
    {
      "Reference": "Ebay-order 123",
      "Receiver": {
        "Mail": "kontakt@shippinglabel.de",
        "PhoneNumber": "0123456789",
        "Name1": "EDV-Biela",
        "Street": "Musterstraße",
        "StreetNumber": "65d",
        "City": "Köln",
        "Zip": "51147",
        "CountryCode": "DE"
      }
    },
    {
      "Reference": "Ebay-order 124",
      "Receiver": {
        "Name1": "John Doe",
        "Street": "Samplestreet",
        "StreetNumber": "12",
        "City": "SampleCity",
        "Zip": "12345",
        "CountryCode": "DE"
      }
    }
  ]
}
Property type required details
Provider string yes when using dhl use 'dhl' as value
BundleLabels boolean no when missing the default is set to false. When BundleLabels is set to true, you will receive all labels bundled in the root property Labels of the response-body. Otherwise you will get a Label property in each shipment element of the response body.
Shipments array of shipments yes the same model for each element as in the request body of 2.3. Single shipment - creation but without the Provider property

Response-Model - 200 (OK):

sample response-body for BundleLabels set to true - 200 (OK)

{
  "Labels": "JVBERi0xLjQKJeLjz9M(shortened)CjM0MDAKJSVFT0YK",
  "Shipments": [
    {
      "Success": true,
      "Provider": "dhl",
      "Id": "S335",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "123456789789456",
      "Reference": "Ebay-order 123"
    },
    {
      "Success": true,
      "Provider": "dhl",
      "Id": "S336",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "1534567897245126",
      "Reference": "Ebay-order 124"
    }
  ]
}
property type optional details
Labels string - b64 see details the PDF-shippinglabels of each shipment combined to one b64-encoded PDF-document. Only present when BundleLabels in the request was set to true
Shipments array of shipments no the same model for each element as in the response body of 2.3. Single shipment - creation but with a missing Label property, when BundleLabels was set to true

sample MultiValidateShipmentRequest with BundleLabels set to false

{
  "Provider": "dhl",
  "BundleLabels": false,
  "Shipments": [
    {
      "Reference": "Ebay-order 123",
      "Receiver": {
        "Name1": "EDV-Biela",
        "Street": "Musterstraße",
        "StreetNumber": "65d",
        "City": "Köln",
        "Zip": "51147",
        "CountryCode": "DE"
      }
    }
  ]
}

sample response-body for BundleLabels set to false - 200 (OK)

{
  "Shipments": [
    {
      "Label": "JVBERi0xLjQKJeLjz9M(shortened)CjM0MDAKJSVFT0YK",
      "Success": true,
      "Provider": "dhl",
      "Id": "S335",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "123456789789456",
      "Reference": "Ebay-order 123"
    }
  ]
}

3. Deutsche Post

3.0. Models / Enums

AddressModel

sample Address

{
  "Name1": "EDV-Biela",
  "Street": "Musterstraße",
  "StreetNumber": "123",
  "AddressAddition": "second floor, first door on the left",
  "City": "Köln",
  "Zip": "51147",
  "CountryCode": "DE"
}
property type required details
Name1 string yes first name-line on the label
Name2 string no secondSingle shipment - creation name-line on the label
Name3 string no third name-line on the label
Street string yes
StreetNumber string yes
AddressAddition string no contains additional address-information (e.g. second floor)
City string yes
Zip string yes zip / postal-code
State string
CountryCode ISO 3166-2 string yes
Mail string no
PhoneNumber string no

3.1. Retrieving available products

GET /v1/shipment/dp/products

This request returns an array of products with various properties

property type optional details
Id string no
Name string no the name is not unique
Annotation string or null no additional details or description
MinWeight int no unit = gramms
MaxWeight int no unit = gramms
MinLength int no unit = millimeters
MaxLength intt no unit = millimeters
MinWidth int no unit = millimeters
MaxWidth int no unit = millimeters
MinHeight int no unit = millimeters
MaxHeight int no unit = millimeters
International boolean no true = for international shipments
false = for national shipments

3.2. Single shipment - creation

POST /v1/shipment

Request-Model:

sample SingleCreateShipmentRequest

{
  "Reference": "Ebay-order 123",
  "Provider": "dp",
  "Product": "1",
  "Receiver": {
    "Mail": "kontakt@shippinglabel.de",
    "PhoneNumber": "0123456789",
    "Name1": "EDV-Biela",
    "Street": "Musterstraße",
    "StreetNumber": "65d",
    "City": "Köln",
    "Zip": "51147",
    "CountryCode": "DE"
  }
}
Property type required details
Provider string yes when using deutsche post use 'dp' as value
Product string - productId yes the product-id you want to create a shipment for - e.g. '1' for 'Standardbrief'
Shipper AddressModel no optional, because a default-address needs to be set in the user-settings
Receiver AddressModel yes
Reference string no will be returned in the response

Response-Model - 200 (OK):

sample response-body - 200 (OK)

{
  "Success": true,
  "Id": "S334",
  "Provider": "dp",
  "OrderId": 123456789,
  "CreationDate": "2020-01-01T00:57:40+00:00",
  "Label": "JVBERi0xLjQKJeLG9iago8PC9G(...)aWx0ZXIvRmUxPj5zdHJlY==",
  "ShipmentNumber": "222201010038174409",
  "Reference": "Ebay-order 123"
}
property type optional details
Success bool - true no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Id string no the internal shippinglabel-id used for retrieving shipments via get-shipment
OrderId int no the shop-order id returned by Deutsche Post
CreationDate ISO 8601 string no the creation-date of the shippinglabel in utc-format
Label string - b64 no PDF-shippinglabel encoded as base64
ShipmentNumber string no the shipping-number returned for the provider - can be used for tracking
Reference string yes equals the reference from the request. The Property is only present when provided in request
Details string-array yes when some weak validation-warnings occur they will present in this property

3.3. Multiple shipments - creation

POST /v1/shipments

Request-Model:

sample MultiCreateShipmentRequest

{
  "Provider": "dp",
  "Shipments": [
    {
      "Reference": "Ebay-order 123",
      "Product": "1",
      "Receiver": {
        "Mail": "kontakt@shippinglabel.de",
        "PhoneNumber": "0123456789",
        "Name1": "EDV-Biela",
        "Street": "Musterstraße",
        "StreetNumber": "65d",
        "City": "Köln",
        "Zip": "51147",
        "CountryCode": "DE"
      }
    },
    {
      "Reference": "Ebay-order 124",
      "Product": "2",
      "Receiver": {
        "Name1": "John Doe",
        "Street": "Samplestreet",
        "StreetNumber": "12",
        "City": "SampleCity",
        "Zip": "12345",
        "CountryCode": "DE"
      }
    }
  ]
}
Property type required details
Provider string yes when using deutsche post use 'dp' as value
Shipments array of shipments yes the same model for each element as in the request body of 3.2. Single shipment - creation but without the Provider property

Response-Model - 200 (OK):

sample response-body - 200 (OK)

{
  "Labels": "JVBERi0xLjQKJeLjz9M(shortened)CjM0MDAKJSVFT0YK",
  "OrderId": 123456789,
  "Shipments": [
    {
      "Success": true,
      "Provider": "dp",
      "Id": "S335",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "123456789789456",
      "Reference": "Ebay-order 123"
    },
    {
      "Success": true,
      "Provider": "dp",
      "Id": "S336",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "1534567897245126",
      "Reference": "Ebay-order 124"
    }
  ]
}
property type optional details
Labels string - b64 no the PDF-shippinglabels of each shipment combined to one b64-encoded PDF-document
OrderId int no the shop-order id returned by Deutsche Post
Shipments array of shipments no the same model for each element as in the request body of 3.2. Single shipment - creation but without the OrderId property

4. DPD - Consumer

4.0. Models / Enums

AddressModel

sample Address

{
  "Name1": "EDV-Biela",
  "Street": "Musterstraße",
  "StreetNumber": "123",
  "AddressAddition": "second floor, first door on the left",
  "City": "Köln",
  "Zip": "51147",
  "CountryCode": "DE"
}
property type required details
Name1 string yes first name-line on the label
Name2 string no second name-line on the label
Name3 string no third name-line on the label
Street string yes
StreetNumber string yes
AddressAddition string no contains additional address-information (e.g. second floor)
City string yes
Zip string yes zip / postal-code
State string
CountryCode ISO 3166-2 string yes
Mail string no
PhoneNumber string no

ParcelModel

sample ParcelModel

{
  "Weight": 3,
  "Reference": "Order #12452"
}
property type required details
Weight positive float/int yes unit: kg - Use a dot as decimal-separator when providing a float-value.
Reference string no will be printed on the shippinglabel

4.1. Retrieving available products

sample response-body - 200 (OK)

[
  {
    "Id": "CL",
    "Name": "Paket national"
  },
  {
    "Id": "E10",
    "Name": "Paket national 10:00"
  },
  {
    "...": "..."
  }
]

GET /v1/shipment/dpd_consumer/products

With this method you can obtain all available DPD consumer products with which you can interact.

Response-Model - 200 (OK)

property type details
Id string
Name string the displayname of the product

4.2. Single shipment - creation

POST /v1/shipment

Request-Model:

sample SingleCreateShipmentRequest

{
  "Reference": "Ebay-order 123",
  "Provider": "dpd_consumer",
  "Product": "CL",
  "Receiver": {
    "Mail": "kontakt@shippinglabel.de",
    "PhoneNumber": "0123456789",
    "Name1": "EDV-Biela",
    "Street": "Musterstraße",
    "StreetNumber": "65d",
    "City": "Köln",
    "Zip": "51147",
    "CountryCode": "DE"
  }
}
Property type required details
Provider string yes when using DPD consumer 'dpd_consumer' as value
Product string - productId yes the product-id you want to create a shipment for - e.g. 'CL'
Shipper AddressModel no optional, because a default-address needs to be set in the user-settings
Receiver AddressModel yes
Reference string no will be returned in the response

Response-Model - 200 (OK):

sample response-body - 200 (OK)

{
  "Success": true,
  "Provider": "dpd_consumer",
  "Id": "S334",
  "CreationDate": "2020-01-01T00:57:40+00:00",
  "Label": "JVBERi0xLjQKJeLG9iago8PC9G(...)aWx0ZXIvRmUxPj5zdHJlY==",
  "ShipmentNumber": "MPS0998505298371920200919",
  "Reference": "Ebay-order 123"
}
property type optional details
Success bool - true no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Id string no the internal shippinglabel-id used for retrieving shipments via get-shipment
CreationDate ISO 8601 string no the creation-date of the shippinglabel in utc-format
Label string - b64 no PDF-shippinglabel encoded as base64
ShipmentNumber string no the shipping-number returned for the provider - can be used for tracking
Reference string yes equals the reference from the request. The Property is only present when provided in request
Details string-array yes when some weak validation-warnings occur they will present in this property

4.3. Multiple shipments - creation

POST /v1/shipments

Request-Model:

sample MultiCreateShipmentRequest

{
  "Provider": "dpd_consumer",
  "Shipments": [
    {
      "Reference": "Ebay-order 123",
      "Product": "CL",
      "Receiver": {
        "Mail": "kontakt@shippinglabel.de",
        "PhoneNumber": "0123456789",
        "Name1": "EDV-Biela",
        "Street": "Musterstraße",
        "StreetNumber": "65d",
        "City": "Köln",
        "Zip": "51147",
        "CountryCode": "DE"
      }
    },
    {
      "Reference": "Ebay-order 124",
      "Product": "CL",
      "Receiver": {
        "Name1": "John Doe",
        "Street": "Samplestreet",
        "StreetNumber": "12",
        "City": "SampleCity",
        "Zip": "12345",
        "CountryCode": "DE"
      }
    }
  ]
}
Property type required details
Provider string yes when using DPD consumer 'dpd_consumer' as value
Shipments array of shipments yes the same model for each element as in the request body of 4.2. Single shipment - creation but without the Provider property

Response-Model - 200 (OK):

sample response-body - 200 (OK)

{
  "Labels": "JVBERi0xLjQKJeLjz9M(shortened)CjM0MDAKJSVFT0YK",
  "Shipments": [
    {
      "Success": true,
      "Provider": "dpd_consumer",
      "Id": "S335",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "123456789789456",
      "Reference": "Ebay-order 123"
    },
    {
      "Success": true,
      "Provider": "dpd_consumer",
      "Id": "S336",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "1534567897245126",
      "Reference": "Ebay-order 124"
    }
  ]
}
property type optional details
Labels string - b64 no the PDF-shippinglabels of each shipment combined to one b64-encoded PDF-document
Shipments array of shipments no the same model for each element as in the request body of 4.2. Single shipment - creation but without the Provider property

5. DPD - Business

5.0. Models / Enums

AddressModel

sample Address

{
  "Name1": "EDV-Biela",
  "Street": "Musterstraße",
  "StreetNumber": "123",
  "AddressAddition": "second floor, first door on the left",
  "City": "Köln",
  "Zip": "51147",
  "CountryCode": "DE"
}
property type required details
Name1 string yes first name-line on the label
Name2 string no second name-line on the label
Name3 string no third name-line on the label
Street string yes
StreetNumber string yes
AddressAddition string no contains additional address-information (e.g. second floor)
City string yes
Zip string yes zip / postal-code
State string
CountryCode ISO 3166-2 string yes
Mail string no
PhoneNumber string no

ParcelModel

sample ParcelModel

{
  "Weight": 3,
  "Reference": "Order #12452"
}
property type required details
Weight positive float/int yes unit: kg - Use a dot as decimal-separator when providing a float-value.
Reference string no will be printed on the shippinglabel

5.1. Retrieving available products

sample response-body - 200 (OK)

[
  {
    "Id": "Classic_Predict",
    "Name": "Classic Predict"
  },
  {
    "Id": "Express_International",
    "Name": "Express International"
  },
  {
    "...": "..."
  }
]

GET /v1/shipment/dpd/products

With this method you can obtain all available DPD business products with which you can interact.

Response-Model - 200 (OK)

property type details
Id string
Name string the displayname of the product

5.2. Single shipment - validation

sample SingleValidateShipmentRequest

{
  "Reference": "Ebay-order 123",
  "Provider": "dpd",
  "Product": "CLASSIC",
  "Receiver": {
    "Mail": "kontakt@shippinglabel.de",
    "PhoneNumber": "0123456789",
    "Name1": "EDV-Biela",
    "Street": "Musterstraße",
    "StreetNumber": "65d",
    "City": "Köln",
    "Zip": "51147",
    "CountryCode": "DE"
  },
  "Parcel": {
    "Weight": 1
  }
}

POST /v1/shipment/validate

Request-Model:

Property type required details
Provider string yes when using dpd business use 'dpd' as value
Product string - productId yes the product-id you want to create a shipment for - check 5.1. Retrieving available products
Receiver AddressModel yes
Parcel ParcelModel yes
Reference string no will be returned in the response

Response-Model - 200 (OK)

sample response-body - 200 (OK)

{
  "Success": true,
  "Provider": "dpd"
}
property type optional details
Success bool - true no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Details string-array yes when some weak validation-warnings occur they will present in this property
Reference string yes equals the reference from the request. The Property is only present when provided in request

Response-Model - 400 (Bad request)

property type optional details
Success bool - false no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Message string no a general message describing the problem
Details string-array yes when more details are available, they will be in this property
Reference string yes equals the reference from the request. The Property is only present when provided in request

5.3. Single shipment - creation

POST /v1/shipment

Request-Model:

sample SingleCreateShipmentRequest

{
  "Reference": "Ebay-order 123",
  "Provider": "dpd",
  "Product": "CLASSIC",
  "Receiver": {
    "Mail": "kontakt@shippinglabel.de",
    "PhoneNumber": "0123456789",
    "Name1": "EDV-Biela",
    "Street": "Musterstraße",
    "StreetNumber": "65d",
    "City": "Köln",
    "Zip": "51147",
    "CountryCode": "DE"
  },
  "Parcel": {
    "Weight": 1
  }
}
Property type required details
Provider string yes when using dpd business use 'dpd' as value
Product string - productId yes the product-id you want to create a shipment for - check 5.1. Retrieving available products
Receiver AddressModel yes
Parcel ParcelModel yes
Reference string no will be returned in the response

Response-Model - 200 (OK):

sample response-body - 200 (OK)

{
  "Success": true,
  "Provider": "dpd",
  "Id": "S534",
  "CreationDate": "2020-01-01T00:57:40+00:00",
  "Label": "JVBERi0xLjQKJeLG9iago8PC9G(...)aWx0ZXIvRmUxPj5zdHJlY==",
  "ShipmentNumber": "MPS0998505298371920200919",
  "Reference": "Ebay-order 123"
}
property type optional details
Success bool - true no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Id string no the internal shippinglabel-id used for retrieving shipments via get-shipment
CreationDate ISO 8601 string no the creation-date of the shippinglabel in utc-format
Label string - b64 no PDF-shippinglabel encoded as base64
ShipmentNumber string no the shipping-number returned for the provider - can be used for tracking
Reference string yes equals the reference from the request. The Property is only present when provided in request
Details string-array yes when some errors occur they will present in this property

Response-Model - 400 (Bad request):

property type optional details
Success bool - false no this property exists for compatibility-reasons for clients which can not evaluate status-codes
Provider string no
Message string no a general message describing the problem
Details string-array yes when more details are available, they will be in this property
Reference string yes equals the reference from the request. The Property is only present when provided in request

5.4. Multiple shipments - validate

POST /v1/shipments/validate

Request-Model:

sample MultiValidateShipmentRequest

{
  "Provider": "dpd",
  "Shipments": [
    {
      "Reference": "Ebay-order 123",
      "Receiver": {
        "Name1": "EDV-Biela",
        "Street": "Musterstraße",
        "StreetNumber": "65d",
        "City": "Köln",
        "Zip": "51147",
        "CountryCode": "DE"
      }
    },
    {
      "Reference": "Ebay-order 124",
      "Receiver": {
        "Name1": "John Doe",
        "Street": "Samplestreet",
        "StreetNumber": "12",
        "City": "SampleCity",
        "Zip": "12345",
        "CountryCode": "DE"
      }
    }
  ]
}
Property type required details
Provider string yes when using dpd business use 'dpd' as value
Shipments array of shipments yes the same model for each element as in the request body of 5.2. Single shipment - validation but without the Provider property

Response-Model - 200 (OK):

sample response-body - 200 (OK)

{
  "Shipments": [
    {
      "Success": true,
      "Provider": "dpd",
      "Reference": "Ebay-order 123"
    },
    {
      "Success": true,
      "Provider": "dpd",
      "Reference": "Ebay-order 124"
    }
  ]
}
property type optional details
Shipments array of shipments no the same model for each element as in the response body of 2.2. Single shipment - validation

5.5. Multiple shipments - creation

POST /v1/shipments

Request-Model:

sample MultiCreateShipmentRequest

{
  "Provider": "dpd",
  "Shipments": [
    {
      "Product": "CLASSIC",
      "Reference": "Ebay-order 123",
      "Receiver": {
        "Mail": "kontakt@shippinglabel.de",
        "PhoneNumber": "0123456789",
        "Name1": "EDV-Biela",
        "Street": "Musterstraße",
        "StreetNumber": "65d",
        "City": "Köln",
        "Zip": "51147",
        "CountryCode": "DE"
      }
    },
    {
      "Product": "CLASSIC",
      "Reference": "Ebay-order 124",
      "Receiver": {
        "Name1": "John Doe",
        "Street": "Samplestreet",
        "StreetNumber": "12",
        "City": "SampleCity",
        "Zip": "12345",
        "CountryCode": "DE"
      }
    }
  ]
}
Property type required details
Provider string yes when using dpd business use 'dpd' as value
Shipments array of shipments yes the same model for each element as in the request body of 5.3. Single shipment - creation but without the Provider property

Response-Model - 200 (OK):

sample response-body - 200 (OK)

{
  "Labels": "JVBERi0xLjQKJeLjz9M(shortened)CjM0MDAKJSVFT0YK",
  "Shipments": [
    {
      "Success": true,
      "Provider": "dpd",
      "Id": "S335",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "123456789789456",
      "Reference": "Ebay-order 123"
    },
    {
      "Success": true,
      "Provider": "dpd",
      "Id": "S336",
      "CreationDate": "2020-01-01T00:57:40+00:00",
      "ShipmentNumber": "1534567897245126",
      "Reference": "Ebay-order 124"
    }
  ]
}
property type optional details
Labels string - b64 no the PDF-shippinglabels of each shipment combined to one b64-encoded PDF-document
Shipments array of shipments no the same model for each element as in the response body of 5.3. Single shipment - creation but with a missing Label property

6. Retrieving Shipments

6.1. Get single shipment

Use this method, to retrieve a previously created shipment. All you need is to provide the shipment-id (e.g. S352) in the URL:

GET /v1/shipment/:id

Response-Model - 200 (OK)

GET /v1/shipment/S123
sample response-body - 200 (OK)

{
  "Id":"S123",
  "Provider":"dhl",
  "Application":3,
  "Reference":null,
  "CreationDate":"2021-08-25T15:15:15+00:00",
  "ShipmentNumber":"00340434333423317654",
  "Status":"Created",
  "Receiver":{
    "Name1":"Max Mustermann",
    "Street":"Musterstraße",
    "StreetNumber":"70",
    "CountryCode":"DE",
    "Zip":"51147",
    "City":"Köln"
  },
  "Shipper":{
    "Name1":"EDV-Biela",
    "Mail":"kontakt@shippinglabel.de",
    "Street":"Musterstraße",
    "StreetNumber":"124",
    "Zip":"51147",
    "City":"Köln",
    "CountryCode":"DE"
  },
  "Parcel":{"Weight":"4.5"},
  "Label":"JVBERi0xLjQKJeLjz9M(shortened)CjM0MDAKJSVFT0YK"
}
property type optional details
Application int no
Id string no the internal shippinglabel-id used for retrieving shipments via get-shipment
ShipmentNumber string no the shipping-number returned for the provider - can be used for tracking
Label string - b64 no PDF-shippinglabel encoded as base64
Provider string no the provider the shipment got created with
CreationDate ISO 8601 string no
Receiver AddressModel no
Shipper AddressModel no
Parcel ParcelModel true for some providers you do not need to pass parcel-data, so it will be only returned when initially provided
Reference string / null no when provided in the creation
Status string no the status of the shipment - Created or Deleted

6.2. Get multiple shipments

Use this method, to retrieve multiple previously created shipments at once. All you need is to provide the shipment-ids seperated by commas (e.g. S352,S353) in the URL:

GET /v1/shipments/:id1,:id2,:idX

Response-Model - 200 (OK)

GET /v1/shipments/S123,S124
sample response-body - 200 (OK)

{
  "Labels": "JVBERi0xLjQKJeLjz9M(shortened)CjM0MDAKJSVFT0YK",
  "Shipments": [
    {
      "Id": "S123",
      "Application": 1,
      "ShipmentNumber": "A0027BBE300000000F01",
      "Provider": "dp",
      "Status": "Created",
      "CreationDate": "2020-02-01T00:57:40Z",
      "Reference": null,
      "Receiver": "...",
      "Shipper": "..."
    },
    {
      "Id": "S124",
      "Application": 1,
      "ShipmentNumber": "222201010040468689",
      "Provider": "dhl",
      "Status": "Created",
      "CreationDate": "2020-01-01T00:57:40Z",
      "Reference": "test",
      "Receiver": "...",
      "Shipper": "...",
      "Parcel": {"Weight": 1}
    }
  ]
}

property type optional details
Labels string - b64 no the PDF-shippinglabels of each shipment combined to one b64-encoded PDF-document
Shipments array of shipments no the model of each shipment equals the response-model of 6.1. Get single shipment, except the missing Label-property in each object.

7. Userspecific

7.1 Userinfo

With this method you can obtain some information about your user-account.

GET /user

Response-Model - 200 (OK)

sample response-body - 200 (OK)

{
  "Id": 2,
  "Contract": "Basis",
  "Locale": "de",
  "Mail": "kontakt@shippinglabel.de",
  "Balance": 24.12,
  "RegisterDate": "2019-07-07 18:54:28",
  "LastSeen": "2019-09-29 20:32:01",
  "Shipments": {
    "Today": 10,
    "Month": 40,
    "Total": 1342
  },
  "LastShipments": [
    {"...": ""}
  ]
}
property type details
Id int your internal userid
Contract string the name of your current contract
Locale string the locale of your account - possible values are 'de' or 'en'
Mail string the mail of your account
Balance float the current shippinglabel-balance of your account
RegisterDate ISO 8601 string the date when your account was created
LastSeen ISO 8601 string the date of your last login into the shippinglabel-memberpanel
Shipments object shipmentstats
LastShipments array of shipments contains last 10 shipments

7.2 Useraddresses

With this method you can obtain all saved addresses of your user-account

GET /user/adddresses

Response-Model - 200 (OK)

sample response-body - 200 (OK)

{
  "Invoice": {
    "Name1": "Daniel",
    "Name2": "Biela",
    "Name3": null,
    "Street": "Musterstraße",
    "StreetNumber": "123",
    "Zip": "51147",
    "City": "Köln",
    "CountryCode": "DE",
    "PhoneNumber": "0123456789",
    "Mail": "kontakt@shippinglabel.de"
  },
  "Shipping": {
    "Name1": "EDV-Biela",
    "Name2": null,
    "Name3": null,
    "Street": "Musterstraße",
    "StreetNumber": "123",
    "Zip": "51147",
    "City": "Köln",
    "CountryCode": "DE",
    "PhoneNumber": null,
    "Mail": "kontakt@shippinglabel.de"
  }
}
property type optional details
Invoice addressmodel yes only available if saved in the memberpanel
Shipping addressmodel yes only available if saved in the memberpanel
Retour addressmodel yes only available if saved in the memberpanel

7.3 Providersettings

Returns all providers, the user has settings saved for. May be used, to determine what providers the user can create shipments with. May contain extra information depending on the provider (see below).

GET /user/providers

Response-Model - 200 (OK)

sample response-body - 200 (OK)

[
  {
    "Name": "dhl",
    "Default": true,
    "Products": {
      "V01PAK": [
        {
          "Id": 8,
          "Value": "01",
          "Default": true,
          "ServicePreferredNeighbour": true,
          "ServicePreferredLocation": true,
          "ServiceVisualCheckOfAge": true,
          "ServiceNamedPersonOnly": true,
          "ServiceIdentCheck": true,
          "ServicePreferredDay": true,
          "ServiceNoNeighbourDelivery": true,
          "ServiceGoGreen": true,
          "ServiceAdditionalInsurance": true,
          "ServiceBulkyGoods": true,
          "ServiceCashOnDelivery": true,
          "ServiceIndividualSenderRequirement": false,
          "ServicePackagingReturn": false,
          "ServiceParcelOutletRouting": false
        }
      ],
      "V53WPAK": [
        {
          "Id": 4,
          "Value": "01",
          "Default": true,
          "ServiceEndorsement": true,
          "ServiceGoGreen": true,
          "ServiceAdditionalInsurance": true,
          "ServiceBulkyGoods": true,
          "ServiceCashOnDelivery": true,
          "ServicePremium": true
        }
      ]
    }
  },
  {
    "Name": "dpd",
    "Default": false,
  },
  {
    "Name": "dp",
    "Default": false,
    "DefaultProductId": "10166"
  }
]

You will get an array of your saved providers.

property type optional details
Name string no the providername
Default boolean no indicates whether the provider is set as default in the usersettings. The user does not need to have a default-provider.
Products array of dhlproducts yes only present when Name = dhl. It contains all your saved dhl-participations grouped by product.
DefaultProductId string or null yes only present when Name = dp. Contains the id of the default-product the user has set in his settings.

HTTP-Statuscodes

Error Code Meaning Details
200 okay Okay, response-body available
204 okay - no content Okay, no response-body available
400 bad request An error occurred (f.e. shipment creation failed or errors on shipment-validation occurred). Check response-body for details.
401 not authenticated You are not authenticated. Perhaps a bad API token was used.
402 insufficient balance You must make a deposit, as there is not enough balance for creating a shipment.
403 forbidden You are not authorized to access this API route or method.
404 not found The requested route or ressource does not exist.
429 too many requests You are sending too many requests. Try again in a few moments.
500 internal server error An internal error occurred. In this case we will get notified and take a look at it asap.
504 gateway timeout Timeout occurred. May result from problems on the provider-endpoint.

Changelog

22.11.2021

Allgemeines

DHL

DPD-Business

Deutsche Post

25.04.2021

DPD - Geschäftskundenschnittstelle

Deutsche Post

Userspezifisches

Sonstiges

22.11.2020

Http-StatusCodes

DHL

05.10.2020

Allgemeines

DHL

26.09.2020

Allgemeines

Deutsche Post

DPD

DHL

11.06.2020

22.04.2020