Loadsmart Loads API

openapi: 3.2.0
info:
  title: Loadsmart Loads 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: Loads
  description: 'This endpoint will be the entrypoint for our integrations. It will receive loads.

    '
paths:
  /api/v2/loads/{load_id}/events:
    get:
      summary: List Load Events
      description: "\nProvides a list of the events (rejected, accepted, etc) regarding a load previously tendered to Loadsmart.\n\nThis is an alternative way to obtain feedback whether a tendered load was accepted or rejected (you can also receive load events by Webhooks - see [Load Webhooks](#tag/Webhooks/paths/~1load-webhooks/post) section).\nThe List Load Events endpoint was designed to be polled, so you don't need to expose an endpoint where Loadsmart would send the accepted/rejected webhook.\n\nAlthough loads and shipments usually refer to the same thing, Loadsmart handles them as two slightly different entities.\nUp to the point when a load is tendered and booked, the entity in play is a “load”.\nAfter this load is booked, it becomes a shipment. From this point on, communication is done with the shipment.\n\nList of event types/actions:\n  - awarded\n  - accepted\n  - canceled\n  - rejected\n"
      security:
      - User-JWT:
        - load_read
      responses:
        '200':
          description: Load was found
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    description: Number of objects found
                    type: number
                    format: integer
                  next:
                    description: URL for next page of results
                    type: string
                    format: url
                  previous:
                    description: URL for previous page of results
                    type: string
                    format: url
                  data:
                    type: array
                    items:
                      allOf:
                      - type: object
                        properties:
                          id:
                            description: Load event unique identifier
                            type: string
                            format: uuid
                          action:
                            description: Event type
                            type: string
                          created:
                            description: The date and time of the event creation
                            type: string
                            format: date-time
                          load_id:
                            description: Load unique identifier
                            type: string
                            format: uuid
              example:
                count: 2
                next: null
                previous: null
                data:
                - id: 54b8e6cb-d038-455f-af44-d78fed519172
                  action: awarded
                  created: 2021-01-06 17:15:12.275594+00:00
                  load_id: 20eccb85-b1cf-4d40-b904-9e2e05981911
                - id: 81c5c1ac-9f6f-4725-81f7-887bd5a9da61
                  action: accepted
                  created: 2021-01-06 17:18:12.552749+00:00
                  load_id: 20eccb85-b1cf-4d40-b904-9e2e05981911
        '404':
          description: Load was 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:
      - Loads
  /api/v2/loads/tender:
    post:
      summary: Create tender
      description: "Tender a load to Loadsmart. The load could be either a spot or contracted one. If the endpoint returns\na successful status code, it means that we have received the load.\n\nIn order to see if the load was accepted or rejected, you must listen for the `load:accepted` and\n`load:rejected` webhooks, respectively. See [Load Webhooks](#tag/Webhooks/paths/~1load-webhooks/post) section.\n\nImportant: the uuid returned identifies a load uniquely in Loadsmart systems. This means that,\n for two or more responses, if they contain the same uuid, they are related to the exact same load.\n\nQuotes that have been created using the `/quote` endpoint can be booked with the tender endpoint if\nthe `quote_id` parameter, provided by the [Create Quote](#tag/Quotes/paths/~1api~1v2~1quotes/post) endpoint, is sent.\n"
      security:
      - User-JWT:
        - tender_write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  default: FTL
                  allOf:
                  - x-external: true
                    type: string
                    default: FTL
                    enum:
                    - FTL
                    - LTL
                    description: 'The transportation mode of the load. Allowed values are:

                      - FTL: Full Truckload

                      - LTL: Less-than-Truckload

                      '
                equipment_type:
                  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:\n  - DRV: Dry Van\n  - FBE: Flatbed\n  - RFR: Reefer\n  - CON: Conestoga\n  - CUR: Curtainside\n  - DDP: Double Drop\n  - IMC: Intermodal\n  - SDK: Step Deck\n  - STK: Straight truck\n  - BLK: Bulk\n  - TNK: Tanker\n  - OTH: Other equipment not explicited listed\n"
                customer_ref:
                  type: string
                  maxLength: 255
                  description: Internal client's reference, such as an ID, of the tender
                quote_id:
                  type: string
                  maxLength: 40
                  description: Reference for the quote that should be used to book the load
                commodity:
                  type: string
                  maxLength: 255
                  description: Name of the commodity that will be shipped
                source:
                  type: string
                  maxLength: 64
                  description: Field used to indicate the context where the tender request was made (in a contract, routing guide process or spot bid, for example)
                weight:
                  oneOf:
                  - type: number
                  - type: string
                  description: 'The total weight, in pounds, of the shipment. Acceptable values must be positive numbers with up to 2 decimal digits.

                    Any other type will cause a validation error. Note that the minimum value is 1 and the maximum value

                    depends on the chosen equipment_type: 45000 for DRV, 43000 for RFR and 50000 for FBE.

                    If the weight is not provided, it is set to the maximum allowed for the equipment_type.

                    '
                  minimum: 1
                  maximum: 50000
                stops:
                  type: array
                  description: Points of interest where the truck makes a stop to either pickup or deliver a shipment. Usually a tender has one pickup stop and one delivery stop, but in some cases there will be multiple delivery stops.
                  items:
                    oneOf:
                    - type: object
                      title: Zipcode
                      properties:
                        type:
                          type: string
                          enum:
                          - PU
                          - DEL
                          description: The type of the stop, can be PU (Pickup) or DEL (Delivery)
                        facility_name:
                          type: string
                          description: Name of the facility at this stop
                        facility_ref:
                          type: string
                          description: A reference used to identify the facility among tenders requests
                        address:
                          type: string
                        city:
                          type: string
                        state:
                          type: string
                        zipcode:
                          type: string
                        country:
                          type: string
                          pattern: ^[A-Z]{3}$
                          description: 3-letter country code, uppercase (ISO 3166-1 alpha-3)
                        contacts:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                description: Name of the person who is the contact at this stop
                                maxLength: 255
                              email:
                                type: string
                                format: email
                                description: Email of the contact. Required if no phone number is provided
                                maxLength: 254
                              phone_number:
                                description: Phone number of the contact. Required if email is provided
                                type: string
                                pattern: \+\d{4,15}
                                maxLength: 16
                            required:
                            - name
                        window_start:
                          description: A window start indicating the start local time of the truck at the stop (required for first stop)
                          type: string
                          format: naive date-time
                        window_end:
                          description: A window end indicating the end local time of the truck stop at the stop
                          type: string
                          format: naive date-time
                        drop_trailer:
                          type: boolean
                          description: Indicates whether the truck will drop the trailer at the stop
                        stop_customer_ref:
                          type: string
                          description: Shipper identifier for this stop
                        instructions:
                          type: string
                          description: Instructions for the driver
                        requirements:
                          type: object
                          description: An object with specific requirements for this stop
                          properties:
                            loading_type:
                              type: string
                              enum:
                              - floor_loaded
                              - palletized
                              description: 'Indicates if the load should be floor loaded in this stop, or if it''s palletized

                                '
                      required:
                      - zipcode
                      - country
                      - window_start
                    - type: object
                      title: City & State
                      properties:
                        type:
                          type: string
                          enum:
                          - PU
                          - DEL
                        facility_name:
                          type: string
                          description: Name of the facility at this stop
                        facility_ref:
                          type: string
                          description: A reference used to identify the facility among tenders requests
                        stop_customer_ref:
                          type: string
                          description: Shipper identifier for this stop
                        address:
                          type: string
                        city:
                          type: string
                        state:
                          type: string
                          description: two-letters state code
                        zipcode:
                          type: string
                        country:
                          type: string
                          pattern: ^[A-Z]{3}$
                          description: 3-letter country code, uppercase (ISO 3166-1 alpha-3)
                        contacts:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                description: Name of the person who is the contact at this stop
                                maxLength: 255
                              email:
                                type: string
                                format: email
                                description: Email of the contact. Required if no phone number is provided
                                maxLength: 254
                              phone_number:
                                description: Phone number of the contact. Required if email is provided
                                type: string
                                pattern: \+\d{4,15}
                                maxLength: 16
                            required:
                            - name
                        window_start:
                          description: A window start indicating the start local time of the truck at the stop (required for first stop)
                          type: string
                          format: naive date-time
                        window_end:
                          description: A window end indicating the end local time of the truck stop at the stop (required for first stop)
                          type: string
                          format: naive date-time
                        drop_trailer:
                          type: boolean
                          description: Indicates whether the truck will drop the trailer at the stop
                        instructions:
                          type: string
                          description: Instructions for the driver
                      required:
                      - city
                      - state
                      - country
                      - window_start
                      - window_end
                  minItems: 2
                contacts:
                  type: array
                  description: At least name or phone number should be provided for each contact.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Name of the person who is the contact at this stop
                        maxLength: 255
                      email:
                        type: string
                        format: email
                        description: Email of the contact. Required if no phone number is provided
                        maxLength: 254
                      phone_number:
                        description: Phone number of the contact. Required if email is provided
                        type: string
                        pattern: \+\d{4,15}
                        maxLength: 16
                    required:
                    - name
                purchase_order_numbers:
                  type: array
                  description: Purchase Order Numbers for the load
                  items:
                    type: object
                    properties:
                      po_number:
                        type: string
                        description: Purchase order number
                properties:
                  type: object
                  description: 'General information about the load.

                    This is an open JSON field that allows passing special properties with meaning on the customer context, such as the order numbers, must_arrive_by_date, and others.

                    '
                  properties: {}
                requirements:
                  type: object
                  description: An object with any specific requirement for this tender
                  properties:
                    promotion_load:
                      type: boolean
                      description: Indicates the load requires expediting since customer needs the product for an in-store promotion
                    emergency_response:
                      type: boolean
                      description: An emergency response flag
                    hazmat:
                      type: boolean
                      description: Indicates that the load  must consider the presence of hazardous materials
                    beer:
                      type: boolean
                      description: Indicates that the load requires permission to move beer
                    twic:
                      type: boolean
                      description: Indicates if the carrier is required to have a TWIC card
                    ctpat:
                      type: boolean
                      description: CTPAT recognition
                    teams:
                      type: boolean
                      description: Indicates if the load requires a team of drivers
                    food_grade:
                      type: boolean
                      description: Indicates if load requires food grade trailers
                    frozen:
                      type: boolean
                      description: Indicates if load requires to be moved frozen
                    produce:
                      type: boolean
                      description: Indicates if the load contains produce
                    pharmaceuticals:
                      type: boolean
                      description: Indicates if the load contains pharmaceuticals
                    chemicals:
                      type: boolean
                      description: Indicates if the load contains chemicals
                    tsa:
                      type: boolean
                      description: Indicates if the carrier is required to have a TSA card
                    hvhr:
                      type: boolean
                      description: Indicates if the load is high value or high risk
                    vented_vans:
                      type: boolean
                      description: Indicates if the load requires vented vans
                bill_to:
                  type: object
                  description: An object with billing information
                  properties:
                    company_name:
                      type: string
                      maxLength: 255
                      description: Bill to Company Name
                    address1:
                      type: string
                      maxLength: 255
                      description: Bill to address
                    address2:
                      type: string
                      maxLength: 255
                      description: Continuation of bill to address
                    city:
                      type: string
                      maxLength: 255
                      description: Bill to city
                    zipcode:
                      type: string
                      maxLength: 255
                      description: Bill to zipcode
                    state:
                      type: string
                      maxLength: 255
                      description: Bill to state
                    country:
                      type: string
                      maxLength: 255
                      pattern: ^[A-Z]{3}$
                      description: 3-letter country code, uppercase (ISO 3166-1 alpha-3)
                bol_number:
                  type: string
                  maxLength: 255
                  description: the bill of lading number for the tender
              required:
              - customer_ref
              - equipment_type
              - stops
            example:
              equipment_type: DRV
              commodity: apples
              weight: 20000
              customer_ref: a reference for the tender
              properties:
                private_id: CAR-7725B
                my_numbers:
                - 44234
                - 10534
                - 8875
              requirements:
                hazmat: true
              bol_number: the bill of lading number for the tender
              quote_id: quote_12345643
              purchase_order_numbers:
              - '12345'
              - ABCDE
              stops:
              - type: PU
                facility_name: Brothers & Sons Inc.
                facility_ref: asjf1984jd112o8
                address: 101 Collins Avenue
                city: Miami Beach
                state: FL
                country: USA
                contacts:
                - name: John Doe
                  email: john@example.com
                  phone_number: '+17895551234'
                drop_trailer: false
                stop_customer_ref: ABC123
                zipcode: '33139'
                window_start: 2018-06-20 09:00:00
                window_end: 2018-06-20 11:00:00
                instructions: Driver must arrive on time. These instructions will be sent to driver.
                requirements:
                  loading_type: palletized
              - type: DEL
                facility_name: Space Ghost Coast to Coast Inc.
                facility_ref: ascm1394u
                address: 2022 Collins Avenue
                city: Miami Beach
                state: FL
                country: USA
                zipcode: '33140'
                contacts:
                - name: Space Ghost
                  email: space@ghost.com
                  phone_number: '+17124832133'
                drop_trailer: false
                stop_customer_ref: 343254-TP
                window_start: 2018-06-21 16:00:00
                window_end: 2018-06-21 18:00:00
                instructions: No special instructions here.
                requirements:
                  loading_type: palletized
              bill_to:
                company_name: Acme
                address1: 1st Street
                address2: null
                city: Springfield
                zipcode: 12345
                state: TX
                country: USA
      responses:
        '200':
          description: Tender was posted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for this load. Use this id to later match with the Webhook/load with the acceptance of the load.
                        readOnly: true
                    required:
                    - id
              example:
                data:
                  id: 3fa68364-4f39-4cf1-a042-5e57215b7150
        '422':
          description: Invalid or missing data
          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:
      - Loads
components:
  securitySchemes:
    Application-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Authorize the request with the application context (preferred\nfor the endpoints that support it):\n\n```\n{\n  \"sub\": \"sys\",\n  \"iss\": \"token-issuer\",\n  \"exp\": 1626239022,\n  \"iat\": 1517239022\n}\n```\n"
    User-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Authorize the request with an user context. A payload example\nwould be:\n\n```\n{\n  \"sub\": \"usr:87127882-d1db-4e50-8f7c-c792a80d7c49\",\n  \"iss\": \"token-issuer\",\n  \"iat\": 1517239022,\n  \"exp\": 1626239022\n}\n```\n"