DHL Track and Trace API

openapi: 3.2.0
info:
  title: Dhl Track and Trace API
  version: '1.0'
  description: 'Operations tagged Track and Trace across 2 of this provider''s published API definitions: dhl-parcel-eu-openapi.yml, dhl-parcel-eu-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-gw.dhlparcel.nl
tags:
- name: Track and Trace
paths:
  /track-trace:
    get:
      summary: Track and Trace
      description: Returns piece information
      operationId: getTrackAndTrace
      tags:
      - Track and Trace
      parameters:
      - name: key
        in: query
        description: 'One or more keys to search on, comma separated. A key has the following format: ''trackingKey+postalcode'' or just ''trackingKey'', where trackingKey must be a barcode, airwayBillNumber of shipmentNumber. When querying with a single trackingKey the API will return a reduced set of information for this piece (containing just the barcode, the list of events and any of the derived fields which can be populated based on the event data, such as the ''plannedDeliveryTimeframe'' and ''deliveredAt'' fields).'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: role
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Pieces
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    barcode:
                      type: string
                      description: First piece barcode
                    barcodes:
                      type: array
                      items:
                        type: string
                        description: All piece barcodes
                    contents:
                      type: string
                      description: A description of the contents of this piece
                    date:
                      type: string
                      format: full-date
                      description: Shipment date
                    declaredHeight:
                      type: number
                      description: Piece height in cm, as declared by the shipper
                    declaredLength:
                      type: number
                      description: Piece length in cm, as declared by the shipper
                    declaredVolume:
                      type: number
                      description: Piece volume in l, as declared by the shipper
                    declaredWeight:
                      type: number
                      description: Piece weight in kg, as declared by the shipper
                    declaredWidth:
                      type: number
                      description: Piece width in cm, as declared by the shipper
                    deliveredAt:
                      type: string
                      format: full-date
                      description: The moment the piece was delivered, in case it has been delivered. This information is derived from the events associated with this piece.
                    destination:
                      properties:
                        address:
                          properties:
                            addition:
                              type: string
                              description: Housenumber addition
                            city:
                              type: string
                              description: City
                            countryCode:
                              type: string
                              description: Countrycode (ISO 3166-1 alpha-2)
                            houseNumber:
                              type: string
                              description: House number
                            lines:
                              type: array
                              items:
                                type: string
                              description: The address as a list of strings. This field will only be filled when this address is related to an international shipment and no properly classified address data is available
                            postalCode:
                              type: string
                              description: Postal code
                            street:
                              type: string
                              description: Street
                        code:
                          type: string
                          description: Parcel shop code or terminal code (only present in case the type is 'PARCEL_SHOP' or 'TERMINAL')
                        name:
                          type: string
                          description: Parcel shop name (only present in case the type is 'PARCEL_SHOP')
                        type:
                          type: string
                          enum:
                          - ADDRESS
                          - PARCEL_SHOP
                          - TERMINAL
                      required:
                      - type
                    events:
                      type: array
                      items:
                        properties:
                          category:
                            type: string
                            enum:
                            - CUSTOMS
                            - DATA_RECEIVED
                            - DELIVERED
                            - EXCEPTION
                            - INTERVENTION
                            - IN_DELIVERY
                            - LEG
                            - PROBLEM
                            - UNDERWAY
                            - UNKNOWN
                            description: Status category
                          deliveryAddress:
                            properties:
                              addition:
                                type: string
                                description: Housenumber addition
                              city:
                                type: string
                                description: City
                              countryCode:
                                type: string
                                description: Countrycode (ISO 3166-1 alpha-2)
                              houseNumber:
                                type: string
                                description: House number
                              lines:
                                type: array
                                items:
                                  type: string
                                description: The address as a list of strings. This field will only be filled when this address is related to an international shipment and no properly classified address data is available
                              postalCode:
                                type: string
                                description: Postal code
                              street:
                                type: string
                                description: Street
                          deliveryCode:
                            type: string
                            description: Known as 'kib kaart nummer' in SV-Depot
                          facility:
                            type: string
                            description: The code of the facility where the event took place
                          geoLocation:
                            properties:
                              latitude:
                                type: number
                                description: The latitude
                              longitude:
                                type: number
                                description: The longitude
                          height:
                            type: number
                            description: Piece height in cm
                          length:
                            type: number
                            description: Piece length in cm
                          localTimestamp:
                            format: date-time
                            type: string
                            description: The time the event occurred in the local time of the event's locale
                          leg:
                            properties:
                              accountId:
                                type: string
                                description: The account id of the customer (verladernummer in SVDepot, verzendernummer in Flow, payer account number in Genesis)
                              airWaybillNumber:
                                type: string
                                description: Air Waybill Number
                              contents:
                                description: A description of the contents of this shipment
                                type: string
                              debtorNumber:
                                type: string
                                description: Debtor Number
                              declaredValue:
                                type: number
                                description: The value of the shipment, declared by the shipper
                              declaredVolume:
                                type: number
                                description: The volume, as declared by the shipper
                              declaredWeight:
                                type: number
                                description: The weight, as declared by the shipper
                              deliveryInformation:
                                type: string
                                description: Delivery information
                              destinationFacility:
                                type: string
                                description: The code of the destination facility (GNSX), terminal (Flow) or depot (SV)
                              destinationServiceArea:
                                type: string
                                description: The destination service area (will only be available for international shipments)
                              internationalReference:
                                type: string
                                description: The international shipment reference, (SID reference in Genesis)
                              number:
                                type: string
                                description: Shipment number, as known in FLOW
                              network:
                                type: string
                                enum:
                                - EXPRESS
                                - DAY_DEFINITE
                                - ECOMMERCE
                                description: The network this Leg belongs to
                              originFacility:
                                type: string
                                description: The code of the originating facility (GNSX), terminal (Flow) or depot (SV)
                              originServiceArea:
                                type: string
                                description: The originating service area
                              recap:
                                type: string
                                enum:
                                - Seal
                                - Signature
                                - Stamp
                                description: Recap indication for Flow shipments
                              reference:
                                type: string
                                description: Customer reference (i.e. orderId)
                              volume:
                                type: number
                                description: The actual volume of the shipment
                              weight:
                                type: number
                                description: The actual weight of the shipment
                          nextPlannedDeliveryTimeframe:
                            type: string
                            format: time-interval
                            description: 'The next alternative delivery timeframe, in the time interval format as specified by the ISO 8601 spec (i.e.: <start>/<end>, as in: YYYY-MM-DDThh:mm:ss.sssZ/YYYY-MM-DDThh:mm:ss.sssZ)'
                          plannedDeliveryTimeframe:
                            type: string
                            format: time-interval
                            description: 'The planned delivery timeframe, in the time interval format as specified by the ISO 8601 spec (i.e.: <start>/<end>, as in: YYYY-MM-DDThh:mm:ss.sssZ/YYYY-MM-DDThh:mm:ss.sssZ)'
                          powerOfAttorney:
                            type: boolean
                            description: Power of attorney
                          remarks:
                            type: string
                            description: Remarks
                          route:
                            type: string
                            description: Route / trip information
                          scannedManual:
                            type: boolean
                            description: Scanned manual
                          serviceArea:
                            type: string
                            description: The code of the service area where the event took place
                          signer:
                            type: string
                            description: The name of the entity that signed for delivery
                          status:
                            type: string
                            description: Event status
                          stopNumber:
                            type: integer
                            description: Stop number
                          timestamp:
                            format: date-time
                            type: string
                            description: Time the event occurred
                          type:
                            type: string
                            enum:
                            - LEG_EVENT
                            - PIECE_EVENT
                            - SHIPMENT_EVENT
                            description: Type of event
                          volume:
                            type: number
                            description: Piece volume in liters
                          weight:
                            type: number
                            description: Piece weight in kg
                          width:
                            type: number
                            description: Piece width in cm
                        required:
                        - category
                        - leg
                        - type
                      description: The list of events, sorted by date (ascending)
                    height:
                      type: number
                      description: Piece height in cm
                    length:
                      type: number
                      description: Piece length in cm
                    onBehalfOf:
                      properties:
                        address:
                          properties:
                            addition:
                              type: string
                              description: Housenumber addition
                            city:
                              type: string
                              description: City
                            countryCode:
                              type: string
                              description: Countrycode (ISO 3166-1 alpha-2)
                            houseNumber:
                              type: string
                              description: House number
                            lines:
                              type: array
                              items:
                                type: string
                              description: The address as a list of strings. This field will only be filled when this address is related to an international shipment and no properly classified address data is available
                            postalCode:
                              type: string
                              description: Postal code
                            street:
                              type: string
                              description: Street
                        email:
                          type: string
                          description: Third party email
                        fax:
                          type: string
                          description: Third party fax number
                        name:
                          type: string
                          description: Third party name
                        telephone:
                          type: string
                          description: Third party phone number
                    options:
                      type: array
                      items:
                        type: string
                        description: Shipment option key
                    origin:
                      properties:
                        address:
                          properties:
                            addition:
                              type: string
                              description: Housenumber addition
                            city:
                              type: string
                              description: City
                            countryCode:
                              type: string
                              description: Countrycode (ISO 3166-1 alpha-2)
                            houseNumber:
                              type: string
                              description: House number
                            lines:
                              type: array
                              items:
                                type: string
                              description: The address as a list of strings. This field will only be filled when this address is related to an international shipment and no properly classified address data is available
                            postalCode:
                              type: string
                              description: Postal code
                            street:
                              type: string
                              description: Street
                        code:
                          type: string
                          description: Parcel shop code or terminal code (only present in case the type is 'PARCEL_SHOP' or 'TERMINAL')
                        name:
                          type: string
                          description: Parcel shop name (only present in case the type is 'PARCEL_SHOP')
                        type:
                          type: string
                          enum:
                          - ADDRESS
                          - PARCEL_SHOP
                          - TERMINAL
                      required:
                      - type
                    packageType:
                      type: string
                      description: Package type
                    palletType:
                      type: string
                      description: Type of pallet
                    plannedDeliveryTimeframe:
                      type: string
                      format: full-date
                      description: The planned delivery timeframe. This information is derived from the events associated with this piece.
                    product:
                      properties:
                        code:
                          type: string
                          description: Unique product code
                        description:
                          type: string
                          description: Product description
                        genesisNetworkProductCode:
                          type: string
                          description: Genesis network product code
                        genesisLocalProductCode:
                          type: string
                          description: Genesis local product code
                    receiver:
                      properties:
                        address:
                          properties:
                            addition:
                              type: string
                              description: Housenumber addition
                            city:
                              type: string
                              description: City
                            countryCode:
                              type: string
                              description: Countrycode (ISO 3166-1 alpha-2)
                            houseNumber:
                              type: string
                              description: House number
                            lines:
                              type: array
                              items:
                                type: string
                              description: The address as a list of strings. This field will only be filled when this address is related to an international shipment and no properly classified address data is available
                            postalCode:
                              type: string
                              description: Postal code
                            street:
                              type: string
                              description: Street
                        contactName:
                          type: string
                          description: Receiver contact name
                        email:
                          type: string
                          description: Receiver email
                        fax:
                          type: string
                          description: Receiver fax number
                        name:
                          type: string
                          description: Receiver name
                        telephone:
                          type: string
                          description: Receiver phone number
                    reference:
                      type: string
                      description: Customer reference (i.e. orderId)
                    shipper:
                      properties:
                        accountId:
                          type: string
                          description: The shipper account number from Genesis
                        address:
                          properties:
                            addition:
                              type: string
                              description: Housenumber addition
                            city:
                              type: string
                              description: City
                            countryCode:
                              type: string
                              description: Countrycode (ISO 3166-1 alpha-2)
                            houseNumber:
                              type: string
                              description: House number
                            lines:
                              type: array
                              items:
                                type: string
                              description: The address as a list of strings. This field will only be filled when this address is related to an international shipment and no properly classified address data is available
                            postalCode:
                              type: string
                              description: Postal code
                            street:
                              type: string
                              description: Street
                        contactName:
                          type: string
                          description: Shipper contact name
                        email:
                          type: string
                          description: Shipper email
                        fax:
                          type: string
                          description: Shipper fax number
                        name:
                          type: string
                          description: Shipper name
                        telephone:
                          type: string
                          description: Shipper phone number
                        terminalCode:
                          type: string
                          description: Code of shipper terminal
                    shipperConfidential:
                      type: boolean
                      description: Indicates if the shipper will be hidden or not
                    transitTime:
                      properties:
                        days:
                          properties:
                            total:
                              type: integer
                              description: Total transitTime in days (sum of standard days, holiday days, remote area days and weekend days) based on shipment date and location
                            holiday:
                              type: integer
                              description: Extra transitTime for planned holidays based on shipment date and location
                            remoteArea:
                              type: integer
                              description: Extra transitTime for remote areas based on shipment date and location
                            standard:
                              type: integer
                              description: Standard transitTime for location based on shipment date and location
                            weekend:
                              type: integer
                              description: Extra transitTime for weekends based on shipment date and location
                          required:
                          - total
                          - holiday
                          - remoteArea
                          - standard
                          - weekend
                        destination:
                          properties:
                            countryCode:
                              type: string
                            postalCode:
                              type: string
                          required:
                          - countryCode
                        expectedDeliveryMoment:
                          type: string
                          format: full-date
                          description: The expected delivery moment (in ISO-8601 format)
                        origin:
                          properties:
                            countryCode:
                              type: string
                            postalCode:
                              type: string
                          required:
                          - countryCode
                        product:
                          properties:
                            code:
                              type: string
                        shipmentDate:
                          type: string
                          format: full-date
                          description: The given shipment date (in ISO-8601 format)
                      required:
                      - destination
                      - origin
                    type:
                      type: string
                      enum:
                      - SHIPMENT
                      - RETOUR
                      description: Type of shipment
                    volume:
                      type: number
                      description: Piece volume in l
                    volumetricWeight:
                      type: number
                      description: 'The dimensional weight. The result of the following calculation: (length in cm * width in cm * height in cm / 5000)'
                    weight:
                      type: number
                      description: Piece weight in kg
                    width:
                      type: number
                      description: Piece width in cm
                    lastUpdated:
                      type: string
                      format: full-date
                      description: Last updated date
                    podsAvailable:
                      description: Indicates the types of pods present for the piece
                      type: array
                      items:
                        type: string
                        enum:
                        - Main
                        - ParcelShop
                    pod:
                      description: Link to pod if available
                      type: string
                  required:
                  - type
    servers:
    - url: https://api-gw.dhlparcel.nl
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
x-refined-from:
- dhl-parcel-eu-openapi.yml
- dhl-parcel-eu-openapi.yml