Loadsmart Shipments API

openapi: 3.2.0
info:
  title: Loadsmart Shipments API
  x-logo:
    altText: Loadsmart API
    url: https://developer.loadsmart.com/logo.svg
  description: "Loadsmart API provides endpoints to quote, book and track shipments autonomously.\n\n# Authentication\n\nLoadsmart API supports JWT tokens for authentication, signed using\npublic/private key pairs (RSA 4096).\n\n## What is JWT?\n\nJSON Web Token (JWT) is an [open standard](https://tools.ietf.org/html/rfc7519) used to\ncreate access tokens that contain some number of claims and is cryptographically signed by\nthe issuer, so its integrity can be verified without an auth server.\n\n## Token algorithm\n\nWe support JWT tokens signed using RS256 algorithm:\n\n```\n{\n  \"alg\": \"RS256\",\n  \"typ\": \"JWT\"\n}\n```\n\n## Required Claims\n\nFor the token payload, we require at least the following claims:\n\n- `sub`: Identifies the subject of the API call. This could be\n  either `sys` (without any user or client context) or `usr:UUID`,\n  where `UUID` is the uuid of the user that will provide the\n  context for the API call.\n- `iss`: Identifies who issued the token. This will be provided by\n  Loadsmart when setting up the integration.\n- `iat`: Standard \"issued at\" claim; should be an unix timestamp.\n- `exp`: Standard \"expires at\" claim; should be an unix timestamp.\n  We recomend to keep the token as short-lived as possible - ideally\n  it should not be valid for more than 1 minute. In the future,\n  Loadsmart could reject tokens with high expiration times.\n\n## Using the token\n\nThe token must be present in the `Authorization` header on all\nrequests, following the format:\n\n```\nAuthorization: JWT <token>\n```\n\nEach part of the token is encoded in base64 and joined with a dot separating each encoded part -\nif you use a library to generate it (which is recommended), you don't need to worry about it.\n\n**Important: Authorization header value must have the prefix `JWT`**.\n\nSee an example:\n\n```\nAuthorization: JWT eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGHSrQyHUdBBPM\n```\n\n## Available contexts\n\nEach token has an implicit context associated with it (usually depending on the value of `sub`\nclaim). This context identifies to the API if the entity doing an action is an user or a system.\n\nLoadsmart API has different token contexts depending on the endpoint being called. Each endpoint\nwill specify the supported contexts (and required scopes) in `AUTHORIZATIONS` section.\n\n<!-- ReDoc-Inject: <security-definitions> -->\n\n## API Access\n\nTo start using Loadsmart API, please get in touch through your\npoint of contact. They will direct you through the proper flow.\n\n### Creating a public/private key pair\n\nFor JWT tokens, you should provide your *public key*. To generate a\npublic and private key pair, you can use OpenSSL:\n\n```bash\n$ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096\n$ openssl rsa -in private_key.pem -pubout -out public_key.pem\n```\n\n*Never* reuse keys between multiple systems.\n\nFor more information, checkout the [official JWT website](https://jwt.io/).\n"
  version: 1.0.0
servers:
- url: https://api.loadsmart.com
  description: Production server
- url: https://api.sandbox.loadsmart.com
  description: Sandbox environment
tags:
- name: Shipments
  description: Manage shipments
paths:
  /api/v2/shipments/{shipment_id}/empty_location:
    post:
      summary: Set empty location
      description: 'Allows a three party partner to set an empty location for a taken load.

        '
      tags:
      - Shipments
      security:
      - User-JWT:
        - shipment_write
      parameters:
      - in: path
        name: shipment_id
        required: true
        schema:
          description: Shipment UUID
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                city:
                  type: string
                  description: Truck empty location's city
                state:
                  type: string
                  description: Truck empty location's state
                zipcode:
                  type: string
                  description: Truck empty location's zipcode (first five digits)
                available_date:
                  type: string
                  description: The date and time the truck is going to be available (UTC)
                  format: date-time
                  pattern: YYYY-MM-DDThh:mm:ssZ
              required:
              - city
              - state
              - zipcode
              - available_date
            example:
            - city: New York
              state: NY
              availability_date: 2016-07-22 12:00:00-03:00
              zipcode: '10007'
      responses:
        '201':
          description: All provided data is valid and the empty location was set.
        '403':
          description: Logged carrier is not related to the shipment and empty location can't be set.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: forbiden_access
                error_description: An user is trying to access a not authorized resource.
        '422':
          description: Payload is invalid or shipment doesn't exist and the empty location can't be set.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: invalid_data
                error_description: Can't create the object
                errors:
                  field_name:
                  - This field is required.
                  other_field:
                  - Expected string but received integer.
  /api/v2/shipments/{shipment_id}/assign_driver:
    post:
      summary: Assign Driver
      description: 'Allows a three party partner to set a driver for a taken load.

        '
      tags:
      - Shipments
      security:
      - User-JWT:
        - shipment_write
      parameters:
      - in: path
        name: shipment_id
        required: true
        schema:
          description: Shipment UUID
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                driver_id:
                  type: string
                  description: Unique identifier for the driver.
              required:
              - driver
            example:
            - driver_id: 63bb49f7-b98c-4a24-8f58-be8b96b5953d
      responses:
        '204':
          description: All provided data is valid and the driver was set.
        '403':
          description: Logged carrier is not related to the driver or is not related to the shipment and driver can't be assign.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: forbiden_access
                error_description: An user is trying to access a not authorized resource.
        '404':
          description: Shipment doesn't exist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
  /api/v2/shipments/{shipment_id}:
    delete:
      summary: Cancel a shipment
      tags:
      - Shipments
      security:
      - User-JWT:
        - shipment_write
      responses:
        '204':
          description: Shipment was canceled
        '404':
          description: Shipment not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
    get:
      summary: Retrieve details from a shipment
      tags:
      - Shipments
      security:
      - User-JWT:
        - shipment_read
      parameters: []
      responses:
        '200':
          description: Shipment was found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier for this shipment
                    readOnly: true
                  ref_number:
                    type: string
                    maxLength: 255
                    description: Internal client's reference, such as an ID, of the load
                  bol_number:
                    type: string
                    maxLength: 255
                    description: The bill of lading number
                  purchase_order_numbers:
                    type: array
                    description: Purchase Orders (PO numbers) associated with this shipment.
                    items:
                      type: string
                  stops:
                    type: array
                    description: Points of interest where the truck makes a stop to either pickup or deliver a shipment. Usually a load has one pickup stop and one delivery stop, but in some cases there will be multiple delivery stops.
                    items:
                      type: object
                      properties:
                        stop_index:
                          type: number
                          description: Indicate the stop number for this event, being 0-based for pickup.
                        address:
                          type: string
                        city:
                          type: string
                        state:
                          type: string
                        zipcode:
                          type: string
                    minItems: 2
                  requirements:
                    type: object
                    description: Requirements that needs to be fulfilled in order to transport the load
                    properties:
                      hazmat:
                        type: boolean
                        description: The commodity being moved consists of hazard material
                      tarp:
                        type: object
                        description: If present in 'requirements', it means the shipment needs a tarp
                        properties:
                          size:
                            type: number
                            format: float
                            minimum: 0
                            description: size in expressed in 'ft'
                          type:
                            type: string
                            enum:
                            - lumber
                            - steel
                            - smoke
                            - parachute
                            - machinery
                            - canvas
                            - hay
                            - poly
                        required:
                        - size
                      dunnage:
                        type: boolean
                        description: Extra rack added to the truck
                      beer:
                        type: boolean
                        description: The carrier must be able to transport alcohool
                      teams:
                        type: boolean
                        description: If it requires a team of drivers
              example:
                data:
                  bol_number: '31871465'
                  ref_number: '24577100'
                  purchase_order_numbers:
                  - abc123
                  - 321cba
                  stops:
                  - address: 2814 S SECOND ST
                    city: St. Louis
                    stop_index: 0
                    state: MO
                    zipcode: '63118'
                  - address: 825 STONE AVE
                    city: Monroe
                    stop_index: 1
                    state: LA
                    zipcode: '71201'
                  requirements:
                    hazmat: false
                    beer: false
                    dunnage: true
                    tarp:
                      size: 10
                      type: lumber
                  id: 2d490b57-6c77-4ee7-8d14-cb9d8d89923d
        '404':
          description: Shipment not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
  /api/v2/shipments/{shipment_id}/interested:
    post:
      summary: Show interest in a shipment.
      description: Inform us about interest in a shipment and request a call.
      tags:
      - Shipments
      security:
      - User-JWT:
        - shipment_read
      parameters:
      - in: path
        name: shipment_id
        required: true
        schema:
          description: Shipment UUID
          type: string
          format: uuid
      responses:
        '200':
          description: Shipment was found and the message was sent.
        '404':
          description: Shipment not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
  /api/v2/shipments/{shipment_id}/action-logs:
    post:
      summary: Create shipment action log entry
      description: 'Appends an action to the shipment''s action log.

        '
      security:
      - Application-JWT:
        - shipment_action_log
      parameters:
      - in: path
        name: shipment_id
        required: true
        schema:
          description: Shipment or Load UUID
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: 'Request body to create a shipment action log entry. The `action` text is combined with the

                caller''s client name when persisted.

                '
              properties:
                action:
                  type: string
                  maxLength: 255
                  description: Action text to record for this shipment (max 255 characters).
              required:
              - action
            example:
              action: Manual gate check completed at pickup
      responses:
        '201':
          description: Action log entry was created
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: forbiden_access
                error_description: An user is trying to access a not authorized resource.
        '404':
          description: Shipment not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: object_not_found
                error_description: Object not found
        '422':
          description: 'Shipment is not eligible for action logs.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: invalid_data
                error_description: Can't create the object
                errors:
                  field_name:
                  - This field is required.
                  other_field:
                  - Expected string but received integer.
      tags:
      - Shipments
  /api/v2/shipment-documents:
    post:
      summary: Create shipment document
      description: Send a shipment document for audit it can be a proof of delivery, carrier invoice or any other document.
      tags:
      - Shipments
      security:
      - User-JWT:
        - submitted_shipment_document_write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                shipment:
                  type: string
                  description: The shipment UUID or Loadsmart ref number.
                file_obj:
                  type: binary
                  description: The shipment pdf file.
                file_name:
                  type: string
                  description: The file name.
                type:
                  type: string
                  description: The file type.
                  enum:
                  - carrier-invoice
                  - proof-of-delivery
                  - other
              required:
              - shipment
              - file_obj
              - file_name
              - type
            example:
              shipment: ac483d72-83c5-41cd-97bf-ce94517e7bc5
              file_obj: (binary)
              file_name: 9444666.pdf
              type: carrier-invoice
      responses:
        '201':
          description: Shipment document successfully created.
        '403':
          description: Logged carrier is incorrect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: forbiden_access
                error_description: An user is trying to access a not authorized resource.
        '422':
          description: Payload is invalid and the document wasn't created for the shipment
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: invalid_data
                error_description: Can't create the object
                errors:
                  field_name:
                  - This field is required.
                  other_field:
                  - Expected string but received integer.
  /api/v2/shipment-documents/?shipment=${shipment}:
    get:
      summary: List shipment documents
      description: List of shipment documents sent via shipment-documents.
      tags:
      - Shipments
      security:
      - User-JWT:
        - submitted_shipment_document_read
      parameters:
      - in: path
        name: shipment_uuid_or_loadsmart_ref_number
        required: true
        schema:
          description: Shipment's UUID or internal ref number in Loadsmart
          type: string
      responses:
        '200':
          description: Success list of shipment documents sent via shipment-documents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique identifier for the document.
                        shipment:
                          type: string
                          description: shipment UUID.
                        shipment_loadsmart_ref_number:
                          type: string
                          description: shipment's internal ref number in Loadsmart.
                        created_at:
                          type: string
                          description: Datetime when the document was created.
                          format: date-time
                        type:
                          type: enum
                          description: Document type.
                        file_name:
                          type: string
                          description: File name for document sent.
                        url:
                          type: enum
                          description: Url with a expiration time for the document.
              example:
                data:
                - id: '444'
                  created_at: 2024-01-01 00:00:00+00:00
                  shipment: ac483d72-83c5-41cd-97bf-ce94517e7bc5
                  shipment_loadsmart_ref_number: '9444666'
                  type: carrier-invoice
                  file_name: 9444666.pdf
                  url: https://my.com/submitted-shipment-documents/9444666/carrier-invoice/9444666.pdf
        '403':
          description: Logged carrier is incorrect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                    - invalid_data
                  error_description:
                    type: string
                    description: Description of what happened
                  errors:
                    type: object
                    description: Object where each field is a key and the value is an array of errors
                required:
                - error
                - error_description
              example:
                error: forbiden_access
                error_description: An user is trying to access a not authorized resource.
  /api/v2/shipmentscores:
    get:
      summary: Retrieve shipment scores
      tags:
      - Shipments
      security:
      - User-JWT:
        - shipment_score_read
      parameters:
      - in: query
        name: start_date
        schema:
          type: string
          format: date
          pattern: YYYY-MM-DD
        description: Start date for shipment scores
      - in: query
        name: end_date
        schema:
          type: string
          format: date
          pattern: YYYY-MM-DD
        description: End date for shipment scores
      - in: query
        name: shipper_uuid
        schema:
          type: uuid
        description: Filter shipment scores by shipper
      responses:
        '200':
          description: Shipment scores
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        shipment_uuid:
                          type: uuid
                        shipment_ref:
                          type: string
                        source:
                          type: string
                        pickup_city:
                          type: string
                        pickup_state:
                          type: string
                        delivery_city:
                          type: string
                        delivery_state:
                          type: string
                        otp:
                          type: boolean
                        otd:
                          type: boolean
                        audited:
                          type: boolean
                        delivered_at:
                          type: datetime
                          format: date-time
                        carrier_name:
                          type: string
                        carrier_uuid:
                          type: uuid
                        overridden:
                          type: string
                        shipper_uuid:
                          type: uuid
                  count:
                    type: number
                    format: integer
                  next:
                    type: string
                    format: url
                  previous:
                    type: string
                    format: url
              example:
                data:
                - audited: false
                  carrier_name: JONES EXPRESS, INC.
                  carrier_uuid: ab51fded-cc5b-4338-ad41-69c98ecdeaa4
                  delivered_at: 2019-10-18 13:20:36+00:00
                  delivery_city: Buford
                  delivery_state: GA
                  otd: true
                  otp: false
                  overridden: ''
                  pickup_city: Grand Rapids
                  pickup_state: MI
                  shipment_ref: '9290080'
                  shipment_uuid: b5cfc16c-37d2-4e1a-a481-3e0ec5e05cdf
                  shipper_uuid: 320bea98-c46a-493a-860d-f9bdd49c39a9
                  source: alice
                - audited: false
                  carrier_name: CELADON TRUCKING SERVICES INC
                  carrier_uuid: d11a1f7c-fad9-4ff9-b0ba-34fc93f63c3f
                  delivered_at: 2019-10-18 13:04:00+00:00
                  delivery_city: Grimes
                  delivery_state: IA
                  otd: true
                  otp: true
                  overridden: ''
                  pickup_city: Salisbury
                  pickup_state: NC
                  shipment_ref: '9290018'
                  shipment_uuid: 0d6527b4-c091-4f4e-99af-4634b7de1a74
                  shipper_uuid: 320bea98-c46a-493a-860d-f9bdd49c39a9
                  source: alice
                - audited: false
                  carrier_name: JD LOGISTIC
                  carrier_uuid: 4591734a-9ce8-47f3-a0bf-9872e4734d70
                  delivered_at: 2019-10-18 12:30:00+00:00
                  delivery_city: Swedesboro
                  delivery_state: NJ
                  otd: true
                  otp: true
                  overridden: ''
                  pickup_city: Walton
                  pickup_state: KY
                  shipment_ref: '9289985'
                  shipment_uuid: a5675679-6b06-4206-8eb9-f930b64ca255
                  shipper_uuid: 320bea98-c46a-493a-860d-f9bdd49c39a9
                  source: alice
                - audited: false
                  carrier_name: TRANSPORT AMERICA
                  c

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