DSV Draft API

openapi: 3.2.0
info:
  title: BOOKING (DEMO) - Air, Sea, Road (EU), Rail Draft API
  description: 'Submit bookings to DSV via the Booking API. Supported transport modes: Air, Sea, Road (EU) and Rail.'
  version: v2
servers:
- url: https://api.dsv.com/my-demo/booking/v2
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: Draft
paths:
  /bookings/getLabel/{bookingId}/{sscc}:
    get:
      tags:
      - Draft
      summary: 6. Get labels by bookingId and SSCC
      description: Generate labels for given bookingId and SSCC.
      operationId: getLabelBySSCC
      parameters:
      - name: bookingId
        in: path
        required: true
        schema:
          type: string
      - name: sscc
        in: path
        required: true
        schema:
          type: string
      - name: labelType
        in: query
        schema:
          type: string
      - name: printFormat
        in: query
        schema:
          type: string
      - name: Authorization
        in: header
        description: OAuth header
        required: true
        schema:
          type: string
      - name: DSV-Subscription-Key
        in: header
        description: DSV Subscription Key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Labels created
          content:
            x-application/zpl+json:
              schema:
                type: string
              example: string
        '400':
          description: Request contains not valid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              example:
                code: ERR12345
                message: 'Not found booking: 40257145990010785188'
                fields:
                - name: field_name
                  message: validation error
                  code: ERR12345
                development:
                  message: string
                  exception: string
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseEntityObject'
        '403':
          description: Lack of privileges to use this method
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponseEntityObject'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              example:
                code: ERR12345
                message: 'Not found booking: 40257145990010785188'
                fields:
                - name: field_name
                  message: validation error
                  code: ERR12345
                development:
                  message: string
                  exception: string
  /bookings/addPackages/{bookingId}:
    put:
      tags:
      - Draft
      summary: 4. Add packages to draft booking
      description: Add packages to existing drafts bookings.
      operationId: addPackages
      parameters:
      - name: bookingId
        in: path
        required: true
        schema:
          type: string
      - name: labelType
        in: query
        description: 'These are the supported label types

          - pdf

          - zpl


          If a "labelType" is not added to the request the label response will default to "pdf"'
        schema:
          enum:
          - pdf
          - zpl
          type: string
          default: pdf
      - name: printFormat
        in: query
        description: 'These are the supported print formats

          - Landscape

          - Portrait


          If a "printFormat" is not added to the request the label response will default to "Landscape"'
        schema:
          enum:
          - Landscape
          - Portrait
          type: string
          default: Landscape
      - name: Authorization
        in: header
        description: OAuth header
        required: true
        schema:
          type: string
      - name: DSV-Subscription-Key
        in: header
        description: DSV Subscription Key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdates'
            example: OrderUpdates
      responses:
        '200':
          description: Packages added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceBookingResponse'
              example:
                bookingId: '40257145990010780000'
        '400':
          description: Request contains not valid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              example:
                code: ERR12345
                message: 'Not found booking: 40257145990010785188'
                fields:
                - name: field_name
                  message: validation error
                  code: ERR12345
                development:
                  message: string
                  exception: string
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Lack of privileges to use this method
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              example:
                code: ERR12345
                message: 'Not found booking: 40257145990010785188'
                fields:
                - name: field_name
                  message: validation error
                  code: ERR12345
                development:
                  message: string
                  exception: string
  /bookings/createDraftBooking:
    post:
      tags:
      - Draft
      summary: 3. Create draft booking
      description: Create a draft booking with DSV.
      operationId: createDraftApiOnlyBooking
      parameters:
      - name: labelType
        in: query
        description: 'These are the supported label types

          - pdf

          - zpl


          If a "labelType" is not added to the request the label response will default to "pdf"'
        schema:
          enum:
          - pdf
          - zpl
          type: string
          default: pdf
      - name: printFormat
        in: query
        description: 'These are the supported print formats

          - Landscape

          - Portrait


          If a "printFormat" is not added to the request the label response will default to "Landscape"'
        schema:
          enum:
          - Landscape
          - Portrait
          type: string
          default: Landscape
      - name: Authorization
        in: header
        description: OAuth header
        required: true
        schema:
          type: string
      - name: DSV-Subscription-Key
        in: header
        description: DSV Subscription Key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            example:
              autobook: false
              templateName: string
              parties:
                sender:
                  address:
                    companyName: Test Company Name Inc.
                    addressId: AddressID123
                    addressLine1: Test Address Line 1
                    addressLine2: Test Address Line 2
                    addressLine3: string
                    city: Test Address City
                    countryCode: DK
                    state: string
                    zipCode: '1234'
                    instructions: Specific Address Party Instrution
                    mdm: '6412345678'
                    eori: DE123456789012AZ
                    approvedShipper: string
                  contact:
                    name: Test Name
                    email: testemail@testcompany.com
                    telephone: '+4512345678'
                receiver:
                  address:
                    companyName: Test Company Name Inc.
                    addressId: AddressID123
                    addressLine1: Test Address Line 1
                    addressLine2: Test Address Line 2
                    addressLine3: string
                    city: Test Address City
                    countryCode: DK
                    state: string
                    zipCode: '1234'
                    instructions: Specific Address Party Instrution
                    mdm: '6412345678'
                    eori: DE123456789012AZ
                    approvedShipper: string
                  contact:
                    name: Test Name
                    email: testemail@testcompany.com
                    telephone: '+4512345678'
                delivery:
                  address:
                    companyName: Test Company Name Inc.
                    addressId: AddressID123
                    addressLine1: Test Address Line 1
                    addressLine2: Test Address Line 2
                    addressLine3: string
                    city: Test Address City
                    countryCode: DK
                    state: string
                    zipCode: '1234'
                    instructions: Specific Address Party Instrution
                    mdm: '6412345678'
                    eori: DE123456789012AZ
                    approvedShipper: string
                  contact:
                    name: Test Name
                    email: testemail@testcompany.com
                    telephone: '+4512345678'
                pickup:
                  address:
                    companyName: Test Company Name Inc.
                    addressId: AddressID123
                    addressLine1: Test Address Line 1
                    addressLine2: Test Address Line 2
                    addressLine3: string
                    city: Test Address City
                    countryCode: DK
                    state: string
                    zipCode: '1234'
                    instructions: Specific Address Party Instrution
                    mdm: '6412345678'
                    eori: DE123456789012AZ
                    approvedShipper: string
                  contact:
                    name: Test Name
                    email: testemail@testcompany.com
                    telephone: '+4512345678'
                notify:
                  address:
                    companyName: Test Company Name Inc.
                    addressId: AddressID123
                    addressLine1: Test Address Line 1
                    addressLine2: Test Address Line 2
                    addressLine3: string
                    city: Test Address City
                    countryCode: DK
                    state: string
                    zipCode: '1234'
                    instructions: Specific Address Party Instrution
                    mdm: '6412345678'
                    eori: DE123456789012AZ
                    approvedShipper: string
                  contact:
                    name: Test Name
                    email: testemail@testcompany.com
                    telephone: '+4512345678'
                freightPayer:
                  address:
                    companyName: Test Company Name Inc.
                    addressId: AddressID123
                    addressLine1: Test Address Line 1
                    addressLine2: Test Address Line 2
                    addressLine3: string
                    city: Test Address City
                    countryCode: DK
                    state: string
                    zipCode: '1234'
                    instructions: Specific Address Party Instrution
                    mdm: '6412345678'
                    eori: DE123456789012AZ
                    approvedShipper: string
                  contact:
                    name: Test Name
                    email: testemail@testcompany.com
                    telephone: '+4512345678'
                bookingParty:
                  address:
                    companyName: Test Company Name Inc.
                    addressId: AddressID123
                    addressLine1: Test Address Line 1
                    addressLine2: Test Address Line 2
                    addressLine3: string
                    city: Test Address City
                    countryCode: DK
                    state: string
                    zipCode: '1234'
                    instructions: Specific Address Party Instrution
                    mdm: '6412345678'
                    eori: DE123456789012AZ
                    approvedShipper: string
                  contact:
                    name: Test Name
                    email: testemail@testcompany.com
                    telephone: '+4512345678'
                carrier:
                  address:
                    companyName: Test Company Name Inc.
                    addressId: AddressID123
                    addressLine1: Test Address Line 1
                    addressLine2: Test Address Line 2
                    addressLine3: string
                    city: Test Address City
                    countryCode: DK
                    state: string
                    zipCode: '1234'
                    instructions: Specific Address Party Instrution
                    mdm: '6412345678'
                    eori: DE123456789012AZ
                    approvedShipper: string
                  contact:
                    name: Test Name
                    email: testemail@testcompany.com
                    telephone: '+4512345678'
              product:
                name: Sea
                billOfLading: Original
                containerMode: FCL
                containers:
                - ref: TestContainerNumber1
                  type: 20RE
                  genset: true
                  temp: -20
                dropOff: false
              services:
                serviceLevel: '401'
                cashOnDelivery:
                  amount:
                    value: 123.45
                    currency: DKK
                insurance:
                  amount:
                    value: 123.45
                    currency: DKK
                  category: STD
                palletExchange:
                  quantity: 2
                  type: EUR
                preAdvice:
                  phone: '+4512345678'
                  email: PreAdvice@companyname.com
                b2C:
                  phone: '+4512345678'
                  email: B2CService@companyname.com
                spotQuoteNumber:
                  number: string
                thermotransport: true
                driverLoading: true
                tailLiftDelivery: true
                dangerousGoods: true
                getePallet: true
                geteParcel: true
                seaPortSelection:
                  portOfLoading:
                    code: DK FDH
                    name: Frederikshavn
                  portOfDischarge:
                    code: DK FDH
                    name: Frederikshavn
                airportSelection:
                  airportOfDeparture:
                    code: DK FDH
                    name: Frederikshavn
                  airportOfDestination:
                    code: DK FDH
                    name: Frederikshavn
                railPortSelection:
                  portOfLoading:
                    code: DK FDH
                    name: Frederikshavn
                  portOfDischarge:
                    code: DK FDH
                    name: Frederikshavn
                simpleServices:
                - name: string
                preAdviceMailPickUp: true
                preAdviceMailDelivery: true
                privateDeliveryCurbSide: true
                tailLiftPickUp: true
                fixPickUpTime: true
                fixDeliveryTime: true
                fixDayDelivery: true
                amPickUp: true
                pmPickUp: true
                amDelivery: true
                pmDelivery: true
                exportCustomsClearance: BY_DSV
                importCustomsClearance: BY_DSV
                airlineExpress: true
              incoterms:
                code: EXW
                location: TestCityPickup1
              detailedGoodsDescription:
              - string
              packages:
              - quantity: 2
                packageType: EUR
                totalWeight: 1900
                netWeight: 1500
                length: 120
                height: 110
                width: 80
                stackable: 'No'
                totalVolume: 2.112
                palletSpace: 1
                loadingMeters: 0.8
                description: Test Goods 1
                shippingMarks: Test Shipping Marks 1
                shippingMarksList:
                - string
                harmonizedCodes:
                - 0
                temperatureMin: -22
                temperatureMax: -18
                containerNo: 0
                battery:
                  batteryType: DRY
                  batteryPackageType: IN_EQUIPMENT
                isDangerous: true
                trackingNumbers: '[”00157145990039103076”,”00157145990039103083”]'
                dangerousGoods:
                - className: '''9'''
                  subRisk: 9A
                  flashPoint: 0
                  limitedQuantity: true
                  marinePollutant: true
                  packingGroup: II
                  properShippingName: LITHIUM ION BATTERIES CONTAINED IN EQUIPMENT
                  technicalName: string
                  technicalNameNational: string
                  temperatureMin: 0
                  temperatureMax: 0
                  type: ADR
                  unCode: '3481'
                  tunnelCode: E
                  packagesCount: 2
                  packingKind: BOX
                  netWeight: 800
                  grossWeight: 1000
                  netWeightUnit: KG
                  grossWeightUnit: KG
                grossWeight: 1900
                cargoAircraftOnly: false
                temperatureControlled: true
              references:
              - value: Test Reference
                type: SHIPPER_REFERENCE
              pickupInstructions: Test Pickup Instruction
              deliveryInstructions: Test Delivery Instruction
              additionalInstructions:
              - string
              pickupTime:
                date: '2020-08-30'
                start: '2025-05-30'
                end: '2025-05-30'
              deliveryTime:
                date: '2020-08-30'
                start: '2025-05-30'
                end: '2025-05-30'
              units:
                dimension: CM
                weight: KG
                volume: M3
                loadingSpace: LM
                temperature: C
              controllingCountry: string
              productCode: string
      responses:
        '200':
          description: Booking submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceBookingResponse'
              example:
                bookingId: '40257145990010780000'
        '400':
          description: Request contains not valid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              example:
                code: ERR12345
                message: 'Not found booking: 40257145990010785188'
                fields:
                - name: field_name
                  message: validation error
                  code: ERR12345
                development:
                  message: string
                  exception: string
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Lack of privileges to use this method
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              example:
                code: ERR12345
                message: 'Not found booking: 40257145990010785188'
                fields:
                - name: field_name
                  message: validation error
                  code: ERR12345
                development:
                  message: string
                  exception: string
  /bookings/submitDraftBooking/{bookingId}:
    post:
      tags:
      - Draft
      summary: 5. Submit draft booking
      description: Submit the existing draft booking.
      operationId: submitDraftBooking_1
      parameters:
      - name: bookingId
        in: path
        required: true
        schema:
          type: string
      - name: labelType
        in: query
        description: 'These are the supported label types

          - pdf

          - zpl


          If a "labelType" is not added to the request the label response will default to "pdf"'
        schema:
          enum:
          - pdf
          - zpl
          type: string
          default: pdf
      - name: printFormat
        in: query
        description: 'These are the supported print formats

          - Landscape

          - Portrait


          If a "printFormat" is not added to the request the label response will default to "Landscape"'
        schema:
          enum:
          - Landscape
          - Portrait
          type: string
          default: Landscape
      - name: Authorization
        in: header
        description: OAuth header
        required: true
        schema:
          type: string
      - name: DSV-Subscription-Key
        in: header
        description: DSV Subscription Key
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Booking is created
          content:
            application/json:
              schema:
                type: string
              example: string
        '400':
          description: Request contains not valid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              example:
                code: ERR12345
                message: 'Not found booking: 40257145990010785188'
                fields:
                - name: field_name
                  message: validation error
                  code: ERR12345
                development:
                  message: string
                  exception: string
        '401':
          description: Not authorized
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Lack of privileges to use this method
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDTO'
              example:
                code: ERR12345
                message: 'Not found booking: 40257145990010785188'
                fields:
                - name: field_name
                  message: validation error
                  code: ERR12345
                development:
                  message: string
                  exception: string
components:
  schemas:
    Order:
      required:
      - bookingReferenceCode
      - packages
      - parties
      - product
      type: object
      properties:
        autobook:
          type: boolean
          description: 'This option provides two ways to submit a booking to DSV, either by as a final booking to DSV without the need for further involvement by the customer (flag set to: True) or sending the booking to DSV’s myDSV customer portal as a draft booking (flag set to: False). In case autobook is true, several fields become business mandatory even if technically they are optional.'
          default: false
          example: true
        labelRequest:
          type: boolean
          description: 'This option provides two ways to process a booking to DSV, either by requesting the generation of a label and returning the label information (Base64) in the booking response (flag set to: True), or by processing the booking without generating a label (flag set to: False).'
          default: false
          example: true
        bookingReferenceCode:
          type: string
          description: Booking Reference Code
          example: '123'
        spotQuoteNumber:
          type: string
          description: Spot Quote Number
          example: 2f6192e1-f29c-ad1c-96c2-3501a361bdc1
        templateName:
          enum:
          - range[-infinity, 64]
          type: string
          description: Name of a previously created template in myDSV customer portal. The template must be accessible in the current upload context. Values present in the template do not need to be included in the booking, even if they are marked as mandatory.
        parties:
          $ref: '#/components/schemas/Parties'
        product:
          $ref: '#/components/schemas/Product'
        services:
          $ref: '#/components/schemas/Services'
        incoterms:
          $ref: '#/components/schemas/Incoterms'
        detailedGoodsDescription:
          type: array
          items:
            type: string
            description: A description of the cargo commodity.
            xml:
              name: line
          description: A description of the cargo commodity.
          xml:
            wrapped: true
        packages:
          type: array
          items:
            $ref: '#/components/schemas/Package'
          description: Contains all package lines included in the booking.
          xml:
            wrapped: true
        references:
          type: array
          items:
            $ref: '#/components/schemas/OrderReference'
          description: A section to include references that can later be used to identify linked information. Multiple references of the same type are allowed. See the reference list for details.
          xml:
            wrapped: true
        pickupInstructions:
          type: array
          items:
            type: string
            description: Additional pickup instructions for the booking.
            xml:
              name: line
            example: Test Pickup Instruction
          description: Additional pickup instructions for the booking.
          xml:
            wrapped: true
          example: Test Pickup Instruction
        deliveryInstructions:
          type: array
          items:
            type: string
            description: Additional delivery instructions for the booking.
            xml:
              name: line
            example: Test Delivery Instruction
          description: Additional delivery instructions for the booking.
          xml:
            wrapped: true
          example: Test Delivery Instruction
        additionalInstructions:
          type: array
          items:
            type: string
            description: 'Additional instructions for the booking. Available options: Pickup, Delivery, Additional. Additional instructions are only available for transport modes: Air, Sea and Rail.'
            xml:
              name: line
          description: 'Additional instructions for the booking. Available options: Pickup, Delivery, Additional. Additional instructions are only available for transport modes: Air, Sea and Rail.'
          xml:
            wrapped: true
        pickupTime:
          $ref: '#/components/schemas/DateTimeRange'
        deliveryTime:
          $ref: '#/components/schemas/DateTimeRange'
        units:
          $ref: '#/components/schemas/Units'
        controllingCountry:
          type: string
          description: Specifies the controlling country.
        productCode:
          type: string
          description: Specifies the product code.
      description: Main structure, represents the booking
    Units:
      type: object
      properties:
        dimension:
          enum:
          - KG
          - M3
          - DM3
          - CM
          - M
          - LM
          - LTR
          - C
          - LB
          - FT3
          - IN
          - FT
          - F
          type: string
          description: 'Dimension UOM:


            CM = Centimeter

            M = Meter (only for Air, Sea and Rail)

            IN = Inch

            FT = Feet (only for Air, Sea and Rail)'
          default: CM
        weight:
          enum:
          - KG
          - M3
          - DM3
          - CM
          - M
          - LM
          - LTR
          - C
          - LB
          - FT3
          - IN
          - FT
          - F
          type: string
          description: 'Weight UOM:

            - KG = Kilo

            - LB = Pound'
          default: KG
        volume:
          enum:
          - KG
          - M3
          - DM3
          - CM
          - M
          - LM
          - LTR
          - C
          - LB
          - FT3
          - IN
          - FT
          - F
          type: string
          description: 'Volume UOM:


            M3 = Cubic meter

            DM3 = Cubic decimetre (only for Air, Sea and Rail)

            LTR = Litre

            FT3 = Cubic feet'
          default: M3
        loadingSpace:
          enum:
          - KG
          - M3
          - DM3
          - CM
          - M
          - LM
          - LTR
          - C
          - LB
          - FT3
          - IN
          - FT
          - F
          type: string
          description: 'Loading Meters UOM:


            LM = Load Meter (only for Road)'
          default: LM
        temperature:
          enum:
          - KG
          - M3
          - DM3
          - CM
          - M
          - LM
          - LTR
          - C
          - LB
          - FT3
          - IN
          - FT
          - F
          type: string
          description: 'Temperature UOM:

            - C = Celsius

            - F = Fahrenheit'
          default: C
      description: Defines the units of measurement (UOM) used for all measurements within the package section. It is recommended to use either all metric or all imperial UOM.
    DangerousGoods:
      required:
      - className
      - grossWeight
      - packagesCount
      - packingGroup
      - packingKind
      - type
      - unCode
      type: object
      properties:
        className:
          type: string
          description: "The UN className can be derived from the mandatory unCode.\n If this value is supplied, it needs to match the UN className that is stored for the provided unCode."
          example: '''9'''
        subRisk:
          type: string
          description: "The UN subRisk can be derived from the mandatory unCode.\n If this value is supplied, it needs to match the UN subRisk that is stored for the provided unCode."
          example: 9A
        flashPoint:
          type: number
          description: "The flashPoint must be provided in the \"Unit of Measure\" selected for temperature in the units object.\nThis can only be used for dangerous goods type = \"IMDG\". \nThis value can be mandatory depending on the UN code."
        limitedQuantity:
          type: boolean
          description: This value can be mandatory depending on the UN code.
          example: true
        marinePollutant:
          type: boolean
          description: This value can be mandatory depending on the UN code.
          example: true
        packingGroup:
          type: string
          description: This value can be mandatory depending on the UN code.
          example: II
        properShippingName:
          type: string
          description: "The UN properShippingName can be derived from the mandatory unCod

# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dsv/refs/heads/main/openapi/dsv-draft-api-openapi.yml