Kuehne+Nagel Job Status API

openapi: 3.2.0
info:
  title: IntermodalTransportExecution Job Status API
  description: 'This API enables Intermodal subcontractors who transport containers via truck, rail, and barge for Kuehne+Nagel to receive details about assigned consignments, including job details and instructions. It also allows them to provide status updates and proof of pickup/delivery on these consignments.

    To use this API, subcontractors must be registered and set up as an API user  within our Intermodal TMS. Please discuss registration with your Kuehne+Nagel Intermodal operations point of contact.'
  contact:
    name: Global TOPS API Support
    url: https://home.kuehne-nagel.com/en/service-request-api?lead_topic=intermodal-transport-execution
    email: tops-technical@kuehne-nagel.com
  version: v1
  x-api-id: b576b932-7583-4076-838b-32d6064a8a2d
  x-api-guideline-version: 1.11.7
  x-api-version: 1.0.0
servers:
- url: https://gateway.api.kuehne-nagel.com/transport/execution/pickup-and-delivery/sea/v1
- url: http://gateway.api.kuehne-nagel.com:8280/transport/execution/pickup-and-delivery/sea/v1
security:
- default: []
tags:
- name: Job Status
paths:
  /job-status/{jobId}:
    parameters:
    - name: X-KN-Country-Code
      in: header
      description: Unique country identifier for a specific Kuehne+Nagel Operating Company.
      required: true
      style: simple
      explode: false
      schema:
        $ref: '#/components/schemas/CountryCode'
    - name: X-KN-Request-ID
      in: header
      description: 'UUID identifying the request which will be generated by the client.

        '
      required: true
      style: simple
      explode: false
      schema:
        $ref: '#/components/schemas/RequestId'
    - name: jobId
      in: path
      description: A unique identifier of the Job. This value can be found in consignment.job.id from AssignedConsignment response.
      required: true
      style: simple
      explode: false
      schema:
        type: string
        example: 1525808-1690222-918
    post:
      tags:
      - Job Status
      summary: Update job status
      description: Creates and updates the status of jobs associated with the Kuehne+Nagel Intermodal department.
      operationId: subcontractorimportstatus
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobStatusRequest'
      responses:
        '201':
          description: Status updated
          headers:
            X-KN-Request-ID:
              description: The same UUID that was originally provided by the client to identify the request.
              style: simple
              explode: false
              schema:
                $ref: '#/components/schemas/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
        default:
          description: Error occurred - see status code and problem object for more information.
          headers:
            X-KN-Request-ID:
              description: The same UUID that was originally provided by the client to identify the request.
              style: simple
              explode: false
              schema:
                $ref: '#/components/schemas/RequestId'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
components:
  schemas:
    JobStatusRequest:
      required:
      - senderUniqueShortName
      - uniqueTransportReference
      type: object
      properties:
        senderUniqueShortName:
          maxLength: 8
          type: string
          description: Unique internal identifier of the message sender. This value can be found in consignment.recipientUniqueShortName from the AssignedConsignment response.
          example: VRTRAN
        uniqueTransportReference:
          maxLength: 20
          type: string
          description: Unique reference of Kuehne+Nagel's transport order. This is the same as the consignment.job.uniqueTransportReference from the AssignedConsignment response.
          example: 9071410039-01
        consignmentAcceptanceStatus:
          maxLength: 6
          type: string
          description: Indicates if the assigned consignment will be accepted for execution or rejected.
          example: ACCEPT
          x-extensible-enum:
          - ACCEPT
          - REJECT
        containerNumber:
          maxLength: 11
          pattern: ^[A-Za-z]{3}[A-Za-z][0-9]{7}$|^[0-9]{1,3}$
          type: string
          description: Container number of the container.
          example: ABCU1234567
        containerSealNumber:
          maxLength: 20
          type: string
          description: Seal number of the container.
          example: SEAL8888
        truckLicensePlate:
          maxLength: 10
          type: string
          description: Truck license plate number allocated to this job.
          example: HH VR 2025
        trailerLicensePlate:
          maxLength: 10
          type: string
          description: Trailer registration allocated to this job.
          example: 12345TR
        waypoint:
          required:
          - activity
          - id
          - unLocationCode
          type: object
          properties:
            id:
              maxLength: 20
              type: integer
              description: Unique identifier of the assigned consignment job waypoint. This value can be found in consignment.job.waypoint.id from the AssignedConsignment response.
              format: int64
              example: 6606341
            activity:
              maxLength: 3
              type: string
              description: Indicates the type of waypoint from the assigned consignment endpoint of the API. The values allowed are LOA = Load, C/D = Collect or Delivery, CUS = Customs, UNL = Unload, VGM = Verified Gross Mass.
              example: LOA
              x-extensible-enum:
              - LOA
              - C/D
              - CUS
              - UNL
              - VGM
            unLocationCode:
              maxLength: 5
              type: string
              description: UN Location Code of the waypoint.
              example: INBLR
          description: When sending waypoint object, at least one of event or reference must be provided along with the required fields (id, activity, unLocationCode). The request will be ignored if neither event nor reference is part of request.
          anyOf:
          - required:
            - event
            properties:
              event:
                required:
                - code
                - dateTime
                type: object
                properties:
                  code:
                    maxLength: 3
                    type: string
                    description: Indicates the event code for the waypoint status. PRO = Proposed, ETA = Estimated Arrival, ATA = Actual Arrival, ETD = Estimated Departure, ATD = Actual Departure.
                    example: ATA
                    x-extensible-enum:
                    - PRO
                    - ETA
                    - ATA
                    - ETD
                    - ATD
                  dateTime:
                    type: string
                    description: Date and time of the event, expressed in local time, formatted as YYYY-MM-DDTHH:mm:ss[+/-HH:mm].
                    format: date-time
                    example: '2025-10-17T07:14:55Z'
          - required:
            - reference
            properties:
              reference:
                maxLength: 50
                type: string
                description: Reference related to specific waypoint.
                example: Pin:123456
    Problem:
      required:
      - detail
      - title
      type: object
      properties:
        type:
          type: string
          description: A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferencable and point to a human-readable documentation nor globally unique for the problem type.
          format: uri-reference
          example: /problem/connection-error
          default: about:blank
        title:
          maxLength: 50
          type: string
          description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.\n
          example: Service Unavailable
        status:
          minimum: 100
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.\n
          format: int32
          example: 503
          exclusiveMaximum: 600
        detail:
          maxLength: 500
          type: string
          description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.\n
          example: Connection to database timed out
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.\n
          format: uri-reference
          example: /problem/connection-error#token-info-read-timed-out
    CountryCode:
      maxLength: 5
      type: string
      description: 'Unique country identifier for a specific Kuehne+Nagel Operating Company.

        '
      example: DE
    JobStatusResponse:
      type: object
      properties:
        message:
          maxLength: 500
          type: string
          description: Details of the job status.
          example: Job status updated successfully
    RequestId:
      maxLength: 36
      type: string
      description: 'UUID identifying the request which will be generated by the client.

        '
      format: uuid
      example: 019a1641-02a3-7a08-a83b-de93c338ed0e
  securitySchemes:
    default:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://gateway.api.kuehne-nagel.com/authorize
          scopes: {}
x-wso2-api-key-header: ApiKey