openapi: 3.1.0
info:
  title: Cargado API
  version: 1.0.0
  description: Cargado's API
  termsOfService: https://cargado.com/terms/
  contact:
    email: dev-support@cargado.com
servers:
  - url: https://api.cargado.com
    description: The production Cargado API server
tags:
  - name: Loads
  - name: Rates
  - name: CarrierRelationship
paths:
  /rates/history:
    post:
      operationId: RateHistory
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateHistoryOutput'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
              examples:
                Example 1:
                  value:
                    message: Unauthorized
      description: >-
        Look up the rate history for a lane. This is considered a mutation
        because it is a

        metered operation and calls are recorded for possible billing purposes.


        See [the usage guide](/rates/rate-lookup).
      summary: Lookup rate history
      tags:
        - Rates
      security:
        - apiKey: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RateHistoryInput'
  /rates/history/{rateHistoryLookupId}:
    get:
      operationId: GetRateHistoryLookup
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateHistoryLookup'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
              examples:
                Example 1:
                  value:
                    message: Unauthorized
      description: Fetch a previously-calculated rate history by its ID.
      summary: Get rate history lookup
      tags:
        - Rates
      security:
        - apiKey: []
      parameters:
        - in: path
          name: rateHistoryLookupId
          required: true
          schema:
            type: string
  /rates/history/export:
    get:
      operationId: GetMarketRateExportUrls
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketRateExportOutput'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
              examples:
                Example 1:
                  value:
                    message: Invalid request parameters
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
              examples:
                Example 1:
                  value:
                    message: Unauthorized
      description: >-
        Get signed URLs to download pre-generated CSV files containing market
        rate history data.

        Returns one URL per snapshot within the specified date range. If no date
        range is provided,

        the latest snapshot will be returned.


        Each CSV file contains rate data for all lanes. See the
        [MarketRateExport](../models/MarketRateExport) model for the schema of
        the CSV file.


        **Requires an Enterprise plan.**
      summary: Export market rate history
      tags:
        - Rates
      security:
        - apiKey: []
      parameters:
        - description: |-
            Start date for the export range, in ISO 8601 format (YYYY-MM-DD).
            If provided, `endDate` must also be provided.
          in: query
          name: startDate
          required: false
          schema:
            $ref: '#/components/schemas/Day'
        - description: |-
            End date for the export range, in ISO 8601 format (YYYY-MM-DD).
            If provided, `startDate` must also be provided.
          in: query
          name: endDate
          required: false
          schema:
            $ref: '#/components/schemas/Day'
  /loads/sync:
    post:
      operationId: SyncALoad
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadsSyncOutput'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                  - message
                type: object
              examples:
                Example 1:
                  value:
                    message: Unauthorized
      description: >-
        Sync a load from your TMS to Cargado, creating or updating any load
        details

        and status.
      summary: Sync a load
      tags:
        - Loads
      security:
        - apiKey: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoadsSyncInput'
  /carrier-relationships/upsert:
    post:
      operationId: UpsertACarrierRelationship
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierRelationshipUpsertOutput'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                required:
                  - message
                type: object
              examples:
                Example 1:
                  value:
                    message: Unauthorized
      description: >-
        Create or update carrier relationships and statuses from your TMS to
        Cargado.

        If a carrier is not found, the relationship will be null.

        Returns the relationships in the same order and length as the input.
      summary: Upsert carrier relationships
      tags:
        - CarrierRelationship
      security:
        - apiKey: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierRelationshipUpsertInput'
components:
  examples: {}
  headers: {}
  parameters: {}
  requestBodies: {}
  responses: {}
  schemas:
    Day:
      type: string
      format: date
      description: A date in ISO 8601 format (YYYY-MM-DD).
      examples:
        - 2025-01-01
    DayRange:
      description: Range between two dates.
      properties:
        start:
          $ref: '#/components/schemas/Day'
          description: Start date in ISO 8601 format.
        end:
          $ref: '#/components/schemas/Day'
          description: End date in ISO 8601 format.
      required:
        - start
        - end
      type: object
      additionalProperties: true
    CountryCode:
      type: string
      enum:
        - US
        - MX
        - CA
      description: The ISO 3166-1 alpha-2 country code of the place.
    Coordinates:
      description: GPS coordinates for a geographic location.
      properties:
        latitude:
          type: number
          format: double
          description: The latitude of the place.
          minimum: -90
          maximum: 90
          examples:
            - 49.280455
        longitude:
          type: number
          format: double
          description: The longitude of the place.
          minimum: -180
          maximum: 180
          examples:
            - -123.118842
      required:
        - latitude
        - longitude
      type: object
      additionalProperties: true
    Market:
      description: A geographic area that Cargado has chosen to aggregate prices.
      properties:
        id:
          type: string
        name:
          type: string
          description: The display name of the market
        code:
          type: string
          description: >-
            The two letter country code and three letter market code of the
            market (e.g. US_SEA, MX_MTY).

            Based on the UN/LOCODE list.
        countryCode:
          $ref: '#/components/schemas/CountryCode'
          description: The country code of the market
        centroid:
          $ref: '#/components/schemas/Coordinates'
          description: |-
            The coordinates of the major city defining the market.
            Deadhead is calculated to/from here.
      required:
        - id
        - name
        - code
        - countryCode
        - centroid
      type: object
      additionalProperties: true
    MarketPricingArea:
      description: A Pricing Area covering a single Market.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - MARKET
        market:
          $ref: '#/components/schemas/Market'
      required:
        - type
        - market
      type: object
      additionalProperties: true
    ExtendedMarket:
      description:
        A set of contiguous Markets that Cargado has chosen to aggregate
        prices over a larger area.
      properties:
        id:
          type: string
        markets:
          items:
            $ref: '#/components/schemas/Market'
          type: array
          description: The set of constituent Markets that make up this ExtendedMarket.
        primaryMarket:
          $ref: '#/components/schemas/Market'
          description:
            The "primary" Market among the set of Markets, used for naming
            purposes.
      required:
        - id
        - markets
        - primaryMarket
      type: object
      additionalProperties: true
    ExtendedMarketPricingArea:
      description:
        A Pricing Area covering a single Extended Market, which is composed
        of contiguous Markets.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - EXTENDED_MARKET
        extendedMarket:
          $ref: '#/components/schemas/ExtendedMarket'
      required:
        - type
        - extendedMarket
      type: object
      additionalProperties: true
    PricingArea:
      anyOf:
        - $ref: '#/components/schemas/MarketPricingArea'
        - $ref: '#/components/schemas/ExtendedMarketPricingArea'
      description: >-
        An area in which freight prices are aggregated for analysis at both
        origin and destination.

        Extended Market-based Pricing Areas are larger and are used when
        insufficient data is available at the Market level.
    TrailerCategory:
      type: string
      enum:
        - DRY_VAN
        - OPEN_DECK
        - REEFER
        - STRAIGHT_TRUCK
    UsMxBorderCrossing:
      type: string
      enum:
        - LAREDO_INTL_BRIDGE
        - LAREDO_COLUMBIA
        - BROWNSVILLE
        - CALEXICO_EAST
        - DEL_RIO
        - DOUGLAS
        - EAGLE_PASS
        - EL_PASO
        - HIDALGO
        - NOGALES
        - OTAY_MESA
        - SAN_LUIS
        - TECATE
    PricingLane:
      description: A description of the unique features used to aggregate prices internally.
      properties:
        origin:
          $ref: '#/components/schemas/PricingArea'
        destination:
          $ref: '#/components/schemas/PricingArea'
        trailerCategory:
          $ref: '#/components/schemas/TrailerCategory'
        usMxBorderCrossing:
          $ref: '#/components/schemas/UsMxBorderCrossing'
      required:
        - origin
        - destination
        - trailerCategory
      type: object
      additionalProperties: true
    CurrencyCode:
      type: string
      enum:
        - USD
        - MXN
        - CAD
      description: Supported currency codes for monetary values.
    Distribution:
      properties:
        p25:
          type: number
          format: double
          description: The 25th percentile of the distribution.
        p50:
          type: number
          format: double
          description: The 50th percentile of the distribution.
        p75:
          type: number
          format: double
          description: The 75th percentile of the distribution.
      required:
        - p25
        - p50
        - p75
      type: object
      additionalProperties: true
    Confidence:
      type: string
      enum:
        - STRONG
        - MEDIUM
        - LOWER
      description: Level of statistical confidence in a piece of data.
    RateHistoryTimeframe:
      description: The distribution of rates, including fuel, for a given timeframe.
      properties:
        dayRange:
          $ref: '#/components/schemas/DayRange'
          description: The date range that this data point covers.
        amountDistribution:
          $ref: '#/components/schemas/Distribution'
          description: >-
            The distribution in "amounts" (integers of the base unit of the
            chosen currency).


            - CAD: cents

            - USD: cents

            - MXN: centavos
        marginOfError:
          type: number
          format: double
          description: >-
            The margin of error is the maximum expected difference between the
            true population median and our observed median.

            It is calculated, per lane, based on the number of bids and their
            variability, from at least 5 unique carriers.


            Its unit is "amount" (integers of the base unit of the chosen
            currency); see the `amountDistribution` field.
        relativeMarginOfError:
          type: number
          format: double
          description:
            The margin of error divided by the rate p50 to yield a percentage
            rate deviation.
        confidenceScore:
          type: number
          format: double
          description: >-
            A score indicating overall confidence in the rates, derived from the
            relative margin of error. This is expressed as an

            integer between 1 and 100, where 1 is the lowest confidence and 100
            is the highest.
        confidence:
          $ref: '#/components/schemas/Confidence'
          description: |-
            The simplest confidence metric. Values:

            - `LOWER`: confidence score 1-33
            - `MEDIUM`: confidence score 34-66
            - `STRONG`: confidence score 67-100
      required:
        - dayRange
        - amountDistribution
      type: object
      additionalProperties: true
    RateHistory:
      description: The history of rates for a specific market to market lane.
      properties:
        dayRange:
          $ref: '#/components/schemas/DayRange'
          description: The date range that this Rate History covers.
        pricingLane:
          $ref: '#/components/schemas/PricingLane'
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        latestSuggestedRate:
          $ref: '#/components/schemas/RateHistoryTimeframe'
          description:
            'Most recent rate, calculated using the suggested formula: either
            per-mile (multiplied by distance) or all-in, depending on our
            analysis.'
        suggestedRates:
          items:
            $ref: '#/components/schemas/RateHistoryTimeframe'
          type: array
          description: History of suggested rates, in ascending order by date.
        latestPerMileRate:
          $ref: '#/components/schemas/RateHistoryTimeframe'
          description: Most recent rate, charged per mile.
        perMileRates:
          items:
            $ref: '#/components/schemas/RateHistoryTimeframe'
          type: array
          description: History of per-mile rates, in ascending order by date.
        latestAllInRate:
          $ref: '#/components/schemas/RateHistoryTimeframe'
          description:
            Most recent rate, calculated from all-in rates between the origin
            and destination pricing areas, ignoring route mileage.
        allInRates:
          items:
            $ref: '#/components/schemas/RateHistoryTimeframe'
          type: array
          description: History of all-in rates, in ascending order by date.
        routeMiles:
          type: number
          format: double
          description: >-
            Distance in miles between the specified pickup and delivery.


            If `routeMiles` was specified in the input, this field has the same
            value. Otherwise, we calculate it.
        routeMilesWithDeadhead:
          type: number
          format: double
          description: >-
            The route mileage, plus estimated deadhead from the origin Market
            centroid to the pickup, and from the delivery to the destination
            Market centroid.


            If `routeMiles` was specified in the input, this field has the same
            value. Otherwise, we calculate it.
      required:
        - dayRange
        - pricingLane
        - currencyCode
        - latestSuggestedRate
        - suggestedRates
        - perMileRates
        - latestAllInRate
        - allInRates
        - routeMiles
        - routeMilesWithDeadhead
      type: object
      additionalProperties: true
    RateHistoryLookup:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - DATA
        id:
          type: string
        rateHistory:
          $ref: '#/components/schemas/RateHistory'
          description: The Rate History suggested by Cargado.
        alternateRateHistories:
          items:
            $ref: '#/components/schemas/RateHistory'
          type: array
          description:
            Alternate Rate Histories also calculated by Cargado, using
            different methodology. May be empty.
      required:
        - type
        - id
        - rateHistory
        - alternateRateHistories
      type: object
      additionalProperties: true
    RateHistoryErrorCode:
      type: string
      enum:
        - USER_INPUT_ERROR
        - SERVER_ERROR
        - RATE_HISTORY_NOT_FOUND
        - GEOCODING_FAILED
        - CALCULATING_ROUTE_DISTANCE_FAILED
    RateHistoryError:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - ERROR
        code:
          $ref: '#/components/schemas/RateHistoryErrorCode'
        message:
          type: string
      required:
        - type
        - code
        - message
      type: object
      additionalProperties: true
    RateHistoryOutput:
      properties:
        results:
          items:
            anyOf:
              - $ref: '#/components/schemas/RateHistoryLookup'
              - $ref: '#/components/schemas/RateHistoryError'
          type: array
          description: >-
            The result for each input request; the request and result arrays are
            the same size and their elements map 1:1.

            Each result is either a successful lookup or an error; each request
            succeeds or fails independently.


            See [the Rate Lookup guide](/rates/rate-lookup) for more
            information.
      required:
        - results
      type: object
      additionalProperties: true
    ErrorResponseBody:
      properties:
        code:
          type: string
        name:
          type: string
        message:
          type: string
        userReadableMessage:
          type: string
        details: {}
        fingerprint:
          type: string
      type: object
      additionalProperties: true
    AddressString:
      properties:
        address:
          type: string
        type:
          type:
            - string
            - 'null'
          enum:
            - ADDRESS_STRING
      required:
        - address
        - type
      type: object
      description: The place as a formatted string. Should be at the level of an
        address, postal code, city, or neighborhood.
    StateCodeCA:
      type: string
      enum:
        - CA_AB
        - CA_BC
        - CA_MB
        - CA_NB
        - CA_NL
        - CA_NT
        - CA_NS
        - CA_NU
        - CA_ON
        - CA_PE
        - CA_QC
        - CA_SK
        - CA_YT
    StateCodeMX:
      type: string
      enum:
        - MX_AGU
        - MX_BCN
        - MX_BCS
        - MX_CAM
        - MX_CMX
        - MX_COA
        - MX_COL
        - MX_CHP
        - MX_CHH
        - MX_DUR
        - MX_GUA
        - MX_GRO
        - MX_HID
        - MX_JAL
        - MX_MEX
        - MX_MIC
        - MX_MOR
        - MX_NAY
        - MX_NLE
        - MX_OAX
        - MX_PUE
        - MX_QUE
        - MX_ROO
        - MX_SLP
        - MX_SIN
        - MX_SON
        - MX_TAB
        - MX_TAM
        - MX_TLA
        - MX_VER
        - MX_YUC
        - MX_ZAC
    StateCodeUS:
      type: string
      enum:
        - US_AK
        - US_AL
        - US_AZ
        - US_AR
        - US_CA
        - US_CO
        - US_CT
        - US_DE
        - US_FL
        - US_GA
        - US_HI
        - US_ID
        - US_IL
        - US_IN
        - US_IA
        - US_KS
        - US_KY
        - US_LA
        - US_ME
        - US_MD
        - US_MA
        - US_MI
        - US_MN
        - US_MS
        - US_MO
        - US_MT
        - US_NE
        - US_NV
        - US_NH
        - US_NJ
        - US_NM
        - US_NY
        - US_NC
        - US_ND
        - US_OH
        - US_OK
        - US_OR
        - US_PA
        - US_RI
        - US_SC
        - US_SD
        - US_TN
        - US_TX
        - US_UT
        - US_VT
        - US_VA
        - US_WA
        - US_WV
        - US_WI
        - US_WY
        - US_DC
        - US_AS
        - US_GU
        - US_MP
        - US_PR
        - US_UM
        - US_VI
    StateCode:
      anyOf:
        - $ref: '#/components/schemas/StateCodeCA'
        - $ref: '#/components/schemas/StateCodeMX'
        - $ref: '#/components/schemas/StateCodeUS'
    Address:
      properties:
        country:
          $ref: '#/components/schemas/CountryCode'
        state:
          $ref: '#/components/schemas/StateCode'
        city:
          type: string
        postalCode:
          type: string
        streetTwo:
          type: string
        street:
          type: string
        type:
          type:
            - string
            - 'null'
          enum:
            - ADDRESS
      required:
        - country
        - state
        - city
        - postalCode
        - street
        - type
      type: object
      description: The full address of the place as structured data.
    PostalCode:
      description:
        A postal code in country-specific format (called a ZIP code in the
        United States).
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - POSTAL_CODE
        postalCode:
          type: string
        country:
          $ref: '#/components/schemas/CountryCode'
      required:
        - type
        - postalCode
        - country
      type: object
      additionalProperties: true
    City:
      description:
        A city or neighborhood. You may use the name of the neighborhood as
        the value of the `city` field.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - CITY
        city:
          type: string
        state:
          $ref: '#/components/schemas/StateCode'
        country:
          $ref: '#/components/schemas/CountryCode'
      required:
        - type
        - city
        - state
        - country
      type: object
      additionalProperties: true
    Place:
      anyOf:
        - $ref: '#/components/schemas/AddressString'
        - $ref: '#/components/schemas/Address'
        - $ref: '#/components/schemas/PostalCode'
        - $ref: '#/components/schemas/City'
    PlaceDetailsInput:
      properties:
        place:
          $ref: '#/components/schemas/Place'
        coordinates:
          $ref: '#/components/schemas/Coordinates'
          description:
            The GPS coordinates of the location. If omitted, Cargado will
            determine the coordinates to use via geocoding.
      type: object
      additionalProperties: true
    PickupStopInput:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - PICKUP
        placeDetails:
          $ref: '#/components/schemas/PlaceDetailsInput'
          description: The location of the stop.
      required:
        - type
        - placeDetails
      type: object
      additionalProperties: true
    DeliveryStopInput:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - DELIVERY
        placeDetails:
          $ref: '#/components/schemas/PlaceDetailsInput'
          description: The location of the stop.
      required:
        - type
        - placeDetails
      type: object
      additionalProperties: true
    BorderCrossingStopInput:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - BORDER_CROSSING
        usMxBorderCrossing:
          $ref: '#/components/schemas/UsMxBorderCrossing'
          description: The border crossing port between the United States and Mexico.
      required:
        - type
        - usMxBorderCrossing
      type: object
      additionalProperties: true
    StopInput:
      anyOf:
        - $ref: '#/components/schemas/PickupStopInput'
        - $ref: '#/components/schemas/DeliveryStopInput'
        - $ref: '#/components/schemas/BorderCrossingStopInput'
    TrailerType:
      type: string
      enum:
        - DRY_VAN
        - DRY_VAN_DOUBLE
        - DRY_VAN_TRIPLE
        - DRY_VAN_MULTI_AXLE
        - REEFER
        - REEFER_DOUBLE
        - REEFER_MULTI_AXLE
        - HEATED
        - HEATED_MULTI_AXLE
        - FLATBED
        - FLATBED_DOUBLE
        - FLATBED_MULTI_AXLE
        - STEPDECK
        - DOUBLE_DROP
        - RGN
        - CONESTOGA
        - STEPDECK_CONESTOGA
        - DOUBLE_DROP_CONESTOGA
        - STRAIGHT_TRUCK_DRY
        - STRAIGHT_TRUCK_REEFER
        - TORTON
        - RABON
        - HALF_TON
        - ONE_TON
        - ONE_AND_HALF_TON
        - THREE_AND_HALF_TON
        - FOUR_AND_HALF_TON
    RateHistoryRequest:
      properties:
        stops:
          items:
            $ref: '#/components/schemas/StopInput'
          type: array
          description: >-
            The list of stops for the load. The first stop is the origin and the
            last stop is the destination.

            The first stop must be a pickup and the last must be a delivery.

            If the load crosses the United States-Mexico border, this must
            include a border crossing stop. Otherwise, it must not include a
            border crossing stop.
          minItems: 2
          maxItems: 64
        trailerRequirements:
          properties:
            allowedTypes:
              items:
                $ref: '#/components/schemas/TrailerType'
              type: array
              description: |-
                Which types of trailers are allowed for the load.
                Examples: ["DRY_VAN"], ["DRY_VAN", "REEFER"]
              examples:
                - - DRY_VAN
          required:
            - allowedTypes
          type: object
          description: The trailer requirements for the load.
        routeMiles:
          type: number
          format: double
      required:
        - stops
        - trailerRequirements
      type: object
      additionalProperties: true
    RateHistoryInput:
      description: See [the Rate Lookup guide](/rates/rate-lookup) for more information.
      properties:
        requests:
          items:
            $ref: '#/components/schemas/RateHistoryRequest'
          type: array
          description: A list of load descriptions to get rate history for.
          minItems: 1
          maxItems: 16
      required:
        - requests
      type: object
      additionalProperties: true
    MarketRateExportUrl:
      description:
        A signed URL link to a historical market rate export CSV file with
        metadata.
      properties:
        url:
          type: string
          description:
            Pre-signed URL to download the CSV file. This URL will expire at
            the time indicated by `expiresAt`.
        dayRange:
          $ref: '#/components/schemas/DayRange'
          description: The date range covered by this CSV file.
        expiresAt:
          type: string
          description: ISO 8601 timestamp indicating when this URL will expire.
          examples:
            - 2026-01-08T12:00:00Z
      required:
        - url
        - dayRange
        - expiresAt
      type: object
      additionalProperties: true
    MarketRateExportOutput:
      description:
        Response containing signed URLs to pre-generated CSV files with
        market rate history data.
      properties:
        urls:
          items:
            $ref: '#/components/schemas/MarketRateExportUrl'
          type: array
          description: >-
            List of signed URLs to CSV files, one per historical snapshot within
            the requested date range.

            At most 20 URLs will be returned, starting from the most recent
            snapshot.
      required:
        - urls
      type: object
      additionalProperties: true
    MarketType:
      type: string
      enum:
        - MARKET
        - EXTENDED_MARKET
      description: Market type classification for pricing markets.
    MarketRateExport:
      description: >-
        A single market rate export record representing pricing data for a lane
        during a specific time period.

        MarketRateExports are unique in a snapshot by origin market, destination
        market, trailer category, and is_suggested_border_port=true.
      properties:
        pricing_lane_id:
          type: string
          description: Pricing lane identifier.
          format: uuid
        start_date:
          type: string
          description: Beginning date of the time period.
          format: date
          examples:
            - 2026-01-07
        end_date:
          type: string
          description: Ending date of the time period.
          format: date
          examples:
            - 2026-01-13
        p25_amount:
          type: integer
          format: int32
          description: 25th percentile price in USD.
        p50_amount:
          type: integer
          format: int32
          description: p50 (median) price in USD.
        p75_amount:
          type: integer
          format: int32
          description: 75th percentile price in USD.
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
          description: Currency for all price values (always USD).
        p25_cost_per_mile:
          type:
            - integer
            - 'null'
          format: int32
          description: 25th percentile cost per mile.
        p50_cost_per_mile:
          type:
            - integer
            - 'null'
          format: int32
          description: Median cost per mile.
        p75_cost_per_mile:
          type:
            - integer
            - 'null'
          format: int32
          description: 75th percentile cost per mile.
        p50_moe:
          type:
            - number
            - 'null'
          format: double
          description: 95% margin of error for median.
        p50_rme:
          type:
            - number
            - 'null'
          format: double
          description: Relative margin of error for median.
        p50_conf_score:
          type:
            - number
            - 'null'
          format: double
          description: Confidence score 0-100 based on margin of error.
        orig_market_id:
          type: string
          description: UUID of the origin Market.
          format: uuid
        orig_market_code:
          type: string
          description: Unique code for the origin Market.
        orig_market_type:
          $ref: '#/components/schemas/MarketType'
          description: Type of origin market.
        orig_market_name:
          type: string
          description:
            Name of the origin market (e.g. "Los Angeles, CA"; "Vancouver, BC";
            "Monterrey, NLE").
        orig_market_country_code:
          $ref: '#/components/schemas/CountryCode'
          description: Country code of the origin market.
        border_port:
          allOf:
            - $ref: '#/components/schemas/UsMxBorderCrossing'
          nullable: true
          description: Border crossing port name, or null for non-cross-border lanes.
        is_suggested_border_port:
          type:
            - boolean
            - 'null'
          description: |-
            Whether the border port is the suggested one for the lane.
            This is only set for cross-border lanes.
        dest_market_id:
          type: string
          description: UUID of the destination Market.
          format: uuid
        dest_market_code:
          type: string
          description: Unique code for the destination Market.
        dest_market_type:
          $ref: '#/components/schemas/MarketType'
          description: Type of destination market.
        dest_market_name:
          type: string
          description:
            Name of the destination market (e.g. "Los Angeles, CA"; "Vancouver,
            BC"; "Monterrey, NLE").
        dest_market_country_code:
          $ref: '#/components/schemas/CountryCode'
          description: Country code of the destination market.
        trailer_category:
          $ref: '#/components/schemas/TrailerCategory'
          description: Category of trailer required for the lane.
      required:
        - pricing_lane_id
        - start_date
        - end_date
        - p25_amount
        - p50_amount
        - p75_amount
        - currency_code
        - p25_cost_per_mile
        - p50_cost_per_mile
        - p75_cost_per_mile
        - p50_moe
        - p50_rme
        - p50_conf_score
        - orig_market_id
        - orig_market_code
        - orig_market_type
        - orig_market_name
        - orig_market_country_code
        - border_port
        - is_suggested_border_port
        - dest_market_id
        - dest_market_code
        - dest_market_type
        - dest_market_name
        - dest_market_country_code
        - trailer_category
      type: object
      additionalProperties: true
    StopLocationAddress:
      description: A structured address with individual components.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - ADDRESS
          description: The type of place
        street:
          type: string
          description: The street address of the place.
          minLength: 0
          maxLength: 255
          examples:
            - 123 Main St
        neighborhood:
          type: string
          description: The neighborhood of the place.
          minLength: 0
          maxLength: 255
          examples:
            - Valle Oriente
        city:
          type: string
          description: |-
            The city of the place.
            Examples: "Chicago", "Monterrey", "Seattle"
          minLength: 0
          maxLength: 255
          examples:
            - Chicago
        state:
          type: string
          description: |-
            The state or province of the place.
            Examples: "IL", "NLE", "Nuevo León"
          minLength: 0
          maxLength: 255
          examples:
            - IL
        countryCode:
          $ref: '#/components/schemas/CountryCode'
          description: The ISO 3166-1 alpha-2 country code of the place.
        postalCode:
          type: string
          description: |-
            The postal code of the place.
            Examples: "98335", "64000", "V6B 4N7"
          examples:
            - '98335'
      required:
        - type
        - street
        - city
        - state
        - countryCode
        - postalCode
      type: object
      additionalProperties: true
    StopLocationFullAddress:
      description: A complete address provided as a single string.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - FULL_ADDRESS
          description: The type of place
        fullAddress:
          type: string
          description: The full address of the place.
          examples:
            - 123 Main St, Chicago, IL 60601
      required:
        - type
        - fullAddress
      type: object
      additionalProperties: true
    CarrierPreapproval:
      type: string
      enum:
        - FIXED_LIST
        - PRE_APPROVED
        - NOT_REQUIRED
    StopLocation:
      description: Location information for a stop.
      properties:
        coordinates:
          $ref: '#/components/schemas/Coordinates'
          description: The GPS coordinates of the place.
        isCtpatCertified:
          type: boolean
          description: Whether the place is CTPAT certified.
        isPipCertified:
          type: boolean
          description: Whether the place is PIP certified.
        isOeaCertified:
          type: boolean
          description: Whether the place is OEA Certified.
        carrierPreapproval:
          $ref: '#/components/schemas/CarrierPreapproval'
          description: |-
            Whether the place requires a pre-approved carrier.
             - `FIXED_LIST`: The carrier must be from a fixed set.
             - `PRE_APPROVED`: The carrier can be pre-approved.
             - `NOT_REQUIRED`: No pre-approval is required.
        timezone:
          type: string
          description: >-
            The timezone of the place (from the IANA timezone database).

            Examples: "America/Chicago", "America/Monterrey",
            "America/Los_Angeles"
          examples:
            - America/Chicago
        place:
          anyOf:
            - $ref: '#/components/schemas/StopLocationAddress'
            - $ref: '#/components/schemas/StopLocationFullAddress'
          description: The address or other type of place.
      required:
        - place
      type: object
      additionalProperties: true
    UnspecifiedAppointment:
      description: The appointment is unspecified or unknown.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - UNSPECIFIED
          description: The appointment is unspecified or unknown.
      required:
        - type
      type: object
      additionalProperties: true
    ToBeSetBySpecificTime:
      description: The appointment will be set by a specific time.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - SPECIFIC_TIME
          description: The appointment will be set by a specific time.
        time:
          type: string
          format: date-time
          description: The specific time the appointment will be set by.
      required:
        - type
        - time
      type: object
      additionalProperties: true
    ToBeSetByRelativeToEvent:
      description: The appointment will be set relative to an event.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - RELATIVE_TO_EVENT
          description: The appointment will be set relative to an event.
        event:
          type: string
          enum:
            - BORDER_CROSSING
            - DISPATCH
          description: >-
            The event the appointment will be set relative to.




             - `BORDER_CROSSING`: The appointment will be set after the border crossing.
             - `DISPATCH`: The appointment will be set after the carrier is dispatched.
      required:
        - type
        - event
      type: object
      additionalProperties: true
    AppointmentToBeSet:
      description: An appointment that has not been set yet.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - TO_BE_SET
          description: An appointment that has not been set yet.
        possibleAppointmentRange:
          properties:
            end:
              type: string
              format: date-time
            start:
              type: string
              format: date-time
          required:
            - end
            - start
          type: object
          description: The range of possible appointment times.
        toBeSetBy:
          anyOf:
            - $ref: '#/components/schemas/ToBeSetBySpecificTime'
            - $ref: '#/components/schemas/ToBeSetByRelativeToEvent'
          description: When the appointment will be set by.
      required:
        - type
        - toBeSetBy
      type: object
      additionalProperties: true
    SetAppointmentWindow:
      description: A set appointment, window of time.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - SET_APPOINTMENT_WINDOW
          description: A set appointment, window of time.
        windowStartTime:
          type: string
          format: date-time
          description: The start time of the window.
        windowEndTime:
          type: string
          format: date-time
          description: The end time of the window.
      required:
        - type
        - windowStartTime
        - windowEndTime
      type: object
      additionalProperties: true
    SetAppointmentExact:
      description: The appointment is an exact time.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - SET_APPOINTMENT_EXACT
          description: The appointment is an exact time.
        time:
          type: string
          format: date-time
          description: The exact time of the appointment.
      required:
        - type
        - time
      type: object
      additionalProperties: true
    FirstComeFirstServeAppointment:
      description: The appointment is first come first serve.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - FIRST_COME_FIRST_SERVE
          description: The appointment is first come first serve.
      required:
        - type
      type: object
      additionalProperties: true
    LoadingMethod:
      type: string
      enum:
        - LIVE
        - DROP
      description: Method of loading/unloading cargo at a stop.
    InboundTransitRequirements:
      description: Requirements for inbound transit to a stop.
      properties:
        maximumExpectedMinutes:
          type:
            - integer
            - 'null'
          format: int32
          description:
            The maximum time in minutes that the driver is expected to be at
            the stop by.
        securityEscortProvider:
          type:
            - string
            - 'null'
          enum:
            - PROVIDER
            - OWNER
            - null
          description:
            Whether a security escort will be provided by the owner of the load
            or by a transportation provider.
        teamDriverRequired:
          type:
            - boolean
            - 'null'
          description:
            Whether a team driver is required for the transit inbound to this
            stop.
        trackingRequired:
          type:
            - boolean
            - 'null'
          description: Whether tracking is required for the transit inbound to this stop.
      type: object
      additionalProperties: true
    StopRequirement:
      description: A requirement that can apply before and/or after a stop.
      properties:
        requiredBefore:
          type: boolean
          description: Whether the requirement applies before the stop.
        requiredAfter:
          type: boolean
          description: Whether the requirement applies after the stop.
      required:
        - requiredBefore
        - requiredAfter
      type: object
      additionalProperties: true
    ReferenceNumber:
      description: A reference number associated with a load or shipment.
      properties:
        label:
          type: string
          description: |-
            The type of reference number.
            Examples: "Shipment #", "BOL #", "PO #", "PRO #"
          minLength: 1
          examples:
            - 'Shipment #'
        value:
          type: string
          description: The value of the reference number.
          minLength: 1
          examples:
            - '1234234'
      required:
        - label
        - value
      type: object
      additionalProperties: true
    PickupStop:
      description: A pickup stop where goods are loaded.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - PICKUP
          description:
            Whether the stop is a pickup or delivery of goods or a border
            crossing.
        externalId:
          type: string
          description:
            The unique ID for the stop in your TMS. This identifier will not be
            displayed outside your organization.
          minLength: 1
          maxLength: 255
          examples:
            - 27924_1
        referenceNumbers:
          items:
            $ref: '#/components/schemas/ReferenceNumber'
          type:
            - array
            - 'null'
        loadingMethod:
          allOf:
            - $ref: '#/components/schemas/LoadingMethod'
          nullable: true
          description:
            Whether the pickup or delivery is live (the truck driver waits
            while the cargo is loaded onto or unloaded from the trailer) or drop
            (the driver picks up a, often preloaded, trailer at the facility or
            drops off a trailer at the facility)
        inboundTransitRequirements:
          $ref: '#/components/schemas/InboundTransitRequirements'
          description:
            Any requirements on how the transit inbound to this stop is
            conducted.
        dropDurationHours:
          type:
            - number
            - 'null'
          format: double
          description: >-
            When the loadingMethod is DROP, this represents the number of hours
            after a trailer is delivered at pickup before the driver should
            arrive to pickup the then loaded trailer.


            Examples: 24, 8
          minimum: 0
          maximum: 2160
          examples:
            - 24
        fumigation:
          allOf:
            - $ref: '#/components/schemas/StopRequirement'
          nullable: true
          description: Whether fumigation is required for the stop.
        scaleTicket:
          allOf:
            - $ref: '#/components/schemas/StopRequirement'
          nullable: true
          description: Whether a scale ticket is required for the stop.
        driverAssistRequired:
          type:
            - boolean
            - 'null'
          description: Whether driver assisted loading is required for the stop.
        location:
          $ref: '#/components/schemas/StopLocation'
          description: The location of the stop.
        appointment:
          anyOf:
            - $ref: '#/components/schemas/UnspecifiedAppointment'
            - $ref: '#/components/schemas/AppointmentToBeSet'
            - $ref: '#/components/schemas/SetAppointmentWindow'
            - $ref: '#/components/schemas/SetAppointmentExact'
            - $ref: '#/components/schemas/FirstComeFirstServeAppointment'
      required:
        - type
        - externalId
        - location
        - appointment
      type: object
      additionalProperties: true
    DeliveryStop:
      description: A delivery stop where goods are unloaded.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - DELIVERY
          description:
            Whether the stop is a pickup or delivery of goods or a border
            crossing.
        externalId:
          type: string
          description:
            The unique ID for the stop in your TMS. This identifier will not be
            displayed outside your organization.
          minLength: 1
          maxLength: 255
          examples:
            - 27924_1
        referenceNumbers:
          items:
            $ref: '#/components/schemas/ReferenceNumber'
          type:
            - array
            - 'null'
        loadingMethod:
          allOf:
            - $ref: '#/components/schemas/LoadingMethod'
          nullable: true
          description:
            Whether the pickup or delivery is live (the truck driver waits
            while the cargo is loaded onto or unloaded from the trailer) or drop
            (the driver picks up a, often preloaded, trailer at the facility or
            drops off a trailer at the facility)
        inboundTransitRequirements:
          $ref: '#/components/schemas/InboundTransitRequirements'
          description:
            Any requirements on how the transit inbound to this stop is
            conducted.
        dropDurationHours:
          type:
            - number
            - 'null'
          format: double
          description: >-
            When the loadingMethod is DROP, this represents the number of hours
            after a trailer is delivered at pickup before the driver should
            arrive to pickup the then loaded trailer.


            Examples: 24, 8
          minimum: 0
          maximum: 2160
          examples:
            - 24
        fumigation:
          allOf:
            - $ref: '#/components/schemas/StopRequirement'
          nullable: true
          description: Whether fumigation is required for the stop.
        scaleTicket:
          allOf:
            - $ref: '#/components/schemas/StopRequirement'
          nullable: true
          description: Whether a scale ticket is required for the stop.
        driverAssistRequired:
          type:
            - boolean
            - 'null'
          description: Whether driver assisted loading is required for the stop.
        location:
          $ref: '#/components/schemas/StopLocation'
          description: The location of the stop.
        appointment:
          anyOf:
            - $ref: '#/components/schemas/UnspecifiedAppointment'
            - $ref: '#/components/schemas/AppointmentToBeSet'
            - $ref: '#/components/schemas/SetAppointmentWindow'
            - $ref: '#/components/schemas/SetAppointmentExact'
            - $ref: '#/components/schemas/FirstComeFirstServeAppointment'
      required:
        - type
        - externalId
        - location
        - appointment
      type: object
      additionalProperties: true
    BorderCrossingStrategy:
      type: string
      enum:
        - PRE_ASSIGNED
        - PROVIDER
    BorderCrossingRequiredInspection:
      type: string
      enum:
        - USDA
        - FDA
        - FISH_AND_WILDLIFE
        - CERTIFICADO_ORIGEN_TEQUILA
        - CBP_AGRICULTURE
        - PROFEPA
        - SAGARPA
        - SENASICA
        - CPSC
        - EPA
        - SADER
    BorderCrossingStop:
      description: A border crossing stop for international shipments.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - BORDER_CROSSING
          description:
            Whether the stop is a pickup or delivery of goods or a border
            crossing.
        externalId:
          type: string
          description:
            The unique ID for the stop in your TMS. This identifier will not be
            displayed outside your organization.
          minLength: 1
          maxLength: 255
          examples:
            - 27924_1
        referenceNumbers:
          items:
            $ref: '#/components/schemas/ReferenceNumber'
          type:
            - array
            - 'null'
        usMxBorderCrossing:
          allOf:
            - $ref: '#/components/schemas/UsMxBorderCrossing'
          nullable: true
          description: The border crossing port between the United States and Mexico.
        borderCrossingStrategy:
          allOf:
            - $ref: '#/components/schemas/BorderCrossingStrategy'
          nullable: true
          description: |-
            The strategy used to cross the US border.
            Examples: 'PRE_ASSIGNED', 'PROVIDER'
        requiredInspections:
          items:
            $ref: '#/components/schemas/BorderCrossingRequiredInspection'
          type:
            - array
            - 'null'
          description: |-
            Inspections required to cross the US border.
            Examples: 'USDA', 'PROFEPA'
        expectedDwellTimeMinutes:
          type:
            - number
            - 'null'
          format: double
          description:
            The expected duration, in minutes, that a shipment or cargo will
            spend at a specific location or during a particular stage of the
            logistics process.
          examples:
            - 12
      required:
        - type
        - externalId
      type: object
      additionalProperties: true
    LoadStatus:
      type: string
      enum:
        - ON_HOLD
        - AVAILABLE
        - BOOKED
        - CANCELLED
        - COMPLETED
      description: |-
        The status of the load. The status can be one of the following:
         - `ON_HOLD`: The load is on hold and not available for booking.
         - `AVAILABLE`: The load is available for booking.
         - `BOOKED`: The load is booked with a carrier.
         - `CANCELLED`: The load has been cancelled.
         - `COMPLETED`: The load has been completed.
    LoadCommodityDimensionUnit:
      type: string
      enum:
        - FEET
        - CENTIMETERS
        - INCHES
        - METERS
    Dimension:
      properties:
        value:
          type: number
          format: double
        unit:
          $ref: '#/components/schemas/LoadCommodityDimensionUnit'
      required:
        - value
        - unit
      type: object
      additionalProperties: true
    Dimensions:
      description: The dimensions of a commodity.
      properties:
        length:
          $ref: '#/components/schemas/Dimension'
          description: The length of the commodity.
          examples:
            - value: 576
              unit: INCHES
        width:
          $ref: '#/components/schemas/Dimension'
          description: The width of the commodity.
          examples:
            - value: 120
              unit: INCHES
        height:
          $ref: '#/components/schemas/Dimension'
          description: The height of the commodity.
          examples:
            - value: 72
              unit: INCHES
      required:
        - length
        - width
        - height
      type: object
      additionalProperties: true
    WeightUnit:
      type: string
      enum:
        - POUNDS
        - KILOGRAMS
        - TONNES
    ApproximateWeight:
      description: The approximate weight of a commodity.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - APPROXIMATE
          description: The weight is a single value.
        value:
          type: number
          format: double
          description: The value of the weight.
        unit:
          $ref: '#/components/schemas/WeightUnit'
      required:
        - type
        - value
        - unit
      type: object
      additionalProperties: true
    WeightRange:
      description: The weight range of a commodity.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - RANGE
          description: The weight is a range.
        minimum:
          type: number
          format: double
          description: The minimum weight of the range.
        maximum:
          type: number
          format: double
          description: The maximum weight of the range.
        unit:
          $ref: '#/components/schemas/WeightUnit'
      required:
        - type
        - minimum
        - maximum
        - unit
      type: object
      additionalProperties: true
    TemperatureUnit:
      type: string
      enum:
        - FAHRENHEIT
        - CELSIUS
    TemperatureControlCycle:
      type: string
      enum:
        - CONTINUOUS
        - CYCLIC
    TemperatureRequirements:
      description: The temperature requirements for a commodity.
      properties:
        minimum:
          type: number
          format: double
          description: The minimum temperature.
        maximum:
          type: number
          format: double
          description: The maximum temperature.
        unit:
          $ref: '#/components/schemas/TemperatureUnit'
          description: The unit of the temperature.
        controlCycle:
          $ref: '#/components/schemas/TemperatureControlCycle'
          description: The control cycle of the temperature.
      required:
        - minimum
        - maximum
        - unit
      type: object
      additionalProperties: true
    HazmatClassification:
      type: string
      enum:
        - CLASS_1_EXPLOSIVES
        - CLASS_2_GASES
        - CLASS_3_FLAMMABLE_LIQUIDS
        - CLASS_4_FLAMMABLE_SOLIDS
        - CLASS_5_OXIDIZING_SUBSTANCES
        - CLASS_6_TOXIC_AND_INFECTIOUS_SUBSTANCES
        - CLASS_7_RADIOACTIVE_MATERIAL
        - CLASS_8_CORROSIVES
        - CLASS_9_MISCELLANEOUS
    HazmatPackingGroup:
      type: string
      enum:
        - I
        - II
        - III
    IsHazmat:
      description:
        This represents a hazmat commodity with its classification, UN
        number, and packing group.
      properties:
        isHazmat:
          type:
            - boolean
            - 'null'
          enum:
            - true
          description: This is a hazmat commodity.
        classification:
          allOf:
            - $ref: '#/components/schemas/HazmatClassification'
          nullable: true
          description: The hazmat classification of the commodity.
        unNumber:
          type:
            - string
            - 'null'
          description: The UN number of the commodity.
        packingGroup:
          allOf:
            - $ref: '#/components/schemas/HazmatPackingGroup'
          nullable: true
          description: The packing group of the commodity.
      required:
        - isHazmat
      type: object
      additionalProperties: true
    IsNotHazmat:
      description: This represents a commodity that is not hazmat.
      properties:
        isHazmat:
          type:
            - boolean
            - 'null'
          enum:
            - false
          description: This is not a hazmat commodity.
        classification:
          type:
            - number
            - 'null'
          enum:
            - null
          description: The hazmat classification of the commodity.
        unNumber:
          type:
            - number
            - 'null'
          enum:
            - null
          description: The UN number of the commodity.
        packingGroup:
          type:
            - number
            - 'null'
          enum:
            - null
          description: The packing group of the commodity.
      required:
        - isHazmat
      type: object
      additionalProperties: true
    CommodityPieceType:
      type: string
      enum:
        - PALLET
        - CRATE
        - SUPER_SACK
        - DRUM
        - ROLL
        - REEL
        - GAYLORD
        - TOTES
        - OTHER
      description: Types of commodity pieces for packaging.
    VolumeUnit:
      type: string
      enum:
        - GALLONS
        - LITERS
    Volume:
      properties:
        value:
          type: number
          format: double
        unit:
          $ref: '#/components/schemas/VolumeUnit'
      required:
        - value
        - unit
      type: object
      additionalProperties: true
    LoadCommodity:
      description: A commodity being transported in a load.
      properties:
        name:
          type: string
          description: The name of the commodity.
          examples:
            - Crude Oil
        dimensions:
          allOf:
            - $ref: '#/components/schemas/Dimensions'
          nullable: true
          description: The dimensions of the commodity.
        weight:
          anyOf:
            - $ref: '#/components/schemas/ApproximateWeight'
            - $ref: '#/components/schemas/WeightRange'
          nullable: true
          description: >-
            The weight of the commodity. The weight can be approximate or a
            range.

            Use approximate when you have a single weight value.
        temperatureRequirements:
          allOf:
            - $ref: '#/components/schemas/TemperatureRequirements'
          nullable: true
          description: The temperature requirements for the commodity.
          examples:
            - minimum: 10
              maximum: 20
              unit: CELSIUS
        hazmatDetails:
          anyOf:
            - $ref: '#/components/schemas/IsHazmat'
            - $ref: '#/components/schemas/IsNotHazmat'
          description: The hazmat details of the commodity.
          examples:
            - isHazmat: true
              classification: CLASS_3_FLAMMABLE_LIQUIDS
              unNumber: '1263'
              packingGroup: II
        pieces:
          properties:
            stackable:
              type:
                - boolean
                - 'null'
              description: Whether the commodity piece is stackable.
            perPieceVolume:
              allOf:
                - $ref: '#/components/schemas/Volume'
              nullable: true
              description: |-
                The volume of a single piece of the commodity.
                Useful for describing Commodity Piece Type "DRUM".
                Examples: 55 gallon drum or 30 gallon drum
              examples:
                - value: 100
                  unit: GALLONS
            perPieceDimensions:
              allOf:
                - $ref: '#/components/schemas/Dimensions'
              nullable: true
              description: The dimensions of each piece of the commodity.
            type:
              $ref: '#/components/schemas/CommodityPieceType'
              description: The type of piece for commodity packaging.
              examples:
                - PALLET
            count:
              type:
                - number
                - 'null'
              format: double
              description: The number of pieces of this commodity type.
              examples:
                - 10
          required:
            - type
          type:
            - object
            - 'null'
          description:
            Piece information for the commodity, including type, count and
            dimensions.
      required:
        - name
        - hazmatDetails
      type: object
      additionalProperties: true
    TrailerRequirementsAllowedTypes:
      type: string
      enum:
        - REEFER
        - DRY_VAN_DOUBLE
        - DRY_VAN_TRIPLE
        - DRY_VAN_MULTI_AXLE
        - REEFER_DOUBLE
        - REEFER_MULTI_AXLE
        - HEATED
        - HEATED_MULTI_AXLE
        - FLATBED_DOUBLE
        - FLATBED_MULTI_AXLE
        - STEPDECK
        - DOUBLE_DROP
        - RGN
        - CONESTOGA
        - STEPDECK_CONESTOGA
        - DOUBLE_DROP_CONESTOGA
        - STRAIGHT_TRUCK_DRY
        - STRAIGHT_TRUCK_REEFER
        - TORTON
        - RABON
        - HALF_TON
        - ONE_TON
        - ONE_AND_HALF_TON
        - THREE_AND_HALF_TON
        - FOUR_AND_HALF_TON
        - DRY_VAN_48
        - DRY_VAN_53
        - FLATBED_48
        - FLATBED_53
      description: Types of trailers that can be used for transportation.
    PowerOnlyType:
      type: string
      enum:
        - PRE_LOADED
        - LOAD_OUT
        - TOW_AWAY
      description: Types of power-only moves.
    TrailerRequirementsDoorType:
      type: string
      enum:
        - SWING
        - ROLL_UP
      description: Types of trailer doors.
    TrailerRequirementsSuspensionType:
      type: string
      enum:
        - AIR_RIDE
        - SPRING
      description: Types of trailer suspension systems.
    TrailerRequirementsWallType:
      type: string
      enum:
        - SHEET_AND_POST
        - PLATED
      description: Types of trailer wall construction.
    TrailerRequirementsETrackRails:
      type: string
      enum:
        - VERTICAL
        - HORIZONTAL
      description: Types of E-track rail configurations for cargo securement.
    ETrackRailDistance:
      type: string
      enum:
        - TWO_FEET
        - FOUR_FEET
      description: Distance between E-track rails.
    TrailerFloorType:
      type: string
      enum:
        - HARDWOOD
        - ALUMINUM
        - STEEL
        - COMPOSITE
      description: Types of trailer floor types.
    TrailerRequirements:
      description: Requirements and specifications for trailers used in transportation.
      properties:
        allowedTypes:
          items:
            $ref: '#/components/schemas/TrailerRequirementsAllowedTypes'
          type: array
          description: |-
            Which types of trailers are allowed for the load.
            Examples: ["DRY_VAN_53"], ["DRY_VAN_53", "REEFER"]
          examples:
            - - DRY_VAN_53
        powerOnlyType:
          allOf:
            - $ref: '#/components/schemas/PowerOnlyType'
          nullable: true
          description: >-
            The type of power-only move, if the freight is power only.

            If null, this is not a power-only load.

            Examples: "PRE_LOADED", "LOAD_OUT", "TOW_AWAY"


            PRE_LOADED: The trailer is pre-loaded with the cargo.

            LOAD_OUT: The empty trailer can be used for a different load on the
            way to the destination.

            TOW_AWAY: The empty trailer must go straight to the destination
        doorType:
          allOf:
            - $ref: '#/components/schemas/TrailerRequirementsDoorType'
          nullable: true
          description: The type of trailer door required.
        maxAgeYears:
          type:
            - number
            - 'null'
          format: double
          description: The maximum age of the trailer in years.
        highCube:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must be high cube.
        spaceSaver:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must be a space saver.
        suspensionType:
          allOf:
            - $ref: '#/components/schemas/TrailerRequirementsSuspensionType'
          nullable: true
          description: The required suspension type of the trailer.
        foodGrade:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must be food grade.
        wallType:
          allOf:
            - $ref: '#/components/schemas/TrailerRequirementsWallType'
          nullable: true
          description: The type of trailer wall.
        logisticPost:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must be logistic post.
        eTrackRails:
          allOf:
            - $ref: '#/components/schemas/TrailerRequirementsETrackRails'
          nullable: true
          description: The type of etrack rails required.
        eTracksDistance:
          allOf:
            - $ref: '#/components/schemas/ETrackRailDistance'
          nullable: true
          description: The distance between E-tracks on the trailer floor.
        extendable:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must be extendable.
        liftGate:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must have a lift gate.
        minAxles:
          type:
            - number
            - 'null'
          format: double
          description: The minimum number of axles required.
        metalEdgeProtectors:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must have metal edge protectors.
        airChute:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must have an air chute.
        ctpatCompliant:
          type:
            - boolean
            - 'null'
          description: Whether the trailer must be CTPAT compliant.
        floorTypes:
          items:
            $ref: '#/components/schemas/TrailerFloorType'
          type:
            - array
            - 'null'
          description: The allowed floor types for the trailer.
      required:
        - allowedTypes
      type: object
      additionalProperties: true
    RequiredEquipmentType:
      type: string
      enum:
        - LOAD_BARS
        - LOAD_LOCK_BAR
        - JACK_LOAD_BAR
        - E_TRACK_SHORING_BEAM
        - STRAP
        - CTPAT_SEAL
        - MASK_AND_GLOVES
        - PERSONAL_PROTECTIVE_EQUIPMENT
        - BLOCKING_AND_BRACING
        - TARP_FOUR_FOOT
        - TARP_SIX_FOOT
        - TARP_EIGHT_FOOT
        - TARP_OVERSIZE
        - CHAINS
        - PIPE_STAKE_FOUR_FOOT
        - PIPE_STAKE_EIGHT_FOOT
        - HEAT_TREATED_DUNNAGE
        - COIL_RACKS
        - HEADACHE_RACK
        - HEADBOARD
        - EDGE_PROTECTORS
        - RAMPS
        - PILOT_CARS
        - RUBBER_MATS
      description: Types of equipment that can be required for a load.
    RequiredEquipment:
      description: Equipment that is required for a load.
      properties:
        type:
          $ref: '#/components/schemas/RequiredEquipmentType'
          description: The type of equipment required.
        quantity:
          type: number
          format: double
          description: The quantity of the equipment required.
          minimum: 1
          maximum: 1000
      required:
        - type
      type: object
      additionalProperties: true
    CurrencyValue:
      description: >-
        An object representing a monetary value in a given currency. Amount

        is in the lowest denomination of the currency (e.g. cents).

        For example, $15.25 is represented as `{ currencyCode: 'USD', amount:
        1525 }`.
      properties:
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
          description: The currency code of the amount
        amount:
          type: integer
          format: int32
          description:
            The currency amount in the lowest denomination of the currency
            (e.g. cents)
          minimum: 0
          maximum: 1000000000
      required:
        - currencyCode
        - amount
      type: object
      additionalProperties: true
    CarrierRequirements:
      description: Requirements and certifications for carriers.
      properties:
        ctpatCertified:
          type:
            - boolean
            - 'null'
          description: Whether the carrier must be CTPAT certified.
        oeaCertified:
          type:
            - boolean
            - 'null'
          description: Whether the carrier must be OEA certified.
        pipCertified:
          type:
            - boolean
            - 'null'
          description: Whether the carrier must be PIP certified.
        fastCertified:
          type:
            - boolean
            - 'null'
          description: Whether the carrier must be FAST certified.
        internationalCarrierBonded:
          type:
            - boolean
            - 'null'
          description: Whether the carrier must be bonded for international shipments.
          deprecated: true
        internationalCarrierBondedUS:
          type:
            - boolean
            - 'null'
          description:
            Whether the carrier must be bonded for international shipments in
            the US.
        internationalCarrierBondedCA:
          type:
            - boolean
            - 'null'
          description:
            Whether the carrier must be bonded for international shipments in
            Canada.
        internationalCarrierBondedMX:
          type:
            - boolean
            - 'null'
          description:
            Whether the carrier must be bonded for international shipments in
            Mexico.
        has247CustomerService:
          type:
            - boolean
            - 'null'
          description: Whether the carrier must have 24/7 customer service.
        minCargoInsurance:
          allOf:
            - $ref: '#/components/schemas/CurrencyValue'
          nullable: true
          description:
            The minimum cargo insurance required for the carrier to have in the
            US and/or Canada.
        minLiabilityInsurance:
          allOf:
            - $ref: '#/components/schemas/CurrencyValue'
          nullable: true
          description: The minimum liability insurance required for the carrier to have.
        minAutoInsurance:
          allOf:
            - $ref: '#/components/schemas/CurrencyValue'
          nullable: true
          description: The minimum auto insurance required for the carrier to have.
      type: object
      additionalProperties: true
    DriverRequirements:
      description: Requirements and certifications for drivers.
      properties:
        twicCard:
          type:
            - boolean
            - 'null'
          description: Whether the driver must have a TWIC card.
        tankerEndorsed:
          type:
            - boolean
            - 'null'
          description: Whether the driver must have a tanker endorsement.
        cdl:
          type:
            - boolean
            - 'null'
          description: Whether the driver must have a CDL.
      type: object
      additionalProperties: true
    Metadata:
      description: >-
        Set of key-value pairs that you can attach to an object.

        This can be useful for storing additional information about the object
        in a structured format.

        Individual keys can be unset by posting an empty value to them.

        All keys can be unset by posting an empty value to metadata.
      properties: {}
      type: object
      additionalProperties:
        type: string
      examples:
        - tmsOrderId: '1314234'
          customerName: Acme Corp
    Truckload:
      type: string
      enum:
        - FULL
        - PARTIAL
      description: >-
        Whether the load is full truckload or partial truckload.




         - `FULL`: Full truckload - the entire trailer is dedicated to this load.
         - `PARTIAL`: Partial truckload - the load shares trailer space with other shipments.
    Load:
      description: A load in the Cargado system.
      properties:
        externalId:
          type: string
          description: >-
            The unique ID for the load in your TMS. This identifier will not be
            displayed outside your organization.

            Examples: "456293", "TMS232423"
          minLength: 1
          maxLength: 255
          examples:
            - '456293'
        externalCustomerId:
          type: string
          description: >-
            The unique ID of your customer in your TMS. This will not be
            displayed outside your organization.

            This should not change for the lifetime of the load.

            Examples: "ACMECORP", "ASHIPPERCO"
          minLength: 1
          maxLength: 255
          examples:
            - ACMECORP
        externalDisplayId:
          type:
            - string
            - 'null'
          description: >-
            A customizable display ID for the load. This field allows
            organizations to configure how their load IDs

            are displayed in Cargado. If not provided, the externalId will be
            used as the display ID.

            Examples: "ORD-2024-001", "SHIP-456293", "LOAD-TMS232423"
          minLength: 1
          maxLength: 255
          examples:
            - ORD-2024-001
        externalWorkspaceId:
          type:
            - string
            - 'null'
          description: >-
            The ID used to map your freight to team/user workspaces in Cargado.
            If not

            provided, the freight will be created in your organization's default
            workspace.
        status:
          $ref: '#/components/schemas/LoadStatus'
          description: The status of the load.
        referenceNumbers:
          items:
            $ref: '#/components/schemas/ReferenceNumber'
          type:
            - array
            - 'null'
          description: Reference numbers associated with the load.
        commodities:
          items:
            $ref: '#/components/schemas/LoadCommodity'
          type: array
          description: >-
            The commodities for the load.

            Usually required, but can be omitted for power only loads that are
            load-out or tow-away.
          minItems: 0
          maxItems: 128
        trailerRequirements:
          $ref: '#/components/schemas/TrailerRequirements'
          description: The trailer requirements for the load.
        requiredEquipment:
          items:
            $ref: '#/components/schemas/RequiredEquipment'
          type:
            - array
            - 'null'
          description: A list of standalone equipment required for the load.
        carrierRequirements:
          $ref: '#/components/schemas/CarrierRequirements'
          description: The requirements for the carrier.
        driverRequirements:
          $ref: '#/components/schemas/DriverRequirements'
          description: The requirements for the driver.
        metadata:
          allOf:
            - $ref: '#/components/schemas/Metadata'
          nullable: true
          description: |-
            Set of key-value pairs that you can attach to an object.
            This can be useful for storing additional information about
            the object in a structured format. Individual keys can be unset
            by posting an empty value to them. All keys can be unset by
            posting an empty value to metadata.
          examples:
            - tmsOrderId: '1314234'
              customerName: Acme Corp
        truckload:
          allOf:
            - $ref: '#/components/schemas/Truckload'
          nullable: true
          description: Whether the load is full truckload or partial truckload.
        roundTrip:
          type:
            - boolean
            - 'null'
          description: Whether the load is a round trip.
        linearFeet:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Linear feet is the amount of floor space cargo occupies in a
            trailer. This is primarily

            relevant for partial truckload shipments. If not provided for
            partial loads, it will be

            automatically calculated based on commodity dimensions.
        maxBuy:
          allOf:
            - $ref: '#/components/schemas/CurrencyValue'
          nullable: true
          description: >-
            The maximum buy amount for the load. Typically used to inform team
            members of what rate

            they can cover the freight at without manager approval. This value
            is not used directly,

            but can be referenced when setting up posting rules.
        targetRate:
          allOf:
            - $ref: '#/components/schemas/CurrencyValue'
          nullable: true
          description: >-
            The target rate for the load. Typically used to inform team members
            of what rate they should

            target when covering freight. This value is not used directly, but
            can be referenced when

            setting up posting rules.
        id:
          type: string
          description:
            The unique id for the load in the Cargado system. This is a UUID
            prefixed with `load_`.
          examples:
            - load_c6ee2dff-f35f-4880-b7a6-9b2a1fa1476e
        stops:
          items:
            anyOf:
              - $ref: '#/components/schemas/PickupStop'
              - $ref: '#/components/schemas/DeliveryStop'
              - $ref: '#/components/schemas/BorderCrossingStop'
          type: array
          description:
            The list of stops for the load. The first stop is the origin and
            the last stop is the destination.
          minItems: 2
          maxItems: 64
      required:
        - externalId
        - externalCustomerId
        - status
        - trailerRequirements
        - carrierRequirements
        - driverRequirements
        - id
        - stops
      type: object
      additionalProperties: true
    LoadsSyncOutput:
      description: Output interface for synchronizing load data.
      properties:
        load:
          $ref: '#/components/schemas/Load'
      required:
        - load
      type: object
      additionalProperties: true
    StopLocationAddressInput:
      description: A structured address with individual components.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - ADDRESS
          description: The type of place
        street:
          type: string
          description: The street address of the place.
          minLength: 0
          maxLength: 255
          examples:
            - 123 Main St
        neighborhood:
          type: string
          description: The neighborhood of the place.
          minLength: 0
          maxLength: 255
          examples:
            - Valle Oriente
        city:
          type: string
          description: |-
            The city of the place.
            Examples: "Chicago", "Monterrey", "Seattle"
          minLength: 0
          maxLength: 255
          examples:
            - Chicago
        state:
          type: string
          description: |-
            The state or province of the place.
            Examples: "IL", "NLE", "Nuevo León"
          minLength: 0
          maxLength: 255
          examples:
            - IL
        countryCode:
          $ref: '#/components/schemas/CountryCode'
          description: The ISO 3166-1 alpha-2 country code of the place.
        postalCode:
          type: string
          description: |-
            The postal code of the place.
            Examples: "98335", "64000", "V6B 4N7"
          examples:
            - '98335'
      required:
        - type
        - street
        - city
        - state
        - countryCode
      type: object
      additionalProperties: true
    StopLocationFullAddressInput:
      description: A complete address provided as a single string.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - FULL_ADDRESS
          description: The type of place
        fullAddress:
          type: string
          description: The full address of the place.
          examples:
            - 123 Main St, Chicago, IL 60601
      required:
        - type
        - fullAddress
      type: object
      additionalProperties: true
    StopLocationInput:
      description: Location information for a stop.
      properties:
        coordinates:
          $ref: '#/components/schemas/Coordinates'
          description: The GPS coordinates of the place.
        isCtpatCertified:
          type: boolean
          description: Whether the place is CTPAT certified.
        isPipCertified:
          type: boolean
          description: Whether the place is PIP certified.
        isOeaCertified:
          type: boolean
          description: Whether the place is OEA Certified.
        carrierPreapproval:
          $ref: '#/components/schemas/CarrierPreapproval'
          description: |-
            Whether the place requires a pre-approved carrier.
             - `FIXED_LIST`: The carrier must be from a fixed set.
             - `PRE_APPROVED`: The carrier can be pre-approved.
             - `NOT_REQUIRED`: No pre-approval is required.
        timezone:
          type: string
          description: >-
            The timezone of the place (from the IANA timezone database).

            Examples: "America/Chicago", "America/Monterrey",
            "America/Los_Angeles"
          examples:
            - America/Chicago
        place:
          anyOf:
            - $ref: '#/components/schemas/StopLocationAddressInput'
            - $ref: '#/components/schemas/StopLocationFullAddressInput'
          description: The address or other type of place.
      required:
        - place
      type: object
      additionalProperties: true
    UnspecifiedAppointmentInput:
      description: An appointment that is unspecified or unknown.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - UNSPECIFIED
          description: The appointment is unspecified or unknown.
      required:
        - type
      type: object
      additionalProperties: true
    ToBeSetBySpecificTimeInput:
      description: The appointment will be set by a specific time.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - SPECIFIC_TIME
          description: The appointment will be set by a specific time.
        time:
          type: string
          description: >-
            The time that the appointment will be set by.


            Can be a ISO 8601 date string with or without a timezone descriptor.

            If a timezoneless date string is provided, the timezone will be
            inferred from the location of the stop.

            If the timezone of the stop cannot be determined, then an error will
            be returned
          pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$
          examples:
            - 2024-01-01T00:00:00Z
      required:
        - type
        - time
      type: object
      additionalProperties: true
    ToBeSetByRelativeToEventInput:
      description: The appointment will be set relative to an event.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - RELATIVE_TO_EVENT
          description: The appointment will be set relative to an event.
        event:
          type: string
          enum:
            - BORDER_CROSSING
            - DISPATCH
          description: >-
            The event the appointment will be set relative to.




             - `BORDER_CROSSING`: The appointment will be set after the border crossing.
             - `DISPATCH`: The appointment will be set after the carrier is dispatched.
      required:
        - type
        - event
      type: object
      additionalProperties: true
    AppointmentToBeSetInput:
      description: An appointment that has not been set yet.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - TO_BE_SET
          description: An appointment that has not been set yet.
        possibleAppointmentRange:
          properties:
            end:
              type: string
              description: >-
                The latest possible end time of the appointment.


                Can be a ISO 8601 date string with or without a timezone
                descriptor.

                If a timezoneless date string is provided, the timezone will be
                inferred from the location of the stop.

                If the timezone of the stop cannot be determined, then an error
                will be returned
              pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$
              examples:
                - 2024-01-01T00:00:00Z
            start:
              type: string
              description: >-
                The earliest possible start time of the appointment.


                Can be a ISO 8601 date string with or without a timezone
                descriptor.

                If a timezoneless date string is provided, the timezone will be
                inferred from the location of the stop.

                If the timezone of the stop cannot be determined, then an error
                will be returned
              pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$
              examples:
                - 2024-01-01T00:00:00Z
          required:
            - end
            - start
          type: object
          description: The range of possible appointment times.
        toBeSetBy:
          anyOf:
            - $ref: '#/components/schemas/ToBeSetBySpecificTimeInput'
            - $ref: '#/components/schemas/ToBeSetByRelativeToEventInput'
          description: When the appointment will be set by.
      required:
        - type
        - toBeSetBy
      type: object
      additionalProperties: true
    SetAppointmentWindowInput:
      description: A set appointment, window of time.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - SET_APPOINTMENT_WINDOW
          description: A set appointment, window of time.
        windowStartTime:
          type: string
          description: >-
            The start time of the window.


            Can be a ISO 8601 date string with or without a timezone descriptor.

            If a timezoneless date string is provided, the timezone will be
            inferred from the location of the stop.

            If the timezone of the stop cannot be determined, then an error will
            be returned
          pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$
          examples:
            - 2024-01-01T00:00:00Z
        windowEndTime:
          type: string
          description: >-
            The end time of the window.


            Can be a ISO 8601 date string with or without a timezone descriptor.

            If a timezoneless date string is provided, the timezone will be
            inferred from the location of the stop.

            If the timezone of the stop cannot be determined, then an error will
            be returned
          pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$
          examples:
            - 2024-01-01T00:00:00Z
      required:
        - type
        - windowStartTime
        - windowEndTime
      type: object
      additionalProperties: true
    SetAppointmentExactInput:
      description: The appointment is an exact time.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - SET_APPOINTMENT_EXACT
          description: The appointment is an exact time.
        time:
          type: string
          description: >-
            The exact time of the appointment.


            Can be a ISO 8601 date string with or without a timezone descriptor.

            If a timezoneless date string is provided, the timezone will be
            inferred from the location of the stop.

            If the timezone of the stop cannot be determined, then an error will
            be returned
          pattern: ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$
          examples:
            - 2024-01-01T00:00:00Z
      required:
        - type
        - time
      type: object
      additionalProperties: true
    FirstComeFirstServeAppointmentInput:
      description: The appointment is first come first serve.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - FIRST_COME_FIRST_SERVE
          description: The appointment is first come first serve.
      required:
        - type
      type: object
      additionalProperties: true
    LoadPickupStopInput:
      description: Input-specific pickup stop.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - PICKUP
          description:
            Whether the stop is a pickup or delivery of goods or a border
            crossing.
        externalId:
          type: string
          description:
            The unique ID for the stop in your TMS. This identifier will not be
            displayed outside your organization.
          minLength: 1
          maxLength: 255
          examples:
            - 27924_1
        referenceNumbers:
          items:
            $ref: '#/components/schemas/ReferenceNumber'
          type:
            - array
            - 'null'
        loadingMethod:
          allOf:
            - $ref: '#/components/schemas/LoadingMethod'
          nullable: true
          description:
            Whether the pickup or delivery is live (the truck driver waits
            while the cargo is loaded onto or unloaded from the trailer) or drop
            (the driver picks up a, often preloaded, trailer at the facility or
            drops off a trailer at the facility)
        inboundTransitRequirements:
          $ref: '#/components/schemas/InboundTransitRequirements'
          description:
            Any requirements on how the transit inbound to this stop is
            conducted.
        dropDurationHours:
          type:
            - number
            - 'null'
          format: double
          description: >-
            When the loadingMethod is DROP, this represents the number of hours
            after a trailer is delivered at pickup before the driver should
            arrive to pickup the then loaded trailer.


            Examples: 24, 8
          minimum: 0
          maximum: 2160
          examples:
            - 24
        fumigation:
          allOf:
            - $ref: '#/components/schemas/StopRequirement'
          nullable: true
          description: Whether fumigation is required for the stop.
        scaleTicket:
          allOf:
            - $ref: '#/components/schemas/StopRequirement'
          nullable: true
          description: Whether a scale ticket is required for the stop.
        driverAssistRequired:
          type:
            - boolean
            - 'null'
          description: Whether driver assisted loading is required for the stop.
        location:
          $ref: '#/components/schemas/StopLocationInput'
          description: The location of the stop.
        appointment:
          anyOf:
            - $ref: '#/components/schemas/UnspecifiedAppointmentInput'
            - $ref: '#/components/schemas/AppointmentToBeSetInput'
            - $ref: '#/components/schemas/SetAppointmentWindowInput'
            - $ref: '#/components/schemas/SetAppointmentExactInput'
            - $ref: '#/components/schemas/FirstComeFirstServeAppointmentInput'
      required:
        - type
        - externalId
        - location
        - appointment
      type: object
      additionalProperties: true
    LoadDeliveryStopInput:
      description: Input-specific delivery stop.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - DELIVERY
          description:
            Whether the stop is a pickup or delivery of goods or a border
            crossing.
        externalId:
          type: string
          description:
            The unique ID for the stop in your TMS. This identifier will not be
            displayed outside your organization.
          minLength: 1
          maxLength: 255
          examples:
            - 27924_1
        referenceNumbers:
          items:
            $ref: '#/components/schemas/ReferenceNumber'
          type:
            - array
            - 'null'
        loadingMethod:
          allOf:
            - $ref: '#/components/schemas/LoadingMethod'
          nullable: true
          description:
            Whether the pickup or delivery is live (the truck driver waits
            while the cargo is loaded onto or unloaded from the trailer) or drop
            (the driver picks up a, often preloaded, trailer at the facility or
            drops off a trailer at the facility)
        inboundTransitRequirements:
          $ref: '#/components/schemas/InboundTransitRequirements'
          description:
            Any requirements on how the transit inbound to this stop is
            conducted.
        dropDurationHours:
          type:
            - number
            - 'null'
          format: double
          description: >-
            When the loadingMethod is DROP, this represents the number of hours
            after a trailer is delivered at pickup before the driver should
            arrive to pickup the then loaded trailer.


            Examples: 24, 8
          minimum: 0
          maximum: 2160
          examples:
            - 24
        fumigation:
          allOf:
            - $ref: '#/components/schemas/StopRequirement'
          nullable: true
          description: Whether fumigation is required for the stop.
        scaleTicket:
          allOf:
            - $ref: '#/components/schemas/StopRequirement'
          nullable: true
          description: Whether a scale ticket is required for the stop.
        driverAssistRequired:
          type:
            - boolean
            - 'null'
          description: Whether driver assisted loading is required for the stop.
        location:
          $ref: '#/components/schemas/StopLocationInput'
          description: The location of the stop.
        appointment:
          anyOf:
            - $ref: '#/components/schemas/UnspecifiedAppointmentInput'
            - $ref: '#/components/schemas/AppointmentToBeSetInput'
            - $ref: '#/components/schemas/SetAppointmentWindowInput'
            - $ref: '#/components/schemas/SetAppointmentExactInput'
            - $ref: '#/components/schemas/FirstComeFirstServeAppointmentInput'
      required:
        - type
        - externalId
        - location
        - appointment
      type: object
      additionalProperties: true
    LoadBorderCrossingStopInput:
      description:
        Border crossing stops don't have appointments, so they can use the
        original type.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - BORDER_CROSSING
          description:
            Whether the stop is a pickup or delivery of goods or a border
            crossing.
        externalId:
          type: string
          description:
            The unique ID for the stop in your TMS. This identifier will not be
            displayed outside your organization.
          minLength: 1
          maxLength: 255
          examples:
            - 27924_1
        referenceNumbers:
          items:
            $ref: '#/components/schemas/ReferenceNumber'
          type:
            - array
            - 'null'
        usMxBorderCrossing:
          allOf:
            - $ref: '#/components/schemas/UsMxBorderCrossing'
          nullable: true
          description: The border crossing port between the United States and Mexico.
        borderCrossingStrategy:
          allOf:
            - $ref: '#/components/schemas/BorderCrossingStrategy'
          nullable: true
          description: |-
            The strategy used to cross the US border.
            Examples: 'PRE_ASSIGNED', 'PROVIDER'
        requiredInspections:
          items:
            $ref: '#/components/schemas/BorderCrossingRequiredInspection'
          type:
            - array
            - 'null'
          description: |-
            Inspections required to cross the US border.
            Examples: 'USDA', 'PROFEPA'
        expectedDwellTimeMinutes:
          type:
            - number
            - 'null'
          format: double
          description:
            The expected duration, in minutes, that a shipment or cargo will
            spend at a specific location or during a particular stage of the
            logistics process.
          examples:
            - 12
      required:
        - type
        - externalId
      type: object
      additionalProperties: true
    CarrierInput:
      description: |-
        A specific carrier as defined by a set of unique government identifiers.
        At least one of the identifiers must be provided.
      properties:
        dotNumber:
          type: string
          description: The carrier's DOT number
          examples:
            - '123456'
        mcNumber:
          type: string
          description: The carrier's MC number
          examples:
            - '248243'
        mxNumber:
          type: string
          description: The carrier's MX number
          examples:
            - '2343'
        rfcNumber:
          type: string
          description: The carrier's RFC number
          examples:
            - RUSM2344227MY4
        cvorNumber:
          type: string
          description: The carrier's Commercial Vehicle Operator Registration number (CVOR)
          examples:
            - 2344227MY4
        nirNumber:
          type: string
          description: The carrier's Registration identification number (NIR)
          examples:
            - R-23424
        nscNumber:
          type: string
          description: The carrier's National Safety Code (NSC) number
          examples:
            - 2344227MY4
      type: object
      additionalProperties: true
    LoadInput:
      description: Input interface for synchronizing load data.
      properties:
        externalId:
          type: string
          description: >-
            The unique ID for the load in your TMS. This identifier will not be
            displayed outside your organization.

            Examples: "456293", "TMS232423"
          minLength: 1
          maxLength: 255
          examples:
            - '456293'
        externalCustomerId:
          type: string
          description: >-
            The unique ID of your customer in your TMS. This will not be
            displayed outside your organization.

            This should not change for the lifetime of the load.

            Examples: "ACMECORP", "ASHIPPERCO"
          minLength: 1
          maxLength: 255
          examples:
            - ACMECORP
        externalDisplayId:
          type:
            - string
            - 'null'
          description: >-
            A customizable display ID for the load. This field allows
            organizations to configure how their load IDs

            are displayed in Cargado. If not provided, the externalId will be
            used as the display ID.

            Examples: "ORD-2024-001", "SHIP-456293", "LOAD-TMS232423"
          minLength: 1
          maxLength: 255
          examples:
            - ORD-2024-001
        externalWorkspaceId:
          type:
            - string
            - 'null'
          description: >-
            The ID used to map your freight to team/user workspaces in Cargado.
            If not

            provided, the freight will be created in your organization's default
            workspace.
        status:
          $ref: '#/components/schemas/LoadStatus'
          description: The status of the load.
        referenceNumbers:
          items:
            $ref: '#/components/schemas/ReferenceNumber'
          type:
            - array
            - 'null'
          description: Reference numbers associated with the load.
        commodities:
          items:
            $ref: '#/components/schemas/LoadCommodity'
          type: array
          description: >-
            The commodities for the load.

            Usually required, but can be omitted for power only loads that are
            load-out or tow-away.
          minItems: 0
          maxItems: 128
        trailerRequirements:
          $ref: '#/components/schemas/TrailerRequirements'
          description: The trailer requirements for the load.
        requiredEquipment:
          items:
            $ref: '#/components/schemas/RequiredEquipment'
          type:
            - array
            - 'null'
          description: A list of standalone equipment required for the load.
        carrierRequirements:
          $ref: '#/components/schemas/CarrierRequirements'
          description: The requirements for the carrier.
        driverRequirements:
          $ref: '#/components/schemas/DriverRequirements'
          description: The requirements for the driver.
        metadata:
          allOf:
            - $ref: '#/components/schemas/Metadata'
          nullable: true
          description: |-
            Set of key-value pairs that you can attach to an object.
            This can be useful for storing additional information about
            the object in a structured format. Individual keys can be unset
            by posting an empty value to them. All keys can be unset by
            posting an empty value to metadata.
          examples:
            - tmsOrderId: '1314234'
              customerName: Acme Corp
        truckload:
          allOf:
            - $ref: '#/components/schemas/Truckload'
          nullable: true
          description: Whether the load is full truckload or partial truckload.
        roundTrip:
          type:
            - boolean
            - 'null'
          description: Whether the load is a round trip.
        linearFeet:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Linear feet is the amount of floor space cargo occupies in a
            trailer. This is primarily

            relevant for partial truckload shipments. If not provided for
            partial loads, it will be

            automatically calculated based on commodity dimensions.
        maxBuy:
          allOf:
            - $ref: '#/components/schemas/CurrencyValue'
          nullable: true
          description: >-
            The maximum buy amount for the load. Typically used to inform team
            members of what rate

            they can cover the freight at without manager approval. This value
            is not used directly,

            but can be referenced when setting up posting rules.
        targetRate:
          allOf:
            - $ref: '#/components/schemas/CurrencyValue'
          nullable: true
          description: >-
            The target rate for the load. Typically used to inform team members
            of what rate they should

            target when covering freight. This value is not used directly, but
            can be referenced when

            setting up posting rules.
        stops:
          items:
            anyOf:
              - $ref: '#/components/schemas/LoadPickupStopInput'
              - $ref: '#/components/schemas/LoadDeliveryStopInput'
          type: array
          description:
            The list of stops for the load. The first stop is the origin and
            the last stop is the destination.
          minItems: 2
          maxItems: 64
        borderCrossings:
          items:
            $ref: '#/components/schemas/LoadBorderCrossingStopInput'
          type: array
          description: The list of border crossings for the load.
          minItems: 0
          maxItems: 64
        assignedCarrier:
          allOf:
            - $ref: '#/components/schemas/CarrierInput'
          nullable: true
          description: >-
            The assigned carrier for the load.


            For US carriers, the DOT number is required.




               - The MC number is also required for interstate loads.
            For Canadian carriers, the CVOR, NIR, or NSC number is required.




               - The DOT and MC number is also required for loads that transit in the US.
            For Mexican carriers, the RFC number is required.




               - The DOT and MX number is also required for loads that transit in the US.
        schemaVersionNumber:
          type: number
          format: double
          description: >-
            Schema version for your load payload.


            - Start at 0 and increment by 1 whenever the set of populated fields
            changes




              (e.g., you begin sending a new field or stop sending an existing one).
            - Used for defining the expected set of fields in the payload and
            protect API-synced fields from being overwritten by in-app edits
            across versions.

            - Errors will be thrown if the payload does not exactly match the
            expected set of fields.


            Bootstrap mode:

            - If omitted or null, the payload is accepted and fields remain
            user-editable in Cargado.

            - Use this during initial setup; set to 0 when ready to enforce
            protection.


            Constraints: must increase by exactly 1, never decrease, and cannot
            be set back to null once defined.
          examples:
            - 0
      required:
        - externalId
        - externalCustomerId
        - status
        - trailerRequirements
        - carrierRequirements
        - driverRequirements
        - stops
      type: object
      additionalProperties: true
    LoadsSyncInput:
      description: Input interface for synchronizing load data.
      properties:
        load:
          $ref: '#/components/schemas/LoadInput'
      required:
        - load
      type: object
      additionalProperties: true
    CarrierRelationshipStatus:
      type: string
      enum:
        - ACTIVE
        - NEEDS_REVIEW
        - DO_NOT_DISPATCH
      description: >-
        - ACTIVE: The carrier is active with the organization and ready to be
        assigned to freight.

        - NEEDS_REVIEW: The carrier needs review prior to being assigned to
        freight.

        - DO_NOT_DISPATCH: The carrier is not allowed to be assigned to freight,
        and will not see




          any freight in the marketplace.
    CarrierOnboardingStatus:
      type: string
      enum:
        - ONBOARDED
        - NEEDS_TO_ONBOARD
      description: >-
        There are 2 possible values for a carrier relationship status:

        - ONBOARDED: The carrier is onboarded.

        - NEEDS_TO_ONBOARD: The carrier needs to be onboarded, even if they have
        been onboarded before.
    CarrierRelationshipSource:
      type: string
      enum:
        - API
        - USER
    CarrierRelationship:
      description: >-
        A carrier relationship represents the relationship between a carrier and

        an organization, including their onboarding status and whether they can
        be

        assigned to freight.


        If a carrier relationship is not found, the carrier will be offered an
        onboarding link

        but will not be assigned to freight until a relationship is created.


        A NEEDS_REVIEW but onboarded carrier still requires manual review prior
        to being assigned

        to freight. An ACTIVE but not onboarded carrier can be assigned to
        freight but the

        carrier is still offered an onboarding link.


        DO_NOT_DISPATCH should be used to block a carrier from being assigned to
        freight at an

        organization level. Use freight level rules to block a carrier from
        being assigned to

        specific freight.
      properties:
        id:
          type: string
        organizationId:
          type: string
        carrierOrganizationId:
          type: string
        status:
          $ref: '#/components/schemas/CarrierRelationshipStatus'
        onboardingStatus:
          $ref: '#/components/schemas/CarrierOnboardingStatus'
        source:
          $ref: '#/components/schemas/CarrierRelationshipSource'
      required:
        - id
        - organizationId
        - carrierOrganizationId
        - status
        - onboardingStatus
      type: object
      additionalProperties: true
    CarrierRelationshipUpsertOutput:
      properties:
        carrierRelationships:
          items:
            allOf:
              - $ref: '#/components/schemas/CarrierRelationship'
            nullable: true
          type: array
      required:
        - carrierRelationships
      type: object
      additionalProperties: true
    CarrierRelationshipInput:
      properties:
        carrier:
          $ref: '#/components/schemas/CarrierInput'
        status:
          $ref: '#/components/schemas/CarrierRelationshipStatus'
        onboardingStatus:
          $ref: '#/components/schemas/CarrierOnboardingStatus'
      required:
        - carrier
        - status
        - onboardingStatus
      type: object
      additionalProperties: true
    CarrierRelationshipUpsertInput:
      properties:
        carrierRelationships:
          items:
            $ref: '#/components/schemas/CarrierRelationshipInput'
          type: array
      required:
        - carrierRelationships
      type: object
      additionalProperties: true
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: api-key
