Loadsmart ShipperGuide API

openapi: 3.0.1
info:
  title: Loadsmart 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.

    # Authentication

    Loadsmart API supports JWT tokens for authentication, signed using
    public/private key pairs (RSA 4096).

    ## What is JWT?

    JSON Web Token (JWT) is an [open standard](https://tools.ietf.org/html/rfc7519) used to
    create access tokens that contain some number of claims and is cryptographically signed by
    the issuer, so its integrity can be verified without an auth server.

    ## Token algorithm

    We support JWT tokens signed using RS256 algorithm:

    ```
    {
      "alg": "RS256",
      "typ": "JWT"
    }
    ```

    ## Required Claims

    For the token payload, we require at least the following claims:

    - `sub`: Identifies the subject of the API call. This could be
      either `sys` (without any user or client context) or `usr:UUID`,
      where `UUID` is the uuid of the user that will provide the
      context for the API call.
    - `iss`: Identifies who issued the token. This will be provided by
      Loadsmart when setting up the integration.
    - `iat`: Standard "issued at" claim; should be an unix timestamp.
    - `exp`: Standard "expires at" claim; should be an unix timestamp.
      We recomend to keep the token as short-lived as possible - ideally
      it should not be valid for more than 1 minute. In the future,
      Loadsmart could reject tokens with high expiration times.

    ## Using the token

    The token must be present in the `Authorization` header on all
    requests, following the format:

    ```
    Authorization: JWT <token>
    ```

    Each part of the token is encoded in base64 and joined with a dot separating each encoded part -
    if you use a library to generate it (which is recommended), you don't need to worry about it.

    **Important: Authorization header value must have the prefix `JWT`**.

    See an example:

    ```
    Authorization: JWT eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGHSrQyHUdBBPM
    ```

    ## Available contexts

    Each token has an implicit context associated with it (usually depending on the value of `sub`
    claim). This context identifies to the API if the entity doing an action is an user or a system.

    Loadsmart API has different token contexts depending on the endpoint being called. Each endpoint
    will specify the supported contexts (and required scopes) in `AUTHORIZATIONS` section.

    <!-- ReDoc-Inject: <security-definitions> -->

    ## API Access

    To start using Loadsmart API, please get in touch through your
    point of contact. They will direct you through the proper flow.

    ### Creating a public/private key pair

    For JWT tokens, you should provide your *public key*. To generate a
    public and private key pair, you can use OpenSSL:

    ```bash
    $ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096
    $ openssl rsa -in private_key.pem -pubout -out public_key.pem
    ```

    *Never* reuse keys between multiple systems.

    For more information, checkout the [official JWT website](https://jwt.io/).
  version: 1.0.0
components:
  securitySchemes:
    Application-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Authorize the request with the application context (preferred
        for the endpoints that support it):

        ```
        {
          "sub": "sys",
          "iss": "token-issuer",
          "exp": 1626239022,
          "iat": 1517239022
        }
        ```
    User-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Authorize the request with an user context. A payload example
        would be:

        ```
        {
          "sub": "usr:87127882-d1db-4e50-8f7c-c792a80d7c49",
          "iss": "token-issuer",
          "iat": 1517239022,
          "exp": 1626239022
        }
        ```
  schemas:
    ShipmentMode:
      type: string
      default: FTL
      enum:
        - FTL
        - LTL
        - PTL
        - RAIL
      description: |
        The transportation mode of the load. Allowed values are:
        - FTL: Full Truckload
        - LTL: Less-than-Truckload
        - PTL: Partial Truckload
        - RAIL: Intermodal rail (53' containers)
    InternalShipmentMode:
      type: string
      default: FTL
      enum:
        - ANY
        - EXP
        - FCL
        - FTL
        - LTL
        - PTL
        - RAIL
        - VLTL
      description: |
        The transportation mode of the load. Allowed values are:
        - ANY
        - EXP: Expedited
        - FTL: Full Truckload
        - FCL: Ful Container Load
        - LTL: Less-than-Truckload
        - PTL: Partial Truckload
        - RAIL: Intermodal rail (53' containers)
        - VLTL: Volume  Less-than-Truckload
    TenderExternalShipmentMode:
      type: string
      default: FTL
      enum:
        - FTL
        - LTL
      description: |
        The transportation mode of the load. Allowed values are:
        - FTL: Full Truckload
        - LTL: Less-than-Truckload
    QuoteRequestEquipmentTypes:
      type: string
      enum:
        - DRV
        - FBE
        - RFR
        - IMC
      description: |
        Equipment required to transport the shipment. Recognized equipments are:
          - DRV: Dry Van
          - FBE: Flatbed
          - RFR: Reefer
          - IMC: Intermodal
    InternalQuoteRequestEquipmentTypes:
      type: string
      enum:
        - BTR
        - CGV
        - DRV
        - dry
        - FBE
        - HOT
        - IMC
        - reefer
        - RFR
        - SPR
        - STR
      description: |
        Equipment required to transport the shipment. Recognized equipments are:
          - BTR: Box Truck
          - CGV: Cargo Van
          - DRV: Dry Van
          - dry: Dry Container
          - FBE: Flatbed
          - HOT: Hotshot
          - IMC: Intermodal
          - reefer: Reefer Container
          - RFR: Reefer
          - SPR: Sprinter Van
          - STR: Straight Truck
    EquipmentType:
      type: string
      enum:
        - DRV
        - FBE
        - RFR
        - CON
        - CUR
        - DDP
        - IMC
        - SDK
        - STK
        - BLK
        - TNK
        - OTH
      description: |
        Equipment required to transport the shipment. Recognized equipments are:
          - DRV: Dry Van
          - FBE: Flatbed
          - RFR: Reefer
          - CON: Conestoga
          - CUR: Curtainside
          - DDP: Double Drop
          - IMC: Intermodal
          - SDK: Step Deck
          - STK: Straight truck
          - BLK: Bulk
          - TNK: Tanker
          - OTH: Other equipment not explicited listed
    PhoneNumber:
      type: string
      pattern: \+\d{4,15}
      maxLength: 16
      description: Phone number following the format [E.164](https://www.itu.int/rec/T-REC-E.164/)
    TotalWidth:
      type: number
      description: The load total width expressed in 'ft'
      minimum: 0
    TotalLength:
      type: number
      description: The load total length expressed in 'ft'
      minimum: 0
    TotalHeight:
      type: number
      description: The load total height expressed in 'ft'
      minimum: 0
    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
servers:
  - url: https://api.loadsmart.com
    description: Production server
  - url: https://api.sandbox.loadsmart.com
    description: Sandbox environment
paths:
  /api/v2/carrier/search:
    get:
      summary: Search a carrier
      tags:
        - Carrier
      security:
        - Application-JWT:
            - carrier_search
      description: |
        Search a carrier by dot or mc
      parameters:
        - in: query
          name: mc
          schema:
            description: Carrier mc
            type: string
            format: integer
          required: false
        - in: query
          name: dot
          schema:
            description: Carrier dot
            type: string
            format: integer
          required: false
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  mc:
                    type: string
                  dot:
                    type: string
                  eligible:
                    type: bool
                    description: |
                      Flag that report if the Carrier is eligible to carry loads
                  status:
                    type: string
                    enum:
                      - NEW
                      - PENDING
                      - READY
                    description: |
                      Onboarding process status:
                      `NEW` means that Carrier is New
                      `PENDING` means that Onboard Process is under review
                      `READY` means that Carrier is successfully onboarded
              example:
                id: 9b739d7a-b4db-45f7-a61b-990c7ac77082
                dot: "2953461"
                mc: "456"
                status: New
                eligible: false
                name: J R T TRANS CORP
        "400":
          description: Invalid parameters
          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:
                missing_parameters:
                  - query must have mc or dot fields
        "404":
          description: Carrier 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/carrier/integrations:
    get:
      summary: List of integrations
      tags:
        - Carrier
      security:
        - Application-JWT:
            - carrier_read
      description: |
        List the integrations that the intermediary have with loadsmart
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: An array of integrations
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                  count:
                    type: integer
                  next:
                    type: string
                  previous:
                    type: string
              example:
                count: 2
                next: null
                previous: null
                data:
                  - id: f0c1b42c-9f8b-434e-9971-ae1c527e2680
                  - id: d11a1f7c-fad9-4ff9-b0ba-34fc93f63c3f
  /api/v2/carrier/integration-request:
    post:
      summary: Request Integration for a Carrier
      description: |
        3PP can integrate a carrier and create a Carrier Account
      security:
        - Application-JWT:
            - request_integration_write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                carrier_id:
                  type: string
                  description: Carrier UUID
                  maxLength: 255
                owner:
                  type: object
                  description: Company main contact information.
                  properties:
                    first_name:
                      type: string
                      description: First Name
                      maxLength: 255
                    last_name:
                      type: string
                      description: Last Name
                      maxLength: 255
                    email:
                      type: string
                      description: Email Address
                      maxLength: 255
                    phone_number:
                      type: string
                      pattern: \+\d{4,15}
                      maxLength: 16
                      description: Phone number following the format [E.164](https://www.itu.int/rec/T-REC-E.164/)
                    phone_number_extension:
                      type: string
                      description: Phone Number Extension
                      maxLength: 255
                  required:
                    - first_name
                    - last_name
                    - email
              required:
                - carrier_id
            example:
              carrier_id: 9f87d040-f843-42e7-887a-45bea55e76f3
              owner:
                first_name: John
                last_name: Doe
                email: john.doe@email.com
                phone_number: "+1111111111"
                phone_number_extension: "123"
      responses:
        "200":
          description: Integration Request with same data already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique Identifier of the Integration Request
                  account_id:
                    type: string
                    description: Unique Identifier of the Account
                  carrier:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique Identifier of the Carrier on Loadsmart
                      mc:
                        type: string
                        description: Carrier Interstate Operating Authority (MC number)
                      dot:
                        type: string
                        description: Carrier US DOT Number
                      name:
                        type: string
                        description: Carrier legal name
                      eligible:
                        type: bool
                        description: Flag that report if the Carrier is eligible to carry loads
                      status:
                        type: string
                        enum:
                          - New
                          - Pending
                          - Ready
                          - Inactive
                        description: Carrier status on Loadsmart
                  status:
                    type: string
                    enum:
                      - pending
                      - accepted
                      - rejected
                    description: |
                      Status of the Integration Request
                      - pending: waiting/under evaluation from Carrier owner and/or Loadsmart
                      - accepted: Integration Request accepted
                      - rejected: Integration Request rejected by Carrier owner and/or Loadsmart
                  documents:
                    type: array
                    description: List of required documents and its status
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Document type (Form W9, Insurance or Authority)
                        status:
                          type: string
                          enum:
                            - missing
                            - under-review
                            - accepted
              example:
                id: fe17b7e7-6453-4520-b99d-2d2b44972468
                account_id: bc32c4d4-5732-7845-aa32-132cdab5467b
                carrier:
                  id: 9f87d040-f843-42e7-887a-45bea55e76f3
                  mc: "12345"
                  dot: "54321"
                  name: John Doe Freights
                  status: new
                  eligible: false
                status: PENDING
                documents:
                  - type: w9
                    status: missing
                  - type: insurance
                    status: under-review
                  - type: authority
                    status: accepted
        "201":
          description: Integration Request successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique Identifier of the Integration Request
                  account_id:
                    type: string
                    description: Unique Identifier of the Account
                  carrier:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique Identifier of the Carrier on Loadsmart
                      mc:
                        type: string
                        description: Carrier Interstate Operating Authority (MC number)
                      dot:
                        type: string
                        description: Carrier US DOT Number
                      name:
                        type: string
                        description: Carrier legal name
                      eligible:
                        type: bool
                        description: Flag that report if the Carrier is eligible to carry loads
                      status:
                        type: string
                        enum:
                          - New
                          - Pending
                          - Ready
                          - Inactive
                        description: Carrier status on Loadsmart
                  status:
                    type: string
                    enum:
                      - pending
                      - accepted
                      - rejected
                    description: |
                      Status of the Integration Request
                      - pending: waiting/under evaluation from Carrier owner and/or Loadsmart
                      - accepted: Integration Request accepted
                      - rejected: Integration Request rejected by Carrier owner and/or Loadsmart
                  documents:
                    type: array
                    description: List of required documents and its status
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Document type (Form W9, Insurance or Authority)
                        status:
                          type: string
                          enum:
                            - missing
                            - under-review
                            - accepted
              example:
                id: fe17b7e7-6453-4520-b99d-2d2b44972468
                account_id: bc32c4d4-5732-7845-aa32-132cdab5467b
                carrier:
                  id: 9f87d040-f843-42e7-887a-45bea55e76f3
                  mc: "12345"
                  dot: "54321"
                  name: John Doe Freights
                  status: new
                  eligible: false
                status: PENDING
                documents:
                  - type: w9
                    status: missing
                  - type: insurance
                    status: under-review
                  - type: authority
                    status: accepted
        "404":
          description: Carrier 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: Integration already requested
          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:
        - Carrier
    get:
      summary: List Carrier Integration Request status
      description: |
        List partner's integration requests
      security:
        - Application-JWT:
            - request_integration_read
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: An array of integrations
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique Identifier of the Integration Request
                        carrier_id:
                          type: string
                          description: Unique Identifier of the Carrier on Loadsmart
                        mc:
                          type: string
                          description: Carrier Interstate Operating Authority (MC number)
                        dot:
                          type: string
                          description: Carrier US DOT Number
                        name:
                          type: string
                          description: Carrier legal name
                        status:
                          type: string
                          enum:
                            - pending
                            - accepted
                            - rejected
                          description: |
                            Status of the Integration Request
                            - pending: waiting/under evaluation from Carrier owner and/or Loadsmart
                            - accepted: Integration Request accepted
                            - rejected: Integration Request rejected by Carrier owner and/or Loadsmart
                  count:
                    type: integer
                  next:
                    type: string
                  previous:
                    type: string
              example:
                count: 1
                next: null
                previous: null
                data:
                  - id: fe17b7e7-6453-4520-b99d-2d2b44972468
                    carrier_id: bc32c4d4-5732-7845-aa32-132cdab5467b
                    mc: "12345"
                    dot: "54321"
                    name: John Doe Freights
                    status: pending
        "404":
          description: No integration requests 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
      tags:
        - Carrier
  "/api/v2/carrier/integration-request/{id}":
    get:
      summary: Detail Carrier Integration Request status
      description: |
        3PP can check the Integrate Status of a Carrier
      security:
        - Application-JWT:
            - request_integration_read
      parameters:
        - in: path
          name: id
          schema:
            description: Unique Integration Request identifier
            type: string
            format: uuid
          required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique Identifier of the Integration Request
                  account_id:
                    type: string
                    description: Unique Identifier of the Account
                  carrier:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique Identifier of the Carrier on Loadsmart
                      mc:
                        type: string
                        description: Carrier Interstate Operating Authority (MC number)
                      dot:
                        type: string
                        description: Carrier US DOT Number
                      name:
                        type: string
                        description: Carrier legal name
                      eligible:
                        type: bool
                        description: Flag that report if the Carrier is eligible to carry loads
                      status:
                        type: string
                        enum:
                          - New
                          - Pending
                          - Ready
                          - Inactive
                        description: Carrier status on Loadsmart
                  status:
                    type: string
                    enum:
                      - pending
                      - accepted
                      - rejected
                    description: |
                      Status of the Integration Request
                      - pending: waiting/under evaluation from Carrier owner and/or Loadsmart
                      - accepted: Integration Request accepted
                      - rejected: Integration Request rejected by Carrier owner and/or Loadsmart
                  documents:
                    type: array
                    description: List of required documents and its status
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Document type (Form W9, Insurance or Authority)
                        status:
                          type: string
                          enum:
                            - missing
                            - under-review
                            - accepted
              example:
                id: fe17b7e7-6453-4520-b99d-2d2b44972468
                account_id: bc32c4d4-5732-7845-aa32-132cdab5467b
                carrier:
                  id: 9f87d040-f843-42e7-887a-45bea55e76f3
                  mc: "12345"
                  dot: "54321"
                  name: John Doe Freights
                  status: new
                  eligible: false
                status: PENDING
                documents:
                  - type: w9
                    status: missing
                  - type: insurance
                    status: under-review
                  - type: authority
                    status: accepted
        "404":
          description: Integrate Request 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
      tags:
        - Carrier
  /api/v2/carrier/documents:
    post:
      summary: Upload document
      description: Uploads Carrier related documents, such as Form W9, Insurance and
      security:
        - User-JWT:
            - carrier_write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
        

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