Developer Guide - Air, Sea, Road (EU), Rail
On this page you will find an overview of the available APIs and the different options offered via each API next to a description of the involved authentication method used in the APIs.
API: Booking
Submit bookings to DSV via DSV’s Booking API.
Supported transport modes: Air, Sea, Road (EU) and Rail
The Booking API offers two methods to submit a booking:
Validate booking (test or validate a booking – booking will NOT be sent to DSV)
Feature: Option to validate the content of a booking prior submitting the final booking to DSV. This method uses the same set of validations applied in the actual booking flow. Bookings sent via this method are not processed by DSV.
Submit new booking (submit a real booking – booking will be sent to DSV)
Feature: Submit a real transport booking to DSV to move a package from A to B. This method provides two options to submit a booking to DSV, either by sending the booking to DSV’s myDSV customer portal as a draft booking or as a final booking to DSV without the need for further involvement by the customer. If a booking is sent as a draft booking to myDSV, an operator at the customer will need to click book in myDSV to finalise the booking towards DSV.
The two listed options are controlled via the autobook flag specified in the Open API documentation.
Critical technical specifications - booking addresses (Booking Party and Freight Payer)
When submitting bookings towards DSV, you need to use a test account number in the MDM field for the address parties Booking Party and Freight Payer with all other address fields left out (example: "parties": { "freightPayer": { "address": { "mdm": "1234567890"}}, "bookingParty": { "address": { "mdm": "1234567890"}}, ....},....).
You will get your personal test account number in the confirmation email you receive when subscribing to one of the generic APIs.
_________________________________________________________________________________________________________
API: Label Printing
Print package labels (PDF) for bookings submitted via DSV’s Booking API or online via myDSV.
Supported transport modes: Air, Sea, Road and Rail
The Label Print API offers one method to print a package label:
Print label (by myDSV booking ID – e.g. 40257145990000123456)
Feature: Download PDF package labels directly via API for bookings submitted via the Booking API or online via DSV’s myDSV customer portal.This API uses the DSV booking ID provided in the booking confirmations from the API bookings or visualised on screen in myDSV.
_________________________________________________________________________________________________________
API: Tracking
Track the status and latest events of your shipments moved by DSV.
Supported transport modes: Air, Sea, Road (EU), Rail and Xpress.
The tracking API offers three methods to obtain shipment information:
Shipment list (by period, mode etc.)
Features: Retrieve a list of shipments for a specific period, transport mode or shipment statusData elements: DSV Shipment ID, DSV Booking ID, Customer references, Address details, Transport mode, Shipment Status, Pickup date/time, Delivery date/time
Shipment details (by myDSV booking ID – e.g. 40257145990000123456)
Features: Retrieve detailed shipment data for a specific shipment, by searching by the DSV booking ID received from API booking or bookings submitted via myDSV.Data elements: DSV Shipment ID, DSV Booking ID, Booked By, Address details, Transport mode, Shipment Status, Events, Pickup date/time, Delivery date/time
Shipment details (by DSV shipment ID – e.g. SCPH1234567, CPHUK-12345, 10123456)
Features: Retrieve detailed shipment data for a specific shipment by searching by the DSV Shipment ID.Data elements: DSV Shipment ID, DSV Booking ID, Booked By, Address details, Transport mode, Shipment Status, Events, Pickup date/time, Delivery date/time
Shipment details (by Customer reference – e.g. PO123546578, ABC12345678)
Features: Retrieve detailed shipment data for a specific shipment, searching by the Customer reference.Data elements: DSV Shipment ID, DSV Booking ID, Booked By, Address details, Transport mode, Shipment Status, Events, Pickup date/time, Delivery date/time.
_________________________________________________________________________________________________________
Webhook: Tracking
Push notification events from DSV to your selected endpoint via the DSV Webhook offering.
Supported transport modes: Air, Sea, Road (EU), Rail.
Supported notification options
Booking summary (Supported for Road, Air, Sea, Rail)
Estimated pickup (Supported for Road, Air, Sea, Rail)
Estimated delivery (Supported for Road, Air, Sea, Rail)
Estimated arrival changed (Supported for Air, Sea, Rail)
Estimated departure changed (Supported for Air, Sea, Rail)
Actual Arrival changed (Supported for Air, Sea, Rail)
Actual departure changed (Supported for Air, Sea, Rail)
Picked up (Supported for Road)
Delivered (Supported for Road)
Supplier booking (Supported for Road, Air, Sea, Rail)
POD Available (Supported for Road)
See more information in the Webhook – Guide.
_________________________________________________________________________________________________________
API: Document download
Download shipment documents from DSV via the Document Download API.
Supported transport modes: Air, Sea, Road (EU), Rail.
The Download API offers three methods for retrieving documents:
Get list of documents on shipment by myDSV booking ID
Get list of documents on shipment by myDSV Shipment ID
Download a specific document with URL provided in list of documents
Document types which can be provided if available on the shipment:
Proof of delivery (POD)
Commercial Invoice
Other goods documents
Customs declaration
Dangerous goods documents
Packing list
House bill of lading
It is possible to set a filter to only retrieve POD documents.
We recommend using our Webhook offering to be notified when Road POD documents are available.
_________________________________________________________________________________________________________
API: Document Upload
The document upload API enables you to upload documents to your shipment via a digital flow.
Supported transport modes: Air, Sea, Road (EU), Rail.
The document upload API offers two methods for uploading documents:
Upload attachment by DSV Booking ID
Upload a document directly via API by providing the DSV Booking ID as key.Upload attachment by DSV Shipment ID
Upload a document directly via API by providing the DSV Shipment ID as key.
For both methods it is mandatory to provide the document type. These are the available types:
CUS - Customs declaration
GDS - Other goods document
HAZ - Dangerous goods document
INV - Commercial invoice
PKL - Packing list
Please be aware that
It is not possible to delete documents which have been uploaded via the API to DSV
All files are scanned for antimalware
Maximum file size is 3MB
_________________________________________________________________________________________________________
API: Visibility
Retrieve or subscribe to live tracking data from DSV visibility.
Supported transport modes: Air, Sea, Rail and Xpress.
Access to visibility tracking data is only possible through devices purchased from DSV attached to your shipment.
The Visibility API offers below method to obtain device information:
GetDeviceDataReadings (by DSV shipment ID – e.g., SCPH1234567 or CPHUK-12345)
Features: Retrieve device data for a specific shipment by searching by the DSV Shipment ID. Gain valuable insights into the status and conditions of your shipment during transit.
_________________________________________________________________________________________________________
API: Invoice
Obtain invoice data via the API and Webhook.
API: Invoice list
Retrieve a list of DSV invoices including the invoice data via the Invoice list API
Supported transport modes: Air, Sea, Rail
The following filter options are possible:
"countryCode": "DK",
"transportMode": "Road",
"mdm": "64987654",
"invoiceStartDateFilter": "2020-01-01",
"invoiceEndDateFilter": "2021-01-01",
"invoiceDueDateStartFilter": "2021-01-01",
"invoiceDueDateEndFilter": "2021-01-01",
"pageSize": "10"
The default filter is past 30 days.
Pagination: The endpoints return paginated responses. The response object contains elements of the current page, and links to the previous and next page. Pagination in the example above is done with 10 per response provided by the API.
API: Invoice by Invoice Id
Retrieve a specific DSV invoice based on the DSV Invoice ID
Supported transport modes: Air, Sea, Rail
API: Invoice by Customer Reference
Retrieve a specific DSV invoice based on the customer reference.
Supported transport modes: Air, Sea, Rail
API: Invoice by Shipment Id
Retrieve a specific DSV invoice based on the DSV shipment ID
Supported transport modes: Air, Sea, Rail
API: Invoice PDF by DSV Invoice Id
Retrieve the DSV invoice pdf based on the DSV Invoice ID
Supported transport modes: Air, Sea, Rail
DEMO Environment
To test the Invoice APIs or Webhook our demo environment will provide a generic response with invoice test data.
_________________________________________________________________________________________________________
API: Webhook
Manage real-time notifications and subscriptions to key events related to Invoice and Visibility with DSV's Webhook API
Supported Operations:
Subscribe to events: Register an endpoint to receive notifications for Invoice, Shipment Device Reading, and Delivery Receipt events.
Unsubscribe from events: Stop receiving notifications for specific events.
Retrieve active subscriptions: Access a list of all active event subscriptions.
Data Elements:
SubscriptionEvent: The event type (e.g., Invoice, ShipmentDeviceReading, ShipmentDeliveryReceipt).PushUrl: URL for event notifications.AuthenticationData: OAuth token or credentials.Headers: Optional headers for communication.
Requirements:
Include OAuth token in the Authorization header.
Ensure
PushUrlis accessible for event delivery.
_________________________________________________________________________________________________________
Authentication
The available APIs are using a combination of two authentication methods to ensure a secure connection to DSV, as briefly described in the following:
Here is a link a video with instructions on how to get the credentials for DSV-Service-Auth and DSV-Subscription-Key.
(If you are using Safari then please download the video instead)
Authentication methods
API key (HTTP header: DSV-Subscription-Key)
This key is obtained by subscribing to the API as described in the ‘Developer Guide’.
The key can be found in the DSV Developer portal profile page once the subscription request is approved by DSV.
2 keys are allocated per subscribed product, a “primary key” and a “secondary key”. Only one key (either primary key or secondary key) should be used in the HTTP header “DSV-Subscription-Key”.
Sample key structure: b5c09b92fbf24d62a17caad22227c470
System account (HTTP header: DSV-Service-Auth)
For security reasons, you will need to have an active account at DSV. When subscribing to the test API, a user email address and password will be provided by DSV which must be used during tests. In case you haven’t received the credentials latest one business day after the subscription was approved by DSV, please do not hesitate to contact support at SUPPORT.
The system account is using HTTP Basic authentication and all requests must contain the HTTP request header:
DSV-Service-Auth: Basic base64(myDSV-demo-user-email:password)
Note: remember to encode user email and password as base64
** OAuth
_________________________________________________________________________________________________________
Login credentials for online portals
When developing against the generic APIs, 2 online portals are made available for supporting the development process.
DSV Developer portal
Main portal for DSV’s APIs covering the API catalogue, technical documentation, developer guides and subscriptions for the different APIs.
The API key (HTTP header: DSV-Subscription-Key) is found on the profile page of the portal.
Login credentials are selected by the user when signing up to the portal.
myDSV demo portal
Online booking and tracking portal where bookings submitted via the test booking API is visible. It is recommended to use the demo portal to verify if the information submitted via the APIs are correctly received by DSV.
Login credentials are provided via email shortly after the first subscription request is sent. Any additional subscription you request for the generic APIs will fall under the same set of credentials.
_________________________________________________________________________________________________________
Postman Collections
To facilitate easy development and testing Postman collections for each endpoint have been created: