openapi: 3.0.3
info:
  title: ShipperGuide API
  version: v3
  description: Optimize shipping operations with ShipperGuide TMS
paths:
  /shipments/:
    post:
      operationId: shipments_create
      description: |-
        This endpoint creates a shipment.

        Use existing data to expedite shipment generation by integrating load-level information.
      summary: Create a shipment
      tags:
      - Shipments API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentCreateRequest'
            examples:
              DryVan-FTL:
                value:
                  shipper_uuid: 5c5d1123-948c-4327-bfcc-08536f5f1064
                  equipment_type: DRV
                  mode: FTL
                  shipment_reference: REF987654321
                  stops:
                  - address: 123 Main St
                    city: Springfield
                    zipcode: '12345'
                    state: IL
                    country: USA
                    index: 0
                    type: pickup
                    planned_date: '2024-01-01'
                  - address: 456 Elm St
                    city: Shelbyville
                    zipcode: '67890'
                    state: IL
                    country: USA
                    index: 1
                    type: delivery
                summary: Dry Van - FTL
              DryVan-LTL:
                value:
                  shipper_uuid: 5c5d1123-948c-4327-bfcc-08536f5f1064
                  bol_number: BOL123456789
                  equipment_type: DRV
                  mode: LTL
                  shipment_reference: REF987654321
                  mileage: 1200
                  target_rate: '5000'
                  stops:
                  - facility_name: ABC Warehouse
                    address: 123 Main St
                    zipcode: '12345'
                    city: Springfield
                    state: IL
                    country: USA
                    index: 0
                    type: pickup
                    planned_date: '2024-01-01'
                    instructions: Load pallets from dock 3
                  - facility_name: XYZ Distribution Center
                    address: 456 Elm St
                    zipcode: '67890'
                    city: Shelbyville
                    state: IL
                    country: USA
                    index: 1
                    type: delivery
                    planned_date: '2024-01-02'
                    instructions: Unload at bay 2
                  handling_units:
                  - quantity: 10
                    type: std_pallets
                    height: '48'
                    length: '48'
                    width: '40'
                    stackable: true
                    turnable: true
                    po_numbers:
                    - PO12345
                    so_numbers:
                    - SO67890
                    pickup_stop_index: 0
                    delivery_stop_index: 1
                    movement: outbound
                    commodities:
                    - description: Food Goods
                      quantity: 10
                      weight: '17225.20'
                      freight_class: '70'
                      nmfc_code: '123456'
                summary: Dry Van - LTL
        required: true
      security:
      - jwt: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentCreateResponse'
          description: ''
components:
  schemas:
    CountryEnum:
      enum:
      - USA
      - CAN
      type: string
      description: |-
        * `USA` - United States
        * `CAN` - Canada
    EquipmentTypeEnum:
      enum:
      - DRV
      - RFR
      type: string
      description: |-
        * `DRV` - Dry Van
        * `RFR` - Reefer
    FreightClassEnum:
      enum:
      - '50'
      - '55'
      - '60'
      - '65'
      - '70'
      - '77.5'
      - '85'
      - '92.5'
      - '100'
      - '110'
      - '125'
      - '150'
      - '175'
      - '200'
      - '250'
      - '300'
      - '400'
      - '500'
      type: string
      description: |-
        * `50` - 50
        * `55` - 55
        * `60` - 60
        * `65` - 65
        * `70` - 70
        * `77.5` - 77.5
        * `85` - 85
        * `92.5` - 92.5
        * `100` - 100
        * `110` - 110
        * `125` - 125
        * `150` - 150
        * `175` - 175
        * `200` - 200
        * `250` - 250
        * `300` - 300
        * `400` - 400
        * `500` - 500
    ModeEnum:
      enum:
      - FTL
      - PTL
      - LTL
      - IMDL
      type: string
      description: |-
        * `FTL` - Full Truckload
        * `PTL` - Partial Truckload
        * `LTL` - Less-Than-Truckload
        * `IMDL` - Intermodal
    MovementEnum:
      enum:
      - inbound
      - outbound
      - transfer
      type: string
      description: |-
        * `inbound` - Inbound
        * `outbound` - Outbound
        * `transfer` - Transfer
    PackageTypeEnum:
      enum:
      - bags
      - boxes
      - bulk_containers
      - bundles_and_rolls
      - cartons
      - drums
      - gas_cylinders
      - jerricans
      - pails_or_cans
      - pieces
      - totes_or_tanks
      type: string
      description: |-
        * `bags` - Bags
        * `boxes` - Boxes
        * `bulk_containers` - Bulk Containers
        * `bundles_and_rolls` - Bundles and Rolls
        * `cartons` - Cartons
        * `drums` - Drums
        * `gas_cylinders` - Gas Cylinders
        * `jerricans` - Jerricans
        * `pails_or_cans` - Pails or Cans
        * `pieces` - Pieces
        * `totes_or_tanks` - Totes or Tanks
    ShipmentCreateRequest:
      type: object
      properties:
        shipper_uuid:
          type: string
          format: uuid
          description: Unique identifier of the shipper that owns this shipment.
        bol_number:
          type: string
          description: BOL Number.
          maxLength: 100
        equipment_type:
          allOf:
          - $ref: '#/components/schemas/EquipmentTypeEnum'
          description: Equipment. The API currently accepts either Dry Van or Reefer.
        mode:
          allOf:
          - $ref: '#/components/schemas/ModeEnum'
          description: |
            Mode of transportation, and the valid modes depend on the Equipment:
            - Dry Van works with FTL, PLT, LTL, IMDL
            - Reefer works for FTL, IMDL
        shipment_reference:
          type: string
          description: Internal customer reference such as the load identifier.
          maxLength: 255
        mileage:
          type: integer
          minimum: 0
          description: |
            Mileage. The total distance between first and last stop.
            If the customer doesn't provide it, the system will calculate it.
        target_rate:
          type: string
          format: decimal
          pattern: ^-?\d{0,10}(?:\.\d{0,3})?$
          description: |
            A target rate is the price the customer would like to pay for the shipment.
            This data is essential if the customer uses the Book it Now functionality.
        stops:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentCreateRequestStop'
          description: Stops indicate the shipment's pickup and drop-off locations.
        handling_units:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentCreateRequestHandlingUnit'
          description: |
            This represents the handling units that will be moved within a shipment, at the level that the freight will be loaded and unloaded.
            If the customer is declaring a PTL/LTL shipment, handling units information is mandatory.
      required:
      - equipment_type
      - mode
      - shipper_uuid
      - stops
    ShipmentCreateRequestHandlingUnit:
      type: object
      properties:
        quantity:
          type: integer
          minimum: 0
          title: Package Count
          description: Number of handling units being described.
        type:
          allOf:
          - $ref: '#/components/schemas/ShipmentCreateRequestHandlingUnitTypeEnum'
          title: Handling Unit Type
          description: Handling unit type.
        height:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,5})?$
          description: Height of the package, in inches.
        length:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,5})?$
          description: Length of the package, in inches.
        width:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,5})?$
          description: Width of the package, in inches.
        stackable:
          type: boolean
          description: Indicates if handling units can be stacked.
        turnable:
          type: boolean
          description: Indicates if handling units can be turned.
        po_numbers:
          type: array
          items:
            type: string
            maxLength: 255
          description: Purchase Order Numbers.
        so_numbers:
          type: array
          items:
            type: string
            maxLength: 255
          description: Sales Order Numbers.
        pickup_stop_index:
          type: integer
          minimum: 0
          description: Use to indicate at what pickup stop this handling unit will
            be collected.
        delivery_stop_index:
          type: integer
          minimum: 0
          description: Use to indicate at what delivery stop this handling unit will
            be dropped off.
        max_temperature:
          type: number
          format: double
          title: Max. Temperature
          description: Max temperature, in Fahrenheit. If the customer provides a
            temp for a given handling unit, the entire shipment becomes temperature-controlled.
        movement:
          allOf:
          - $ref: '#/components/schemas/MovementEnum'
          description: Indicates the movement type for this handling unit. Stored
            for reporting purposes only.
        commodities:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentCreateRequestHandlingUnitCommodity'
          description: The commodities or items that will be conveyed with the shipment.
    ShipmentCreateRequestHandlingUnitCommodity:
      type: object
      properties:
        description:
          type: string
          title: Commodity Name
          description: Commodity name.
          maxLength: 255
        package_type:
          allOf:
          - $ref: '#/components/schemas/PackageTypeEnum'
          description: Package type.
        quantity:
          type: integer
          minimum: 0
          description: Quantity.
        weight:
          type: string
          format: decimal
          pattern: ^-?\d{0,6}(?:\.\d{0,5})?$
          description: |
            Weight of the package, in pounds (LB).
            Values must be positive and contain up to two decimal digits.

            Note that the lowest value is 1 and the maximum value is determined by the equipment_type: 45000 for DRV, 43000 for RFR.
            If the weight is not specified, it is set to the maximum allowable for the equipment_type.
        freight_class:
          allOf:
          - $ref: '#/components/schemas/FreightClassEnum'
          title: Class
          description: Freight Class is used in interstate, intrastate, and international
            commerce for LTL (less than truckload) shipments.
        nmfc_code:
          type: string
          title: NMFC
          description: The NMFC Number for the commodity.
          maxLength: 255
    ShipmentCreateRequestHandlingUnitTypeEnum:
      enum:
      - bags
      - bales
      - boxes
      - bunches
      - carpets
      - coils
      - crates
      - cylinders
      - drums
      - loose
      - pails
      - pallets_non_std
      - reels
      - rolls
      - std_pallets
      - tubes_pipes
      - ubox
      type: string
      description: |-
        * `bags` - Bags
        * `bales` - Bales
        * `boxes` - Boxes
        * `bunches` - Bunches
        * `carpets` - Carpets
        * `coils` - Coils
        * `crates` - Crates
        * `cylinders` - Cylinders
        * `drums` - Drums
        * `loose` - Loose
        * `pails` - Pails
        * `pallets_non_std` - Pallets Non Standard
        * `reels` - Reels
        * `rolls` - Rolls
        * `std_pallets` - Standard Pallets/Skids (48x40)
        * `tubes_pipes` - Tubes and Pipes
        * `ubox` - U-Box
    ShipmentCreateRequestStop:
      type: object
      properties:
        facility_name:
          type: string
          description: The Facility's name.
          maxLength: 255
        address:
          type: string
          description: Address of the facility.
          maxLength: 255
        zipcode:
          type: string
          description: |
            Postal code of the address.
            Accepts:
            - 5-digit for USA (eg: 10108)
            - 6-digit for CAN (eg: N3H 4R7)
          maxLength: 7
          minLength: 5
        city:
          type: string
          description: City of the address.
          maxLength: 100
        state:
          type: string
          description: State of the address. Accepts two-letter abbreviations for
            the states in the USA and CAN.
          maxLength: 2
        country:
          allOf:
          - $ref: '#/components/schemas/CountryEnum'
          description: Country code for the address.
        index:
          type: integer
          minimum: 0
          title: Stop Index
          description: Indicates the order of the stops. The first one must be 0.
        type:
          allOf:
          - $ref: '#/components/schemas/ShipmentCreateRequestStopTypeEnum'
          title: Stop Type
          description: |
            Up to 14 stops allowed, with the first being the pick-up, and the last a delivery.
            If not declared, the first stop will be created as a pickup and all subsequent stops will be set as deliveries.
        planned_date:
          type: string
          format: date
          title: Date
          description: The planned date of the stop, in the form YYYY-MM-DD. It is
            required for the first stop.
        instructions:
          type: string
          title: Instructions (or Notes)
          description: Facility instructions (or Notes) that will be saved for future
            shipment creations.
      required:
      - address
      - city
      - country
      - index
      - state
      - zipcode
    ShipmentCreateRequestStopTypeEnum:
      enum:
      - pickup
      - delivery
      type: string
      description: |-
        * `pickup` - Pickup
        * `delivery` - Delivery
    ShipmentCreateResponse:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          title: Shipment UUID
          description: Unique identifier of the shipment.
      required:
      - uuid
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
servers:
- url: https://api.loadsmart.com/api/v3
  description: Production environment
tags:
- name: Shipments API
  description: This object represents the shipments of your business.
