Introduction

A booking represents the collection and delivery of goods for a logstics customer. A single booking may be either Part Load or Full Load. A full load booking always has a single subbooking representing a collection and delivery. A part load booking may have one or more subbookings.

Booking Details

Details about a specific booking can be found at the following API endpoint. Retrieving booking details requires the ViewBooking feature access. You may notice additional undocumented attributes on the booking model. Do not use or rely on these attributes, as they will be deprecated.

GET https://logisticsapi.dfds.com/api/booking/{bookingId}

The booking model is an Entity Tree model. Please refer to the entity tree documentation for additional details.

Attributes

Name Description Type
state The current state of the booking. Booking State
customerReference

Optional customer reference for the booking.

Do not use this for system integration! The customer reference may be changed by DFDS, and thus should not be used for integrations. Use the booking ID instead.

string
customerRemarks Optional customer remarks for the booking. string
loadType The type of load represented by the booking
1: Full Load, 2: Partial Load/Groupage 		number
customCode The customs code applicable to the booking Customs Code
transportTerm The transport terms agreed for the booking. Transport Terms
isNeutralDelivery Indicates whether the booking should be considered neutral for delivery. This will hide collection deltails for the receiver. boolean
rejectReason A human readable reason for a booking rejection. This value is present only if the booking is in Rejected state. string
externalId An optional unique id for the booking provided by the initial booking creator string
customer The customer which owns this booking. Company Associate
shipper The name and location of the shipper. This value is optional. Freight Location
consignee The name and location of the consignee. This value is optional. Freight Location
requestedEquipmentType The type of carry equipment requested for this booking. This value is optional. Equipment Type
serviceLevels The service levels attached to this booking. This value is optional. Service Levels
subBookings The list of SubBookings included in this booking. SubBooking
consignment The consignment attached to the booking. This value is optional. Consignment
Booking State

Bookings can be created in either Draft or AwaitingApproval state. If a booking is created in draft state it must be submitted before entering AwaitingApproval state. "AwaitingApproval"-bookings will be reviewed by DFDS and be either Approved or Rejected. Booking details may be amended by DFDS when the booking is approved. If a booking is cancelled after it has been approved, it will get a Cancelled status.

Name Description Value
Draft The booking is saved as a customer draft only and will not be considered by DFDS. 1
AwaitingApproval The booking has been submitted and will be reviewed by DFDS. 2
Approved The booking has been approved by DFDS. 3
Rejected The booking has been rejected by DFDS. 4
Cancelled The booking has been cancelled. 5
Customs Code

The customs code.

Name Description Value
NotSet Not Set 0
None None 1
Communitarian Communitarian 2
T1 External Community Transit Procedure. 3
T2 Internal Community Transit Procedure. 4
T5 European Community Transit Document. 5
T2Export Internal Community Transit Procedure + Export. 6
Transport Terms

The Booking Incoterms.

Name Description Value Info
NotSet Not Set 0
EXW Ex Works 1
FCA Free Carrier 2
FAS Free Alongside Ship 4
FOB Free On Board 8
CFR Cost and Freight 16
CIF Cost, Insurance and Freight 32
CPT Carriage Paid To 64
CIP Carriage and Insurance Paid To 128
(*)DAF Delivered At Frontier 256 Obsolete
(*)DES Delivered Ex Ship 512 Obsolete
(*)DEQ Delivered Ex Quay 1024 Obsolete
(*)DDU Delivered Duty Unpaid 2048 Obsolete
DDP Delivered Duty Paid 4096
DAP Delivered at Place 8192
(*)DAT Delivered at Terminal 16384 Obsolete
DPU Delivered at Place Unloaded 32768

* Info: The Booking Incoterms have been updated as part of the Brexit update 238600 (24-09-2020). Obsolete values cannot be used to create or update a booking. It can only be used when reading historical data.

Inco Terms

A list of all Inco Terms can be retrieved using the following API endpoint.

GET https://logisticsapi.dfds.com/api/booking/AllIncoTerms

All Inco Terms Example

Example of getting all Inco Terms

            
[
  {
    "name": "Delivered Duty Paid",
    "value": 4096,
    "shortName": "DDP",
    "IsObsolete": false
  },
  {
    "name": "Delivered at Place Unloaded",
    "value": 32768,
    "shortName": "DPU",
    "order": 17,
    "IsObsolete": false
  }
  //....

]

SubBooking

A Booking references at least one SubBooking, which is described here. Each SubBooking is composed of collection/delivery details and goods informations.

Name Description Type
name The sequence letter identifying this subbooking within the context of the entire booking. Ex 'A', 'B', 'C' string
collectionAddress The address and time requested for the collection. Booking Address
deliveryAddress The address and time requested for the delivery. Booking Address
goods The list of goods to be transported. Array of Goods
Booking Address

The BookingAddress type specifies location and time details.

Name Description Type
addressType The type of address. Can either be collection (0) or delivery (1). number
freightLocation The location of the collection or delivery. Freight Location
requestedDate The requested date at the collection/delivery location. Ex: "2018-05-29" date
requestedFromTimeDate The start date interval requested for collection/delivery in the time zone of the location. Ex: "2018-05-29" date
requestedFromTime The start time interval requested for collection/delivery in the time zone of the location. Ex: "14:00" time
requestedToTimeDate The end date interval requested for collection/delivery in the time zone of the location. Ex: "2018-05-29" date
requestedToTime The end time interval requested for collection/delivery in the time zone of the location. Ex: "17:00" time
Goods

Goods details includes the following information

Name Description Type
subQuantities Detail of Sub quantities for goods. Array of Sub Quantities
quantity The number of {packageType}. number
quantityOnFloor The amount of the quantity that can be placed on the floor. number
packageType The type of packaging used for the goods Package Type
packagingProvider The packaging provider that provides the package type for this goods line Packaging Provider
description A human readable description of the goods. string
grossWeight The gross weight of the goods in KGS number
nettoWeight The netto weight of the goods in KGS number
loadMetres The number of loading meters occupied by the goods. number
cubicMetres The physical size occupied by the goods in m3 number
length The length of the goods in meters number
width The width of the goods in meters number
height The height of the goods in meters number
temperature The temperature in Celsius at which the goods must be transported. This value is optional. number
temperatureRange The temperature range that is wanted Temperature range
imoUNDG The hazardous UN Code string

Customs related goods fields.

Name Description Type
invoiceNumber The number of the commercial invoice. string
invoiceValue The value of the commercial invoice. number
invoiceCurrency The currency code of the commercial invoice. Ex: 'DKK' or 'GBP' string
invoiceDate The commercial invoice date. Ex: "2019-03-31" number
commodityCode The commodity code of the goods. string
exportLicenseCode The export license code of the goods. string
licenseNumber The license number of the goods. string
marksAndNumbers The symbols used to identify different pieces of cargo. string
countryOfOrigin The country of origin for customs. Country
referenceNumber The reference number for customs. string
supplementaryUnits The supplementary units for customs. number
customsProcedureCode The customs procedure code applied for customs. Customs Procedure Code
Temperature Ranges
Name Description Type
id The id of the object. When sending back which temperature range, only this is needed. number
minTemp Minimum temperature of the range. number
maxTemp Maximum temperature of the range. number
Customs Procedure Code

Customs Procedure Codes (CPC) are used to identify the Customs regimes to which goods are being entered and from which they have been removed. The CPC signals to the system whether the declaration is for an import, an export, transit, or any other circumstance possible in a Customs environment. The Code identifies to the system how the data input from the declaration is to be handled and how the declaration is to be processed.

Name Description Type
code The customs procedure code string
description The description of customs procedure code. string

Booking Example

Example of simple booking with a single sub booking.

        
{
  "$id": "1",
  "state": 3,
  "customerReference": "Remarks",
  "customerRemarks": "Customer Remarks",
  "loadType": 1,
  "customCode": 0,
  "transportTerm": 0,
  "isNeutralDelivery": false,
  "rejectReason": null,
  "customer": {
    "$id": "2",
    "name": "Customer Name",
    "number": 1234,
    "isBookingReferenceRequired": false,
    "address": {
      "$id": "3",
      "streetName": "Streename",
      "houseNumber": "7",
      "pOBox": null,
      "addressLine2": null,
      "addressLine3": null,
      "addressLine4": null,
      "postalCode": "1234",
      "city": "City",
      "county": null,
      "country": {
        "$id": "4",
        "code": "DK",
        "longCode": "DEN",
        "euCountryCode": "DK",
        "numericCode": 45,
        "name": "Denmark",
        "nationalityName": "Danish",
        "id": 2,
        "concurrencyToken": "AAAAAAA6E4w="
      },
      "id": 661,
      "concurrencyToken": "AAAAAAcV9JM="
    },
    "id": 661,
    "concurrencyToken": "AAAAAEMPjLk="
  },
  "shipper": null,
  "consignee": null,
  "requestedEquipmentType": null,
  "subBookings": [
    {
      "$id": "6",
      "name": "A",
      "collectionAddress": {
        "$id": "7",
        "requestedDate": "2018-01-31T00:00:00",
        "addressType": 0,
        "freightLocation": {
          "$id": "8",
          "isLoadingPoint": true,
          "isUnLoadingPoint": true,
          "name": "LocationName",
          "address": {
            "$id": "9",
            "streetName": "Street",
            "houseNumber": "5",
            "pOBox": null,
            "addressLine2": "",
            "addressLine3": "",
            "addressLine4": "",
            "postalCode": "1234",
            "city": "City",
            "county": "",
            "country": { "$ref": "4" },
            "id": 1695,
            "concurrencyToken": "AAAAAAcV9PY="
          },
          "state": 2,
          "id": 477,
          "concurrencyToken": "AAAAAC/cNpA="
        },
        "requestedFromTime": null,
        "requestedToTime": null,
        "id": 7248716,
        "concurrencyToken": "AAAAAEMqnoo="
      },
      "deliveryAddress": {
        "$id": "10",
        "reference": "1234",
        "requestedDate": "2018-02-01T00:00:00",
        "addressType": 1,
        "freightLocation": {
          "$id": "11",
          "isLoadingPoint": true,
          "isUnLoadingPoint": true,
          "name": "LocationName",
          "address": {
            "$id": "12",
            "streetName": "Street",
            "houseNumber": "165",
            "pOBox": null,
            "addressLine2": "",
            "addressLine3": "",
            "addressLine4": "",
            "postalCode": "1234",
            "city": "City",
            "county": "",
            "country": {
              "$id": "13",
              "code": "FR",
              "longCode": "FRA",
              "euCountryCode": "FR",
              "numericCode": 250,
              "name": "France",
              "nationalityName": "French",
              "id": 9,
              "concurrencyToken": "AAAAAABAVOA="
            },
            "id": 1759,
            "concurrencyToken": "AAAAAAjXPCs="
          },
          "state": 2,
          "id": 541,
          "concurrencyToken": "AAAAAAjXPCw="
        },
        "requestedFromTime": "06:00:00",
        "requestedToTime": "06:00:00",
        "id": 7248717,
        "concurrencyToken": "AAAAAEMqnow="
      },
      "goods": [
        {
          "$id": "14",
          "quantity": 25,
          "description": "FOOD",
          "grossWeight": 24941.0,
          "nettoWeight": 0.0,
          "loadMetres": 0.0,
          "cubicMetres": 0.0,
          "temperature": null,
          "length": null,
          "width": null,
          "height": null,
          "packageType": {
            "$id": "15",
            "code": "PLT",
            "name": "Pallets",
            "id": 16,
            "concurrencyToken": "AAAAAB2lxj6="
          },
          "packagingProvider": {
            "$id": "16",
            "name": "provider name",
            "id": 15
          },
          "subQuantities": [
            {
              "description": "packed sub quantity",
              "grossWeight": 12.0,
              "netWeight": 9.0,
              "cubicMetres": 1.0,
              "reference": "reference detail",
              "quantity": 11,
              "packageType": {
                "id": 4
              },
              "packagingProvider": {
                "id": 1
              },
              "id": 25597
            }
          ],
          "invoiceValue": 1167.0,
          "invoiceCurrency": "DKK",
          "invoiceDate": "2018-07-27T00:00:00",
          "commodityCode": "",
          "invoiceNumber": "",
          "exportLicenseCode": "",
          "licenseNumber": "",
          "marksAndNumbers": "",
          "countryOfOrigin": {
            "$id": "14",
            "code": "DK",
            "longCode": "DNK",
            "euCountryCode": "DK",
            "numericCode": 208,
            "name": "Denmark",
            "supplierSundryCode": null,
            "nationalityName": "Danish",
            "id": 6,
            "concurrencyToken": "AAAAAAA6GM4="
          },
          "supplementaryUnits": "",
          "customsProcedureCode": {
            "$id": "1",
            "code": "10 00 001",
            "description": "10 00 001",
            "concurrencyToken": "AAAAAB2lxj8="
          },
          "id": 4869404,
          "concurrencyToken": "AAAAAEKlrAU="
        }
      ],
      "id": 3776011,
      "concurrencyToken": "AAAAAEMs+eQ="
    }
  ],
  "externalId": "MG2345GH234",
  "id": 3470199,
  "concurrencyToken": "AAAAAEMs+d8="
}

Freight Locations

Freight locations is a general concept used throughout the API when working with addresses. It may refer to a delivery/collection address, a warehouse or a vessel terminal. A freight location is an entity type. The same freight locations may be referenced many times, typically for many different subbookings.

A list of available FreightLocations can be found at the following endpoint.

GET https://logisticsapi.dfds.com/api/booking/freightlocations

If the required address is not available in this list, a new address may be created as part of booking creation

Attributes

The set of attributes applicable to a freight location is described here. Entity related properties (id, concurrencyToken) etc. are not included in the table. Please refer to the entity tree documentation for details about these properties.

Name Description Type
isLoadingPoint Gets or sets a value indicating whether the address is a loading point boolean
isUnLoadingPoint Gets or sets a value indicating whether the address is a unloading point boolean
name The name associated with this location. Example "DFDS Hourse" or "Esbjerg Terminal" string
state The current state of the address. See the Freight Location Flow section for details. number
address The address of the freight location Address

Address

The address referenced from a freight location is described here. A single address instance can only ever be referenced by a single freight location.

Name Description Type
streetName The name of the street. Ex: Sundkrogsgade string
houseNumber The house number of the street. Ex "1" or "1A." string
pOBox The post office box number if applicable. string
addressLine2-4 Additional address lines if applicable string
postalCode The postal code. Ex "2100" string
city The name of the city in English or local language at the location. Ex "Copenhagen" or "København" string
county The name of the county if applicable string
country The county in which the adress is located Country
Country

All addresses share the same set of countries which are referenced by id. A country is defined by the following set of attributes.

Name Description Type
code The ISO 3166-1 alpha-2 code representing the country string
longCode The ISO 3166-1 alpha-3 code representing the country string
euCountryCode The EU country code representing the country. This value is null for countries outside the EU string
numericCode The ISO 3166-1 numeric code representing the country number
name The name of the country in english. Ex "Denmark" string
nationalityName The name of the nationality in english. Ex "Danish" string

When referencing a specific Country use the following endpoint to determine the proper corresponding Id.

GET https://logisticsapi.dfds.com/api/booking/countries

Freight Location Flow

New freight locations must be validated by DFDS. They are validated when submitted along with a booking.

Name Description Value
Received The location is currently awaiting approval by DFDS 1
Approved The location has been validated and can be reused without further validation. 2
Draft The location is saved as a customer draft only and will not be considered by DFDS. 3

Related Types

In this section you will find documentation of miscellaneous types used in the API.

Company Associate

This entity represents the customer. It is populated automatically in responses when calling endpoints on the API.

Name Description Type
name The name of the associate. string
organizationRegistrationNumber The associate organization registration number. string
number The associate number. number
EoriNumber The Economic Organization Registration number. string
isBookingReferenceRequired Value indicating whether a booking reference is required. boolean
address Address of the associate. Address
externalId External id for this associate. string

Equipment Type

The requested equipment type of the booking is described here.

Name Description Value
name The equipment type name. Ex "TRATIR" string
description The equipment type description. Ex "EurolinerTIR" string

When referencing a specific EquipmentType use the following endpoint to determine the proper corresponding Id.

GET https://logisticsapi.dfds.com/api/booking/equipmenttypes

Package Type

Goods package type

Name Description Value
code The package type code. Ex "EUPS2" string
name The package type name. Ex "EuroPalletsStackable(2levels)" string
isStackable The package type is stackable or not. boolean

When referencing a specific PackageType use the following endpoint to determine the proper corresponding Id.

GET https://logisticsapi.dfds.com/api/booking/packagetypes

Packaging Provider

Represents an actor leasing packaging material i.e. PackageTypes to another actor.

Name Description Value
name The packaging provider name. string
providedPackageTypes The package types this provider offers. PackageTypes

When referencing a specific PackagingProvider use the following endpoint to determine the proper corresponding Id.

GET https://logisticsapi.dfds.com/api/booking/packagingproviders

Sub Quantities

Represents sub quantity for goods.

Name Description Value
description A human readable description of a sub quantity. string
grossWeight The gross weight of the sub quantity in KGS. number
netWeight The net weight of the sub quantity in KGS. number
cubicMetres The physical size occupied by the sub quantity in m3. number
reference The reference detail of the sub quantity. string
quantity The quantity of a sub quantity. number
packageType The type of packaging used for the sub quantity. PackageTypes
packagingProvider The packaging provider that provides the package type for this sub quantity. Packaging Provider

When referencing a specific PackagingProvider use the following endpoint to determine the proper corresponding Id.

GET https://logisticsapi.dfds.com/api/booking/packagingproviders

Service Levels

This entity represents the various service levels that can be attached to a booking.

Name Description Type
name Name of the service level string
code Unique code used to identify service level string

Booking Flow

Bookings can be created in either Draft or Received state. If a booking is created in draft state it must be submitted before entering Received state. Received bookings will be reviewed by DFDS and be either Approved or Rejected. Booking details may be amended by DFDS when the booking is approved. If a booking is cancelled after it has been approved, it will get a Cancelled status.

Notifications

Booking approval, rejection and withdrawal support Notification Hooks. A notification hook must be setup for each specific event type. The content posted for these notification hooks is identical to the content received from the Booking Details API.

EventType Description
Booking Received Triggerd when a booking has been submitted for approval.
Booking Approved Triggered when a booking has been approved.
Booking Rejected Triggered when a booking is rejected. The booking contains a message indicating the reason for rejection. The booking can be ammended and re-submitted.
Booking Withdrawn Triggered when a received booking is withdrawn by the customer before it has been approved by DFDS.
Booking Cancelled Triggered when an approved booking is cancelled.

Creating and updating bookings

The booking create and update API's are EntityTree API's. This implies many rules about object reference etc. Please familiarize yourself with the entity tree concept before continuing.

The booking data format is explained in the Booking Details section.

Creating a new booking

A new booking can be created using the following endpoint. Bookings may be created in Draft or AwaitingApproval state.

This API requires the CreateBooking feature access

POST https://logisticsapi.dfds.com/api/booking/create

Example 1

This example shows how to create a simple booking in the AwaitingApproval state with a single sub booking. Most optional attributes are left out. The Customer field is also omitted, since it is extracted from the identity of the caller. The example also shows how to create new FreightLocations, in this case in state 2 (Received). 

            
{
  "state": 2,
  "customerReference": "TestCustomerReference",
  "customerRemarks": "Customer Remarks",
  "loadType": 1,
  "customCode": 5,
  "transportTerm": 4,
  "isNeutralDelivery": false,
  "shipper": null,
  "consignee": null,
  "subBookings": [
    {
      "name": "A",
      "collectionAddress": {
        "requestedFromTimeDate": "2018-05-29",
        "requestedToTimeDate": "2018-05-29",
        "requestedDate": "2018-05-29",
        "serviceLevels": [
          {
            "name": "Barge",
            "code": "Barge"
          }
        ],
        "addressType": 0,
        "freightLocation": {
          "isLoadingPoint": true,
          "isUnLoadingPoint": true,
          "name": "DFDS LOGISTICS TEST",
          "address": {
            "streetName": "Middleton Avenue",
            "houseNumber": "17",
            "pOBox": null,
            "addressLine2": "Strutherhill Ind Est",
            "addressLine3": null,
            "addressLine4": null,
            "postalCode": "ML9 2TL",
            "city": "Larkhall",
            "county": null,
            "country": {
              "code": "GB"
            }
          }
        },
        "requestedFromTime": "10:40",
        "requestedToTime": "11:50"
      },
      "deliveryAddress": {
        "requestedFromTimeDate": "2018-05-31",
        "requestedToTimeDate": "2018-05-31",
        "requestedDate": "2018-05-31",
        "addressType": 1,
        "freightLocation": {
          "isLoadingPoint": true,
          "isUnLoadingPoint": true,
          "name": "DFDS LOGISTICS - BOULOGNE SUR MER TEST",
          "address": {
            "streetName": "Rue Alexandre Adam",
            "houseNumber": "11",
            "pOBox": null,
            "addressLine2": "Gare de Marée",
            "addressLine3": null,
            "addressLine4": null,
            "postalCode": "62200",
            "city": "Boulogne-sur-Mer",
            "county": null,
            "country": {
              "code": "FR"
            }
          }
        },
        "requestedFromTime": "05:30:00",
        "requestedToTime": "06:10:00"
      },
      "goods": [
        {
          "subQuantities": [
            {
              "description": "description of the sub quantity",
              "grossWeight": 12.0,
              "netWeight": 9.0,
              "cubicMetres": 1.0,
              "reference": "reference detail for the sub quantity",
              "quantity": 11,
              "packageType": {
                "id": 4
              },
              "packagingProvider": {
                "id": 1
              }
            }
          ],
          "quantity": 11,
          "description": "desc",
          "grossWeight": 1200,
          "nettoWeight": 1100,
          "loadMetres": 3,
          "cubicMetres": 3,
          "temperature": 22,
          "length": 2,
          "width": 1,
          "height": 1.5,
          "imoUNDG": "210",
          "packageType": {
            "id": 18
          }
        }
      ]
    }
  ]
}
Example 2

This example is like the above Example 1, but with known/already existing FreightLocations specified by Ids. 

            
{
  "state": 2,
  "customerReference": "TestCustomerReference",
  "customerRemarks": "Customer Remarks",
  "loadType": 1,
  "customCode": 5,
  "transportTerm": 4,
  "isNeutralDelivery": false,
  "shipper": {
    "id": 52640
  },
  "consignee": {
    "id": 4784
  },
  "subBookings": [
    {
      "name": "A",
      "collectionAddress": {
        "requestedFromTimeDate": "2018-05-29",
        "requestedToTimeDate": "2018-05-29",
        "requestedDate": "2018-05-29",
        "addressType": 0,
        "freightLocation": {
          "id": 52640
        },
        "requestedFromTime": "10:40",
        "requestedToTime": "11:50"
      },
      "deliveryAddress": {
        "requestedFromTimeDate": "2018-05-31",
        "requestedToTimeDate": "2018-05-31",
        "requestedDate": "2018-05-31",
        "addressType": 1,
        "freightLocation": {
          "id": 4784
        },
        "requestedFromTime": "05:30:00",
        "requestedToTime": "06:10:00"
      },
      "goods": [
        {
          "subQuantities": [
            {
              "description": "description of the sub quantity",
              "grossWeight": 12.0,
              "netWeight": 9.0,
              "cubicMetres": 1.0,
              "reference": "reference detail for the sub quantity",
              "quantity": 1,
              "packageType": {
                "id": 4
              },
              "packagingProvider": {
                "id": 1
              }
            }
          ],
          "quantity": 1,
          "description": "desc",
          "grossWeight": 1200,
          "nettoWeight": 1100,
          "loadMetres": 3,
          "cubicMetres": 3,
          "temperature": 22,
          "length": 2,
          "width": 1,
          "height": 1.5,
          "imoUNDG": "210",
          "packageType": {
            "id": 18
          }

        }
      ]
    }
  ]
}

When referencing a FreightLocation by Id, use the following endpoint to list available FreightLocations.

GET https://logisticsapi.dfds.com/api/freightlocations

Example 3

This example is like the above Example 2, but with hazardous related properties can be set for a particular good. These values should only be set if the value for hazardous is true. 

            
{
  "state": 2,
  "customerReference": "TestCustomerReference",
  "customerRemarks": "Customer Remarks",
  "loadType": 1,
  "customCode": 5,
  "transportTerm": 4,
  "isNeutralDelivery": false,
  "subBookings": [
    {
      "name": "A",
      "collectionAddress": {
        "requestedFromTimeDate": "2018-05-29",
        "requestedToTimeDate": "2018-05-29",
        "requestedDate": "2018-05-29",
        "addressType": 0,
        "freightLocation": {
          "id": 52640
        },
        "requestedFromTime": "10:40",
        "requestedToTime": "11:50"
      },
      "deliveryAddress": {
        "requestedFromTimeDate": "2018-05-31",
        "requestedToTimeDate": "2018-05-31",
        "requestedDate": "2018-05-31",
        "addressType": 1,
        "freightLocation": {
          "id": 4784
        },
        "requestedFromTime": "05:30:00",
        "requestedToTime": "06:10:00"
      },
      "goods": [
        {
          "subQuantities": [
            {
              "description": "description of the sub quantity",
              "grossWeight": 12.0,
              "netWeight": 9.0,
              "cubicMetres": 1.0,
              "reference": "reference detail for the sub quantity",
              "quantity": 3,
              "packageType": {
                "id": 4
              },
              "packagingProvider": {
                "id": 1
              }
            }
          ],
          "quantity": 3,
          "quantityOnFloor": 1,
          "description": "desc",
          "grossWeight": 1200,
          "nettoWeight": 1100,
          "loadMetres": 3,
          "cubicMetres": 3,
          "temperature": 22,
          "length": 2,
          "width": 1,
          "height": 1.5,
          "hazardous": true,
          "imoLimitedQantity": false,
          "imoBulk": false,
          "imoResidues": false,
          "imoMarinePollutant": false,
          "imoUNDG": "210",
          "imoClass": false,
          "imoSubClass": false,
          "imoEMS": false,
          "imoNEC": false,
          "imoComment": "comment on hazardous",
          "imoFlashPoint": "desired flash point value",
          "imoNetWeight": 20,
          "imoGrossweight": 19,
          "imoPackingGroup": "3",
          "imoStowageCategory": "2",
          "imoPackageType": "IBC",
          "imoNoPkgs": "2",
          "imoProductName": "special bags",
          "imoTechnicalName": "hazardous technical name",
          "packageType": {
            "id": 18
          }
        }
      ]
    }
  ]
}

Submitting or withdrawing a booking

If a booking is awaiting approval, it may be withdrawn by you. When a booking is withdraw, it enters Draft state. Draft bookings are not considered by DFDS, and are available for your reference only. You may update a draft booking and submit it again. If the booking has already been approved, it cannot be withdrawn.

This API requires the EditBooking feature access

POST https://logisticsapi.dfds.com/api/booking/{bookingId}/withdraw

Draft bookings must be submitted before they are considered by DFDS. Use the following endpoint to submit a booking for approval. The booking will be in AwaitingApproval state after this operation.

POST https://logisticsapi.dfds.com/api/booking/{bookingId}/submit

Updating a booking

This API requires the EditBooking feature access

If required, you can update a booking after it has been created. It is only possible to update the booking while in Draft state. See the submit/withdraw section for details on how to get your booking back to draft state if required.

POST https://logisticsapi.dfds.com/api/booking/update

Example

Example of how to update customerReference and sub quantity for the specified booking.

            
{
  "customerReference": "TestCustomerReference2",
  "id": 3909262
}

Submitting Border Compliance Data

DFDS provides seperate endpoints for submitting and editing data related for border compliance like ICS2. See ICS2 Information

The data that can be submitted for conforming to the border compliance requirements in question are named "Shipment" and "ShipmentItems".
"Shipment" are data related to seller and buyer information for the current shipment where as the individual shipmentitems contains data related to the actual shipments like grossweight and commodity code. A "Shipment" does always have a direct reference to a subbooking. A "Shipment" can contain multiple "ShipmentItems".

Shipment

Represents information about the shipment containing seller and buyer.

Name Description Value
Id Id for reference when shipment should be updated string
IsApproved Shows that a shipment has been approved. bool
Seller Information about the Seller for the shipment - see info below about Seller property details. Seller/Buyer DTO
Buyer Information about the Buyer for the shipment - see info below about Buyer property details. Seller/Buyer DTO
ShipmentItems A collection of ShipmentItems related to the current Shipment Seller/Buyer DTO

Seller/Buyer

Represents information about Seller and Buyer for a shipment related to a subbooking. Both Seller and Buyer share the same properties listed below. Almost all fields are mandatory. The exception is streetname, housenumber and poBox. Either streetname together with housenumber needs to be filled or PoBox alone.

Name Description Value
Name Name of the seller/buyer. string
City Cityname of the seller/buyer. string
CountryCode The two letter ISO countrycode of the address from the seller/buyer. string
PostalCode PostalCode of the seller/buyer.. string
StreetName The streetname from the address of the seller/buyer. string
HouseNumber The housenumber from the address of the seller/buyer. string
PoBox The PoBox from the address of the seller/buyer. string

Shipment Items

Represents shipment items for goods.

Name Description Value
quantity The quantity of the shipment item. number
grossWeight The gross weight of the shipment item in KGS. number
description A human readable description for the shipment item. string
commodityCode The commodity code for the shipment item. string
packageTypeUNCode The package type UN code of the shipment item. string

Add Shipment

A new Shipment with shipmentitems can be created using the following endpoint.

This endpoint requires the CreateBooking feature access as it also does for creating and managing the booking itself.

POST https://logisticsapi.dfds.com/api/shipments

Example

This example shows how to create a Shipment with one ShipmentItem. Note the all shipments needs to reference a SubBookingId which you will get from the Create Booking Endpoint 

            
                    
{
  "SubBookingId": "12345678",
  "Shipments": [
    {
      "Seller": {
        "Name": "SellerFirstName Lastname",
        "City": "Seller City",
        "CountryCode": "DK",
        "PostalCode": "1234",
        "POBox": "PoBox Example",
        "StreetName": "Streetname example",
        "HouseNumber": "10"
      },
      "Buyer": {
        "Name": "BuyerFirstName Lastname",
        "City": "Buyer City",
        "CountryCode": "GB",
        "PostalCode": "1234",
        "POBox": "PoBox Example",
        "StreetName": "Streetname Example",
        "HouseNumber": "10"
      },
      "ShipmentItems": [
        {
          "Quantity": 1,
          "GrossWeight": 100,
          "Description": "Test description",
          "CommodityCode": "123456",
          "PackageTypeUnCode": "BG"
        }
      ]
    }
  ]
}

Update Shipment

This endpoint is used for updating existing shipments. The shipment should be referenced as a route parameter in the url. It is only possible to edit shipments that have not been approved by DFDS customer service.

PUT https://logisticsapi.dfds.com/api/shipments{shipmentId}

Example
            
                    
{
  "Seller": {
    "Name": "SellerFirstName Lastname",
    "City": "Seller City",
    "CountryCode": "DK",
    "PostalCode": "1234",
    "POBox": "PoBox Example",
    "StreetName": "Streetname example",
    "HouseNumber": "10"
  },
  "Buyer": {
    "Name": "BuyerFirstName Lastname",
    "City": "Buyer City",
    "CountryCode": "GB",
    "PostalCode": "1234",
    "POBox": "PoBox Example",
    "StreetName": "Streetname Example",
    "HouseNumber": "10"
  },
  "ShipmentItems": [
    {
      "Quantity": 1,
      "GrossWeight": 100,
      "Description": "Test description",
      "CommodityCode": "123456",
      "PackageTypeUnCode": "BG"
    }
  ]
}

Update Shipments

This endpoint is used for updating multiple shipments at the same time. For this endpoint you need to pass all details in the body of the request including the subbookingId to where the shipments exist. It is only possible to edit shipments that have not been approved by DFDS customer service.

PUT https://logisticsapi.dfds.com/api/shipments

Example
            
                    
{
  "SubBookingId": "12345678",
  "Shipments": [
    {
      "Seller": {
        "Name": "SellerFirstName Lastname",
        "City": "Seller City",
        "CountryCode": "DK",
        "PostalCode": "1234",
        "POBox": "PoBox Example",
        "StreetName": "Streetname example",
        "HouseNumber": "10"
      },
      "Buyer": {
        "Name": "BuyerFirstName Lastname",
        "City": "Buyer City",
        "CountryCode": "GB",
        "PostalCode": "1234",
        "POBox": "PoBox Example",
        "StreetName": "Streetname Example",
        "HouseNumber": "10"
      },
      "ShipmentItems": [
        {
          "Quantity": 1,
          "GrossWeight": 100,
          "Description": "Test description",
          "CommodityCode": "123456",
          "PackageTypeUnCode": "BG"
        }
      ]
    }
  ]
}

Get Shipments for Booking

This endpoint is a "GET" endpoint for receiving all Shipments for a specific bookingId where the BookingId should be added as a route parameter to the request.

GET https://logisticsapi.dfds.com/api/bookings/{bookingid}/shipments

The below shows an example of how a response would look like

Example
                
                    
{
  "SubBookingId": "12345678",
  "Shipments": [
    {
      "Id": "Id of shipment as string",
      "Seller": {
        "Name": "SellerFirstName Lastname",
        "City": "Seller City",
        "CountryCode": "DK",
        "PostalCode": "1234",
        "POBox": "PoBox Example",
        "StreetName": "Streetname example",
        "HouseNumber": "10"
      },
      "Buyer": {
        "Name": "BuyerFirstName Lastname",
        "City": "Buyer City",
        "CountryCode": "GB",
        "PostalCode": "1234",
        "POBox": "PoBox Example",
        "StreetName": "Streetname Example",
        "HouseNumber": "10"
      },
      "ShipmentItems": [
        {
          "Quantity": 1,
          "GrossWeight": 100,
          "Description": "Test description",
          "CommodityCode": "123456",
          "PackageTypeUnCode": "BG"
        }
      ]
    }
  ]
}

Get Single Shipment

This endpoint is a "GET" endpoint for receiving a single Shipment. You have to pass the ShipmentId in the route for which shipment you want to request.

GET https://logisticsapi.dfds.com/api/shipments/{shipmentid}

The below shows an example of how a response would look like

Example
                
                    {
  "Id": "Id of shipment as string",
  "IsApproved": false,
  "Seller": {
    "Name": "SellerFirstName Lastname",
    "City": "Seller City",
    "CountryCode": "DK",
    "PostalCode": "1234",
    "POBox": "PoBox Example",
    "StreetName": "Streetname example",
    "HouseNumber": "10"
  },
  "Buyer": {
    "Name": "BuyerFirstName Lastname",
    "City": "Buyer City",
    "CountryCode": "GB",
    "PostalCode": "1234",
    "POBox": "PoBox Example",
    "StreetName": "Streetname Example",
    "HouseNumber": "10"
  },
  "ShipmentItems": [
    {
      "Quantity": 1,
      "GrossWeight": 100,
      "Description": "Test description",
      "CommodityCode": "123456",
      "PackageTypeUnCode": "BG"
    }
  ]
}

Remove Shipment

Example

This endpoint is a "DELETE" endpoint that will remove a single shipment. It is only possible to remove shipments that have not been approved by DFDS customer service.

DELETE https://logisticsapi.dfds.com/api/shipments/{shipmentid}

The response for a delete would be either 200 OK or 404 NOTFOUND.

Uploading and downloading booking documents

The booking document upload and download API's can be used for managing booking documents and assigning categories to those documents.

Uploading a new booking document

A new document can be uploaded by using the following endpoint. Uploading is done by posting multipart/form-data to this endpoint, please note that for the time being only one file can be uploaded at a time.
A valid category id can be obtained by calling the category list endpoint.

Size limit There is a size limit for uploaded documents which is set to 10MB per document, documents larger than 10MB will be rejected.

This API requires the Upload / View documents feature access

POST https://logisticsapi.dfds.com/api/booking/{bookingId}/document/category/{categoryId}

Downloading a booking document

A document can be downloaded by using the following endpoint

This API requires the Upload / View documents feature access

GET https://logisticsapi.dfds.com/api/booking/{bookingId}/document/{documentId}

Deleting a booking document

A document can be removed from the booking by using the following endpoint

This API requires the Upload / View documents feature access

DELETE https://logisticsapi.dfds.com/api/booking/{bookingId}/document/{documentId}

Getting a list of documents from a Booking

A list of booking documents can be obtained by using the following endpoint

This API requires the Upload / View documents feature access

GET https://logisticsapi.dfds.com/api/booking/{bookingId}/document

Example

Example of list of documents.

        
[
  {
    "$id": "1",
    "id": 4816795,
    "name": "BookingDoc.pdf",
    "category": "PACK",
    "description": "Packing doc"
  },
  {
    "$id": "2",
    "id": 4816796,
    "name": "Invoice.pdf",
    "category": "CSTMS",
    "description": "This is the invoice"
  }
]

Getting a list of valid document categories.

A list of valid document categories can obtained by calling the following endpoint. A category must be supplied when uploading a document, see Uploading booking documents

This API requires the Upload / View documents feature access

GET https://logisticsapi.dfds.com/api/booking/document/category/list

Example

Example of list of categories.

        
[
  {
    "$id": "1",
    "id": 1,
    "name": "CSTMS",
    "description": "Customs"
  },
  {
    "$id": "2",
    "id": 3,
    "name": "HAZ",
    "description": "Hazardous"
  },
  {
    "$id": "3",
    "id": 4,
    "name": "PACK",
    "description": "Packing list"
  }
]

Creating and updating consignments

The booking consignment API's can be used for managing consignments on bookings.

Creating a new consignment on a booking

A new can be created by using the following endpoint.

This API requires the Create and Update Consignments feature access

POST https://logisticsapi.dfds.com/api/booking/{bookingId}/consignments

Client errors

HTTP/1.1 404 Not Found
If the booking was not found.

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to: view the booking or create consignments.

HTTP/1.1 400 Bad Request
If the provided consignment data is invalid.

HTTP/1.1 400 Bad Request
If the document or goodslines ids represent invalid ids, ids not found on the booking.

See also:
Example

Example of how to create a consignment.

        
{
  "incoTerms": 32,
  "incoTermsPlace":  "Dahm",
  "remarks": "my consignment remarks",
  "goodsLines": [
    6674067
  ],
  "documents": [
    23007
  ],
  "exportDeclaration": {
    "movementReferenceNumber": "myExportMrn",
    "notes": "Notes and remarks",
    "responsibility": "DFDS"
  },
  "importDeclaration": {
    "movementReferenceNumber": "myImportMrn",
    "notes": "Notes and remarks",
    "responsibility": "DFDS"
  },
  "exitSummaryDeclaration": {
    "movementReferenceNumber": "myExitMrn",
    "notes": "Notes and remarks"
  },
  "entrySummaryDeclaration": {
    "movementReferenceNumber": "myEntryMrn",
    "notes": "Notes and remarks"
  },
  "shipper": { "EoriNumber": "BE0402778345" },
  "consignee": { "EoriNumber": "NL003069345" },
  "ConsignmentDeclarationItems": [
    {
      "description": "desc string",
      "quantity": 10,
      "packageTypeUNCode": "PK",
      "grossWeight": 990,
      "nettoWeight": 99,
      "hazardous": true,
      "invoiceValue": 1,
      "invoiceCurrency": "DKK",
      "invoiceDate": "2021-10-07T13:48:14.282Z",
      "commodityCode": "string",
      "invoiceNumber": "curzio1523",
      "exportLicenseCode": "string",
      "licenseNumber": "string",
      "marksAndNumbers": "string",
      "countryOfOriginUNCode": "IT",
      "supplementaryUnits": 0,
      "lic99": true,
      "cpc": "string",
      "preferentialOrigin": true,
      "vatRate": 100,
      "meursingCode": "string",
      "healthCertificateNumber": "string",
      "chedNumber": "string",
      "rexNumber": "string",
      "authorisationNumber": "string",
      "importCustomsProcedureCode": "string",
      "exportCustomsProcedureCode": "string",
      "transportCostAmount": 0,
      "transportCostCurrency": "DKK",
      "supplementaryUnitCode": "CBM",
      "additionalCodes": "NPR"
    },
    {

      "description": "desc string",
      "quantity": 10,
      "packageTypeUNCode": "PK",
      "grossWeight": 990,
      "nettoWeight": 99,
      "hazardous": true,
      "invoiceValue": 0,
      "invoiceCurrency": "DKK",
      "invoiceDate": "2021-10-07T13:48:14.282Z",
      "commodityCode": "string",
      "invoiceNumber": "curzio1523",
      "exportLicenseCode": "string",
      "licenseNumber": "string",
      "marksAndNumbers": "string",
      "countryOfOriginUNCode": "IT",
      "supplementaryUnits": 0,
      "lic99": true,
      "cpc": "string",
      "preferentialOrigin": true,
      "vatRate": 100,
      "meursingCode": "string",
      "healthCertificateNumber": "string",
      "chedNumber": "string",
      "rexNumber": "string",
      "authorisationNumber": "string",
      "importCustomsProcedureCode": "string",
      "exportCustomsProcedureCode": "string",
      "transportCostAmount": 0,
      "transportCostCurrency": "DKK",
      "supplementaryUnitCode": "CBM",
      "additionalCodes": "NPR"
    }

  ]
}
Notes
  • You can leave out individual declarations, but please note they will still be added on the consignment returned.
  • You can leave out individual fields on the consignment like the remarks and incoTerms.
  • You cannot remove declarations from a consignment

Updating a consignment on a booking

A consignment can be updated by using the following endpoint

This API requires the Create and Update Consignments feature access

PUT https://logisticsapi.dfds.com/api/booking/{bookingId}/consignments/{consignmentId}

Client errors

HTTP/1.1 404 Not Found
If the booking was not found.

HTTP/1.1 404 Not Found
If the consignment was not found.

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to: view the booking or update consignments.

HTTP/1.1 400 Bad Request
If the provided consignment data is invalid.

HTTP/1.1 400 Bad Request
If the document or goodslines ids represent invalid ids, ids not found on the booking.

See also:
Example

Example of how to update a consignment.

        
{
  "remarks": "my consignment remarks, updated",
  "exportDeclaration": {
    "movementReferenceNumber": "myExportMrnUpdated",
    "notes": "Notes and remarks",
    "responsibility": "DFDS"
  }
}
Notes
  • Please note that only supplied declarations gets updated on the consignment, in this example we left out other declarations types, goods and documents.
  • To Remove previously added documents or goods, you must post the update with only the relevant id's included.
  • You cannot remove declarations from a consignment, if unwanted values were previously added then submit a new update with the values cleared.

Deleting a consignment form a booking

A consignment can be removed from the booking by using the following endpoint

This API requires the Create and Update Consignments feature access

Client errors

DELETE https://logisticsapi.dfds.com/api/booking/{bookingId}/consignments/{consignmentId}

HTTP/1.1 404 Not Found
If the booking was not found.

HTTP/1.1 404 Not Found
If the consignment was not found.

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to: view the booking or delete consignments.

See also:

Getting a list of consignments from a Booking

A list of consignments can be obtained by using the following endpoint

This API requires the View Consignments feature access

GET https://logisticsapi.dfds.com/api/booking/{bookingId}/consignments

Client errors

HTTP/1.1 404 Not Found
If the booking was not found.

HTTP/1.1 404 Not Found
If the consignment was not found.

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to: view the booking or update consignments.

See also:
Example

Example of how to get a list of consignments.

        
[
  {
    "$id": "1",
    "id": 16,
    "incoTerms": 0,
    "incoTermsPlace":  "This is incoTerms place",
    "remarks": "This is remarks for the consignment",
    "goodsLines": [
      6674066,
      6674067
    ],
    "documents": [
      23007,
      23008
    ],
    "exportDeclaration": {
      "$id": "2",
      "id": 60,
      "movementReferenceNumber": "MyExportMrn",
      "access": 0,
      "notes": "Notes and remarks",
      "responsibility": "Customer"
    },
    "importDeclaration": {
      "$id": "3",
      "id": 61,
      "movementReferenceNumber": "MyImportMrn",
      "access": 0,
      "notes": "Notes and remarks",
      "responsibility": "DFDS"
    },
    "exitSummaryDeclaration": {
      "$id": "4",
      "id": 59,
      "movementReferenceNumber": null,
      "access": 0,
      "notes": "Notes and remarks"
    },
    "entrySummaryDeclaration": {
      "$id": "5",
      "id": 62,
      "movementReferenceNumber": "MyEntrySummaryMrn",
      "access": 0,
      "notes": "Notes and remarks"
    }
  },
  {
    "$id": "6",
    "id": 17,
    "incoTerms": 0,
    "incoTermsPlace": "This is incoTerms place",
    "remarks": null,
    "goodsLines": [
      6674068
    ],
    "documents": [
      23009
    ],
    "exportDeclaration": {
      "$id": "7",
      "id": 64,
      "movementReferenceNumber": "MyExportMrn",
      "access": 0,
      "notes": "Notes and remarks",
      "responsibility": "DFDS"
    },
    "importDeclaration": {
      "$id": "8",
      "id": 65,
      "movementReferenceNumber": null,
      "access": 0,
      "notes": "Notes and remarks",
      "responsibility": "DFDS"
    },
    "exitSummaryDeclaration": {
      "$id": "9",
      "id": 63,
      "movementReferenceNumber": null,
      "access": 0,
      "notes": "Notes and remarks"
    },
    "entrySummaryDeclaration": {
      "$id": "10",
      "id": 66,
      "movementReferenceNumber": null,
      "access": 0,
      "notes": "Notes and remarks"
    }
  }
]

Getting a specific consignment from a Booking

A consignment can be obtained by using the following endpoint

This API requires the View Consignments feature access

GET https://logisticsapi.dfds.com/api/booking/{bookingId}/consignments/{consignmentId}

Client errors

HTTP/1.1 404 Not Found
If the booking was not found.

HTTP/1.1 404 Not Found
If the consignment was not found.

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to: view the booking or update consignments.

See also:
Example

Example of how to get a single consignment.

        
{
  "$id": "1",
  "id": 16,
  "incoTerms": 0,
  "incoTermsPlace": "This is incoTerms place",
  "remarks": null,
  "goodsLines": [
    6674067
  ],
  "documents": [
    23007
  ],
  "exportDeclaration": {
    "$id": "2",
    "id": 60,
    "movementReferenceNumber": null,
    "access": 0,
    "notes": "Notes and remarks",
    "responsibility": "Customer"
  },
  "importDeclaration": {
    "$id": "3",
    "id": 61,
    "movementReferenceNumber": null,
    "access": 0,
    "notes": "Notes and remarks",
    "responsibility": "Customer"
  },
  "exitSummaryDeclaration": {
    "$id": "4",
    "id": 59,
    "movementReferenceNumber": null,
    "access": 0,
    "notes": "Notes and remarks"
  },
  "entrySummaryDeclaration": {
    "$id": "5",
    "id": 62,
    "movementReferenceNumber": null,
    "access": 0,
    "notes": "Notes and remarks"
  }
}

Data Format

Name Description Type
consignment Contains declarations and details needed to do a customs clearance. Consignment
Consignment

Use this information to identify consignments on bookings.

Name Description Type
id The id uniquely identifying the consignment number
incoTerms International Commercial Terms. Incoterms (Transport terms)
remarks A free text field that holds any remarks relevant to the consignment string
exportDeclaration Customs export declaration. Declaration
importDeclaration Customs import declaration. Declaration
exitSummaryDeclaration Exit summary declaration Declaration
entrySummaryDeclaration Entry summary declaration Declaration
Shipper The shipper Company Associate
Consignee The consignee Company Associate
OfficeOfDeparture Company Associate
IncoTermsPlace The international commercial terms place string
Shipper The shipper Company Associate
goodsLines Array of sub booking goods ids, see Goods Array of 32bit numbers.
documents Array of booking document ids, see Documents Array of 32bit numbers.
Declaration

Use this information to identify declarations on bookings.

Name Description Type
id The id uniquely identifying the consignment number
movementReferenceNumber The MRN number for the declaration. string
uniqueConsignmentReference A free text field that holds any unique consignment reference number relevant to the declaration string
dfdsReference Its a calculated field relevant to the declaration string
notes A free text field that holds any notes relevant to the declaration string
access Field specifying if the declaration details can be updated or not Declaration Edit Mode
responsibility Field specifying who has the responsibility of processing the declaration Declaration Responsibility
state Field specifying the state of the declaration Declaration State
entryNumber The Entry number of the declaration string
Declaration Edit Mode

The declaration edit mode enumeration.

Name Description Value
Allowed Updates to declaration is allowed. 0
AllLocked Updates for the declaration is no longer accepted. 1
Declaration Responsibility

The declaration responsibility enumeration.

Name Description Value
NotSet Responsibility is not set 0
DFDS DFDS has the responsibility of handling declaration 1
Customer Customer has the responsibility of handling declaration 2
Declaration State

The declaration state enumeration.

Name Description Value
NotSet Declaration is not set 0
New Declaration is new 1
Sent Declaration is sent 2
Cleared Declaration is cleared 3
InProgress Declaration is in progress 4
Rejected Declaration is rejected 5

Creating and updating movement

The movement API can be used for creating movement.

Creating a new movement

A new can be created by using the following endpoint.

POST https://logisticsapi.dfds.com/api/customs/movement

Client errors

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to: create movement.

HTTP/1.1 400 Bad Request
If the provided movement data is invalid.

See also:
Example

Example of how to create a movement.

        
{
  "CustomsBorderCrossing": {
    "VesselName": "Victoria",
    "FlagCountryUNCode": "DK",
    "ArrivalDateTime": "2021-10-10T03:24:00",
    "DepartureDateTime": "2021-10-10T12:36:00",
    "BorderEntryLocation": {
      "freightLocationId": 853
    },
    "BorderExitLocation": {
      "freightLocationId": 854
    }
  },
  "TruckUnit": {
    "EquipmentNumber": "AZ27222",
    "RegistrationNumber": "CU4222",
    "NationalityUNCode": "DK"
  },
  "TrailerUnit": {
    "EquipmentNumber": "AZ27333",
    "RegistrationNumber": "CU43333",
    "NationalityUNCode": "DK"
  },
  "TrailerEntryClearanceType": {
    "Name": "Pre-lodgement"
  }
}

Data Format

Name Description Type
movement Contains border exit location, border entry location, truck and trailer information needed to do a customs clearance. Movement

Update existing movement

Update a movement record already present by movement id.

POST https://logisticsapi.dfds.com/api/customs/movement/{movementid}

Client errors

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to link consignments with movement.

HTTP/1.1 400 Bad Request
If the provided data is invalid.

Example

Example of how to update a movement.

        
            {
  "CustomsBorderCrossing": {
    "id": 15,
    "VesselName": "VictoriaUpdated1",
    "FlagCountryUNCode": "DK",
    "ArrivalDateTime": "2021-10-18T03:24:00",
    "DepartureDateTime": "2021-10-18T12:36:00",
    "BorderEntryLocation": {
      "id": 29,
      "freightLocationId": 924
    },
    "BorderExitLocation": {
      "id": 30,
      "freightLocationId": 925
    }
  },
  "TruckUnit": {
    "id": 26,
    "EquipmentNumber": "AZ27222Updated1",
    "RegistrationNumber": "CU4222Update",
    "NationalityUNCode": "US"
  },
  "TrailerUnit": {
    "id": 25,
    "EquipmentNumber": "AZ27333Updated",
    "RegistrationNumber": "CU43333Updated",
    "NationalityUNCode": "US"
  },
  "TrailerEntryClearanceType": {
    "id": 5,
    "Name": "Temporary Storage"
  }
}

Get movement for the booking

Get movement related to a booking.

Get https://logisticsapi.dfds.com/api/customs/movement/{BookingId}/movements

Client errors

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to link consignments with movement.

HTTP/1.1 404 Forbidden
Not found.


Get movement

Get movement detail for a specific movement id.

Get https://logisticsapi.dfds.com/api/customs/movement/{movementId}

Client errors

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to link consignments with movement.

HTTP/1.1 404 Not Found
Movement record with Id is not available.

HTTP/1.1 400 Bad Request
Movement Id is not provided.

Example

Movement data returned for movement Id.

        
            {
  "CustomsBorderCrossing": {
    "id": 15,
    "VesselName": "VictoriaUpdated1",
    "FlagCountryUNCode": "DK",
    "ArrivalDateTime": "2021-10-18T03:24:00",
    "DepartureDateTime": "2021-10-18T12:36:00",
    "BorderEntryLocation": {
      "id": 29,
      "freightLocation": {
        "isRail": false,
        "isVessel": true,
        "externalId": null,
        "name": "DFDS (ROTTERDAM-FELIXSTOWE)",
        "address": {
          "streetName": "Reeweg",
          "houseNumber": "35",
          "pOBox": null,
          "addressLine2": "Rotterdam Shortsea Terminal",
          "addressLine3": null,
          "addressLine4": null,
          "postalCode": "3089 KM",
          "city": "Rotterdam",
          "county": null,
          "country": {
            "code": "NL",
            "longCode": "NLD",
            "euCountryCode": "NL",
            "numericCode": 528,
            "name": "Netherlands",
            "supplierSundryCode": null,
            "nationalityName": "Dutch",
            "id": 19
          },
          "id": 154768
        },
        "state": 2,
        "id": 134625
      },
      "freightLocationId": 924
    },
    "BorderExitLocation": {
      "id": 30,
      "freightLocation": {
        "$id": "8",
        "isRail": false,
        "isVessel": true,
        "externalId": null,
        "name": "DFDS (FELIXSTOWE-VLAARDINGEN)",
        "address": {
          "$id": "9",
          "streetName": "Central Road South",
          "houseNumber": ".",
          "pOBox": null,
          "addressLine2": "North Sea House",
          "addressLine3": "The Docks",
          "addressLine4": null,
          "postalCode": "IP11 3SD",
          "city": "Felixstowe",
          "county": "Suffolk",
          "country": {
            "$id": "10",
            "code": "GB",
            "longCode": "GBR",
            "euCountryCode": null,
            "numericCode": 826,
            "name": "United Kingdom",
            "supplierSundryCode": null,
            "nationalityName": "British",
            "id": 30
          },
          "id": 2074
        },
        "state": 2,
        "id": 856
      },
      "freightLocationId": 925
    }
  },
  "TruckUnit": {
    "id": 26,
    "EquipmentNumber": "AZ27222Updated1",
    "RegistrationNumber": "CU4222Update",
    "NationalityUNCode": "US"
  },
  "TrailerUnit": Information about the trailer used in the movement.
    "id": 25,
    "EquipmentNumber": "AZ27333Updated",
    "RegistrationNumber": "CU43333Updated",
    "NationalityUNCode": "US"
  },
  "TrailerEntryClearanceType": {
    "id": 5,
    "Name": "Temporary Storage"
  }
}

Attach consignments to the existing movement

Consignments can be attached to an existing movement by using the following endpoint.

POST https://logisticsapi.dfds.com/api/customs/movement/{movementid}/carriedconsignments

Client errors

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to link consignments with movement.

HTTP/1.1 400 Bad Request
If the provided data is invalid.

Example

Example of how to attach consignments to a movement.

        
{
  "consignmentIds": [ 1, 2, 3 ]
}

Get the movement and carried consignments relation.

Get the movement and carried consignments relation by using the following endpoint.

GET https://logisticsapi.dfds.com/api/customs/movement/{movementid}/carriedconsignments


Client errors

HTTP/1.1 403 Forbidden
If the authenticated user is not allowed to get movement and carried consignments.

HTTP/1.1 400 Bad Request
If the provided movement id is invalid.

Movement

Use this information to know about movement in customs.

Name Description Type
CustomsBorderCrossing Customs Border crossing contains the information about the Entry border freight location, Exit border freight location Customs border crossing
TruckUnit Information about the truck used in the movement. Truck Unit
TrailerUnit Information about the trailer used in the movement. Trailer unit
TrailerEntryClearanceType Information about the trailer entry clearance type used in the movement. Trailer entry clearance type
Customs Border Crossing

Use this information to know about customs border crossing in movement.

Name Description Type
CustomsBorderCrossing Customs Border crossing is of two types. CustomsShipBorderCrossing and CustomsCarBorderCrossing. Customs ship border crossing
Customs Ship Border Crossing

Use this information to know about customs ship border crossing in movement.

Name Description Type
VesselName The vessel name used in the movement string
FlagCountryUNCode The flag country UNCode for the vessel. string
ArrivalDateTime Arrival DateTime for the vessel. DateTime
DepartureDateTime Departure DateTime for the vessel. DateTime
Truck Unit

Trailer unit information used for the creation of movement.

Name Description Type
EquipmentNumber Equipment number to identify the trailer. string
RegisterationNumber Registeration number of the trailer. string
NationalityUNCode Country UN code for the trailer. string
Truck Unit

Truck unit information used for the creation of movement.

Name Description Type
EquipmentNumber Equipment number to identify the truck string
RegisterationNumber Registeration number of the truck. string
NationalityUNCode Country UN code for the truck string
Trailer entry clearance type

Trailer entry clearance type helps to identify the entry clearance model used for clearance of a trailer in a movement.

Name Description Type
Name Name of the trailer entry clearance type string

Tracking

The tracking API exposes a directed tracking graph representing the movement of all subbookings on a booking. It includes actual, planned or estimated times, carry equipment information and more. It also explicitly includes the last known position of all subbookings. This API requires the 'ViewBookingTracking' feature access.

Tracking information is available at the following api endpoint.

GET https://logisticsapi.dfds.com/api/booking/{bookingId}/tracking

Live Updates! If you need frequent tracking updates, please consider using the Tracking Notification Hook instead of polling the api. The data exposed in the tracking API is frequently updated, but frequent polling will be rate limited.

Data Format

Name Description Type
booking Contains booking and subbooking identifications which are described in this tracking Booking Identification
lastKnownPositions The last known physical position of all subbookings. The last known positions may be at a stop or GPS tracking on the transport. Array of SubBooking Position
stops List of location waypoints with actual or estimated times. Stops may be customer addreses, sea terminals, warehouses or rail stations. Array of Stop
transports List of transportation means connecting Stops. Ex a Truck, Ship or Train Array of Transport
Booking Identification

Use this information to identity the booking and subbokings when tracking data is pushed to you.

Name Description Type
id The id uniquely identifying the booking number
subBookings The list of unique identifiers for all subbookings associated with the booking Array of number
SubBooking Position

Describes the last known position of a subbooking. The time at which this information was obtained is included. The current position may be static if the subbooking is currently stationary (ex. at a terminal). If the subbooking is currently beeing transported by truck, the last known position will be updated using GPS every 15 min.

If the last known position of a subbooking is at a stop, the attributes included are:

Name Description Type
type The last known position is at a stop. "type": "Stop" string
stop The full stop details. Stop

If the last known position is on a transport, the following set of attributes are inlcuded:

Name Description Type
type The last known posistion is on a transport. "type": "Transport" string
transport The full transport details. Transport
position The geographical position Geographical Position
time The time at which this geographical position was tracked Time
Time

Times may be specified as UTC or local time at the location.

Name Description Type
datetime The date and time without timezone information date
timeZone The time zone type. Ex LocationLocal or UTC string
Geographical Position

A geographical position is represented as WGS84 latitude and longitude

Name Description Type
latitude The WGS84 latitude number
longitude The WGS84 longitude number
Stop

A stop describes the arrival and departure at a physical location (collection address, terminal etc.). The times associated with a stop may be actual, planned or predicted. Additional details about specific actions, which occured while at the stop, may be included.

Name Description Type
actions Set the of actions which occured at this stop. Ex. Embark/Disembark at a Sea Terminal Array of Action
location The location for this stop. Location
arrival The time of arrival at this stop Predictable Time
departure The time of departure from this stop Predictable Time

Locations may be either freight addresses, warehouses, sea terminals or rail stations. In either case, a location will always include the following set of attributes.

Name Description Type
friendlyName A human readable name representing the location. Example "DFDS House" or "Copenhagen, Denmark". string
cityName Represents the name for the city of the location. string
type Ex: FreightAddress, SeaTerminal, Warehouse, RailStation string
latitude The latitude in WGS84 format. number
longitude The longitude in WGS84 format. number

Predictable times are equal to Time, but includes an accuracy attribute. A predictable time may be either planned, estimated or actual. Planned carry the least accuracy. Estimated times start appearing when subbokings are transported. An estimated time is more accurate than a planned time. Actual times are the most accurate, as they represent tracking information from the past.

Name Description Type
accuracy Planned, Estimated or Actual string
Transports

A transport represents the transport of one or more subbookings between two stops. It describes the means of transportation (ex Truck, Ship or Train). Additional details like identification of the carrying equipment is also included here.

Name Description Type
type The type of transport used. Truck, Ship or Train string
subBookings The ids of subbookings beeing transported by this means of transportation. Array of number
origin The Stop at which this transport originates. Stop
destination The Stop at which this transport ends. Stop
shippingReference A reference to particular set of subBookings with an external provider string
Ship Transport

If the transport is of type Ship, it includes additional details

Name Description Type
voyage The specific voyage used for this transport Voyage

A voyage is described by ship details and carry equipment.

Name Description Type
ship The ship Ship
carryEquipment The identification describing the carrying equipment. (Ex container-number or trailer-number) Carry Equipment

The ship definies the following attributes

Name Description Type
name The name of the ship string
Truck Transport

Likewise, if the transport is of type Truck, additional details are included

Name Description Type
haulage Haulage

A haulage defines the following attributes

Name Description Type
carryEquipment The identification describing the carrying equipment. (Ex container-number or trailer-number) Carry Equipment
Train Transport

When using train as means for transportation, details about the journey is included.

Name Description Type
journey Journey

The attributes available for a train journey:

Name Description Type
carryEquipment The identification describing the carrying equipment. (Ex container-number or trailer-number) Carry Equipment

Example

Example of a full tracking history for a delivered subbooking.

    
{
  "booking": {
    "id": 42142341,
    "subBookings": [ 3, 45 ]
  },
  "lastKnownPosition": [
    {
      "type": "Stop",
      "stop": { "$ref": 8 },
      "subBooking": 3
    },
    {
      "type": "Transport",
      "transport": { "$ref": 4 },
      "subBooking": 45,
      "position": {
        "latitude": 2.123,
        "longitude": 15.23
      },
      "time": {
        "datetime": "2017-11-04T01:30:00",
        "timeZone": "Local"
      }
    }
  ],
  "stops": [
    {
      "$id": 5,
      "actions": [
        {
          "type": "Collection",
          "subBookings": [ 3 ],
          "time": {
            "dateTime": "2017-11-04T07:50:00",
            "timeZone": "UTC",
            "accuracy": "Actual"
          }
        }
      ],
      "location": {
        "$id": 2,
        "id": 12312,
        "type": "FreightAddress",
        "friendlyName": "DFDS House",
        "cityName": "Copenhagen",
        "latitude": 1,
        "longitude": 2
      },
      "arrival": {
        "datetime": "2017-11-04T07:50:00",
        "timeZone": "Local",
        "accuracy": "Actual"
      },
      "departure": {
        "datetime": "2017-11-04T01:30:00",
        "timeZone": "Local",
        "accuracy": "Actual"
      }
    },
    {
      "$id": 6,
      "actions": [
        {
          "type": "Embarked",
          "subBookings": [ 3 ],
          "time": {
            "datetime": "2017-11-04T07:50:00",
            "timeZone": "Local",
            "accuracy": "Actual"
          }
        }
      ],
      "location": {
        "$id": 3,
        "id": 1234,
        "type": "SeaTerminal",
        "friendlyName": "Esbjerg Terminal",
        "cityName": "Esbjerg",
        "latitude": 1,
        "longitude": 2
      },
      "arrival": {
        "datetime": "2017-11-04T07:50:00",
        "timeZone": "Local",
        "accuracy": "Actual"
      },
      "departure": {
        "datetime": "2017-11-04T07:50:00",
        "timeZone": "Local",
        "accuracy": "Actual"
      }
    },
    {
      "$id": 7,
      "actions": [
        {
          "type": "Disembark",
          "time": {
            "datetime": "2017-11-04T07:50:00",
            "timeZone": "Local",
            "accuracy": "Actual"
          }
        }
      ],
      "location": {
        "$id": 3,
        "locationId": 2432,
        "type": "SeaTerminal",
        "friendlyName": "Immingham Terminal",
        "cityName": "Immingham",
        "latitude": 1,
        "longitude": 2
      },
      "arrival": {
        "datetime": "2017-11-04T07:50:00",
        "timeZone": "Local",
        "accuracy": "Actual"
      },
      "departure": {
        "datetime": "2017-11-04T07:50:00",
        "timeZone": "Local",
        "accuracy": "Planned"
      }
    },
    {
      "$id": 8,
      "actions": [
        {
          "type": "Delivery",
          "bookingAddressId": "23421",
          "time": null
        }
      ],
      "location": {
        "$id": 2,
        "locationId": 22345,
        "type": "Address",
        "friendlyName": "DFDS Immingham",
        "cityName": "Immingham",
        "latitude": 1,
        "longitude": 2
      },
      "arrival": {
        "datetime": "2017-11-04T07:50:00",
        "timeZone": "Local",
        "accuracy": "Estimated"
      }
    }
  ],
  "transports": [
    {
      "$id": 1,
      "type": "Truck",
      "subBookings": [ 3, 45 ],
      "haulage": {
        "$id": 1,
        "carryEquipment": {
          "$id": 2,
          "identification": "DFDA1004562"
        }
      },
      "destination": { "$ref": 5 }
    },
    {
      "$id": 2,
      "type": "Truck",
      "subBookings": [ 3, 45 ],
      "truckHaulage": { "$ref": 1 },
      "origin": { "$ref": 5 },
      "destination": { "$ref": 6 }
    },
    {
      "$id": 3,
      "type": "Ship",
      "subBookings": [ 3, 45 ],
      "voyage": {
        "$id": 3,
        "ship": {
          "name": "Petunia",
          "flag": "DK"
        },
        "carryEquipment": {
          "$ref": 2
        }
      },
      "origin": { "$ref": 6 },
      "destination": { "$ref": 7 }
    },
    {
      "$id": 4,
      "type": "Truck",
      "subBookings": [ 3, 45 ],
      "truckHaulage": { "$ref": 1 },
      "origin": { "$ref": 7 },
      "destination": { "$ref": 8 }
    }
  ]
}

Tracking Notification Hook

Booking trackings can be pushed to external systems using Notification Hooks. The event type representing this tracking is called BookingTracking. When a notification hook is active for this event trackings are pushed every time location trackings or estimated times are updated. Truck location trackings causes updates every 15min.

When considering a single booking, trackings will be pushed starting when a truck is on route for collection and stop when all subbookings have been delivered.

This notification hook supports Content-Type: application/json. The content pushed to the notification endpoint is identical to the data available when calling the tracking api directly.

Invoicing

The invoicing API provides the invoices that have been generated for your account for the selected booking.

Get a specific invoice

GET https://logisticsapi.dfds.com/api/booking/{bookingId}/invoice/{invoiceId}/{invoiceFormat?}

Data Format

Name Description Type
bookingId The id uniquely identifying the booking for which the invoice file is being requested. number
invoiceId The id uniquely identifying the invoice for which the file is being requested. number
invoiceFormat Defines the format in which the invoice file is being requested, which can be "/pdf" or "/excel". If no invoiceFormat is passed, the default will be "/pdf". string