--- title: "Create or update load" method: POST path: "/v2/loads" tags: ["Load Management"] --- # Create or update load `POST /v2/loads` ## Request - Base URL: `https://api.prod.goaugment.com` - URL: `https://api.prod.goaugment.com/v2/loads` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a load, or replace an existing load matched by `loadNumber`. The whole payload is validated on every request. Which fields are required depends on the load's `status`: stop appointment windows are optional while the load is a `DRAFT` and required on every route stop once the load reaches `CUSTOMER_CONFIRMED` or later. See [Load Status Validation](/guide/start-developing/load-status-validation) for the full status-by-status breakdown. ## Request body - LoadRequest - `load` Load, required - `loadNumber` string, required - `brokerageLoadInternalId` string: Optional internal load ID in the TMS. Use loadNumber as the main ID. - `mode` 'DRAYAGE' | 'EXPEDITE' | 'FTL' | 'LTL' | 'PARTIAL', required - `rateType` 'CONTRACT' | 'DEDICATED' | 'PROJECT' | 'SPOT' - `status` 'DRAFT' | 'CUSTOMER_CONFIRMED' | 'COVERED' | 'DISPATCHED' | 'AT_PICKUP' | 'IN_TRANSIT' | 'AT_DELIVERY' | 'DELIVERED' | 'POD_COLLECTED' | 'PAID' | 'CANCELED' | 'ERROR' | 'ARCHIVED', required: The load's lifecycle status. `CANCELED`, `ERROR`, and `ARCHIVED` are terminal or administrative states rather than lifecycle stages; a load in any status can move to one of them. Validation requirements vary by status — see [Load Status Validation](/guide/start-developing/load-status-validation). - `referenceNumbers` object[] - `name` 'BILLED_DATE' | 'BOOKING_NUMBER' | 'BOL_NUMBER' | 'CONSIGNEE_NUMBER' | 'CONSIGNEE_REF_NUMBER' | 'CONTAINER_NUMBER' | 'CONTROL_NUMBER' | 'CUSTOMER_REF_NUMBER' | 'DAT_POSTING_ID' | 'PICKUP_NUMBER' | 'PO_NUMBER' | 'POSTING_GROUP_ID' | 'PRO_NUMBER' | 'RELEASED_DATE' | 'REQUIRED_DOCS' | 'SHIPMENT_NUMBER' | 'SHIPPER_NUMBER' | 'TMS_LOAD_STATUS' | 'TMS_SHIPMENT_STATUS' | 'TRAILER_NUMBER' | 'TRUCK_NUMBER' | 'OTHER', required - `value` string, required - `equipment` object: Optional equipment details. If provided, equipmentType is required - `equipmentType` 'AUTO_CARRIER' | 'AUTO_TRANSPORT' | 'B_TRAIN' | 'BOX_TRUCK' | 'CHASSIS' | 'CONESTOGA' | 'CONTAINER' | 'CONTAINER_INSULATED' | 'CONTAINER_OR_CHASSIS' | 'CONTAINER_REFRIGERATED' | 'CONTAINERS' | 'CONVEYOR' | 'DECKS_SPECIALIZED' | 'DECKS_STANDARD' | 'DOUBLE_DROP' | 'DROP_DECK_LANDOLL' | 'DRY_BULK' | 'DRY_VAN' | 'DUMP_END' | 'DUMP_SIDE' | 'DUMP_TRAILER' | 'FLATBED' | 'FLATBED_AIR_RIDE' | 'FLATBED_CONESTOGA' | 'FLATBED_DOUBLE' | 'FLATBED_HAZMAT' | 'FLATBED_HOTSHOT' | 'FLATBED_MAXI' | 'FLATBED_OR_STEP_DECK' | 'FLATBED_OVERDIMENSION' | 'FLATBED_STRETCH' | 'FLATBED_VAN_REEFER' | 'FLATBED_WITH_CHAINS' | 'FLATBED_WITH_SIDES' | 'FLATBED_WITH_TARPS' | 'FLATBED_WITH_TEAM' | 'FLATBEDS' | 'HAZARDOUS_MATERIALS' | 'HOPPER_BOTTOM' | 'HOTSHOT' | 'HOTSHOT_FLATBED' | 'INSULATED_VAN_OR_REEFER' | 'LOWBOY' | 'LOWBOY_OR_REM_GOOSENECK_RGN' | 'LOWBOY_OVERDIMENSION' | 'MOVING_VAN' | 'PLATE_TRAILER' | 'PNEUMATIC' | 'POWER_ONLY' | 'POWER_ONLY_LOAD_OUT' | 'POWER_ONLY_TOW_AWAY' | 'REEFER' | 'REEFER_AIR_RIDE' | 'REEFER_DEEP_FROZEN' | 'REEFER_DOUBLE' | 'REEFER_HAZMAT' | 'REEFER_INTERMODAL' | 'REEFER_LOGISTICS' | 'REEFER_OR_POWER_ONLY' | 'REEFER_OR_VENTED_VAN' | 'REEFER_PALLET_EXCHANGE' | 'REEFER_QUADAXLE' | 'REEFER_TRIAXLE' | 'REEFER_WITH_TEAM' | 'REEFERS' | 'REMOVABLE_GOOSE_NECK' | 'REMOVABLE_GOOSENECK' | 'SPRINTER_VAN' | 'SPRINTER_VAN_HAZMAT' | 'SPRINTER_VAN_TEMP_CONTROLLED' | 'SPRINTER_VAN_WITH_TEAM' | 'STEP_DECK' | 'STEP_DECK_OR_REM_GOOSENECK_RGN' | 'STEPDECK_CONESTOGA' | 'STRAIGHT_BOX_TRUCK' | 'STRAIGHT_BOX_TRUCK_HAZMAT' | 'STRAIGHT_BOX_TRUCK_REEFER' | 'STRAIGHT_TRUCK' | 'STRETCH_TRAILER' | 'TANKER' | 'TANKER_ALUMINUM' | 'TANKER_INTERMODAL' | 'TANKER_STEEL' | 'TANKERS' | 'TRUCK_AND_TRAILER' | 'V2G' | 'VAH' | 'VAN' | 'VAN_AIR_RIDE' | 'VAN_BLANKET_WRAP' | 'VAN_CONESTOGA' | 'VAN_CURTAIN' | 'VAN_DOUBLE' | 'VAN_HAZMAT' | 'VAN_HIGH_CUBE' | 'VAN_HIGH_CUBE_4_AXLE' | 'VAN_HOTSHOT' | 'VAN_INSULATED' | 'VAN_INTERMODAL' | 'VAN_LIFT_GATE' | 'VAN_LOGISTICS' | 'VAN_OPEN_TOP' | 'VAN_OR_FLATBED' | 'VAN_OR_FLATBED_WITH_TARPS' | 'VAN_OR_POWER_ONLY' | 'VAN_OR_REEFER' | 'VAN_PALLET_EXCHANGE' | 'VAN_ROLLER_BED' | 'VAN_SPRINTER' | 'VAN_TRIPLE' | 'VAN_VENTED' | 'VAN_WITH_CURTAINS' | 'VAN_WITH_TEAM' | 'VANS_SPECIALIZED' | 'VANS_STANDARD' | 'VENTED_VAN_OR_POWER_ONLY' | 'WALKING_FLOOR' | 'OTHER', required: Required if equipment object is provided - `description` string: A field suitable for mapping the exact string value that the source system stores for equipment type - `dimensions` object: Physical dimensions of the equipment/trailer. At least one of length, width, or height is required if this object is provided. - `length` number: Length, in the given unit. Must be positive. - `width` number: Width, in the given unit. Must be positive. - `height` number: Height, in the given unit. Must be positive. - `unit` 'IN' | 'CM' | 'FT' | 'M' | 'YD', required: Unit of measure for length, width, and height - `accessorials` AccessorialsEnum[] - `route` LoadRouteStop[], required - `sequence` integer, required: The sequence number of the stop in the route. Number should start at 1 increase by 1 for the following stop. - `externalId` string: Optional external ID for the stop. This is used to link the stop to an external system. - `facilityCode` string, nullable: Identifier of the facility where the stop takes place, matching the facility's external ID in your TMS. Stored as provided and not checked against a known facility, so an unrecognized code is accepted rather than rejected. - `stopActivity` 'PICKUP' | 'DELIVERY', required - `address` object, required - `company` string - `locationName` string - `street1` string, required - `street2` string - `city` string, required - `stateOrProvince` string, required - `postalCode` string, required - `country` string, required: Must be 2-letter ISO country code as listed here: https://www.iban.com/country-codes - `notes` string: Optional notes for the stop. - `expectedArrivalWindowStart` string, date-time: Expected arrival window start time in UTC, or with a specific timezone offset. Optional at `DRAFT`; required once the load reaches `CUSTOMER_CONFIRMED` or later. Must be at or before `expectedArrivalWindowEnd` whenever both are present. - `expectedArrivalWindowEnd` string, date-time: Expected arrival window end time in UTC, or with a specified timezone offset. Optional at `DRAFT`; required once the load reaches `CUSTOMER_CONFIRMED` or later. - `actualArrivalTime` string, date-time: Actual arrival time in UTC, or with a specific timezone offset - `actualCompletionTime` string, date-time: Actual completion time in UTC, or with a specific timezone offset - `expectedDropWindowStart` string, date-time: Expected window start time for drop trailers in UTC, or with a specific timezone offset - `expectedDropWindowEnd` string, date-time: Expected window end time for drop trailers in UTC, or with a specific timezone offset - `mustArriveByDate` string, date-time: The date and time by which the carrier must arrive at this stop, in UTC or with a specific timezone offset - `isLocalTime` boolean: When true, route times are in local time instead of UTC. When this is true, omit the Z suffix or timezone offset from all route time strings. Example: 2017-07-21T17:32:28 - `schedulingType` 'APPT' | 'FCFS': Scheduling type for the stop. - APPT (Appointment) indicates the stop operates on an appointment basis. - FCFS (First Come First Serve) indicates the stop accepts arrivals on a first-come-first-serve basis. - `handlingType` 'DT' | 'L': Handling type for the stop. - DT (Drop Trailer) indicates the location supports drop-trailer operations. - L (Live) indicates live loading or unloading where the driver stays with the trailer. - `customData` StopCustomData, nullable: Optional client-specific metadata for this stop. Use string keys; each value may be a string, number, boolean, array of JSON-safe values, or a nested object with the same rules. The serialized JSON must not exceed 2,000 characters. Use this field to attach stop-specific references such as pickup numbers, BOL numbers, or PO numbers to individual stops rather than flattening them into load-level `customData`. On update, sending this field replaces the stored value for that stop. Because routes are replaced wholesale on every write, omitting `customData` from a stop clears it to `null`. Send `null` explicitly to clear a previously stored value. - `items` LoadItem[]: Optional array of items. If provided, each item must include quantity and totalWeightLbs. Use packagingUnit to describe how the item is packaged and handlingUnit to describe how the freight is handled or moved. - `quantity` integer, required: Item quantity. Required if item is provided. - `packagingUnit` LoadItemUnit - `unitType` 'PALLET' | 'PIECE' | 'CARTON' | 'TOTE' | 'SKID' | 'CRATE' | 'BOX' | 'DRUM' | 'CASE' | 'BUNDLE' | 'OTHER' | 'FLOOR_LOADED' | 'ROLL' | 'SHEET', required - `quantity` number, required: Quantity of this unit type. - `handlingUnit` LoadItemUnit - `unitType` 'PALLET' | 'PIECE' | 'CARTON' | 'TOTE' | 'SKID' | 'CRATE' | 'BOX' | 'DRUM' | 'CASE' | 'BUNDLE' | 'OTHER' | 'FLOOR_LOADED' | 'ROLL' | 'SHEET', required - `quantity` number, required: Quantity of this unit type. - `description` string: Commodity description for this item. Augment's AI agent uses this value verbatim when speaking with carriers. - `totalWeightLbs` number, required: Required if item is provided - `lengthInches` integer - `widthInches` integer - `heightInches` integer - `freightClass` '50' | '55' | '60' | '65' | '70' | '77.5' | '85' | '92.5' | '100' | '110' | '125' | '150' | '175' | '200' | '250' | '300' | '400' | '500' - `nmfc` string - `density` number - `pickupSequence` integer - `deliverySequence` integer - `externalTrackingStatus` ExternalTrackingStatus - `source` 'MACROPOINT' | 'P44' | 'OTHER', required: The source system or service providing the tracking status - `message` string, required: Human-readable message describing the current tracking status - `code` 'READY' | 'WAITING' | 'FAILED' | 'COMPLETED', required: Status code indicating the current state of external tracking - `updatedAt` string, date-time, required: The timestamp when the tracking status was last updated in UTC, or with a specific timezone offset - `isPostedToDAT` boolean: Indicates whether the load has been posted to DAT load board. This is required for Augie to search for loads using lane information (pick up and drop off city and state). - `weight` number: Total weight in pounds (lbs) - `totalMiles` number: Total estimated mileage for the entire route of a load - `maxRate` number: Maximum bid amount in USD - `targetRate` number: Target rate in USD - `highValueAmount` number: High value amount in USD - `dimensions` object: Optional dimensions object. If provided, all dimension fields are required. All dimensions are in inches. - `heightInches` integer, required: Required if dimensions object is provided - `lengthInches` integer, required: Required if dimensions object is provided - `widthInches` integer, required: Required if dimensions object is provided - `minimumTemperature` number: Minimum temperature requirement in Fahrenheit - `maximumTemperature` number: Maximum temperature requirement in Fahrenheit - `service` 'HOTSHOT' | 'PARTIAL' | 'STANDARD' | 'TIME_CRITICAL' | 'VOLUME' - `bidExpiration` string, date-time: Bid expiration time in UTC, or with a specific timezone offset - `notes` LoadNote[]: Operational notes about the load. Use this field to send context about actions taken on the load (e.g. broker instructions, status updates). On update, the provided notes are merged with existing notes. - `timestamp` string, date-time, required - `text` string, required: Note content - `author` string, required: Who created the note (e.g. email address or system name) - `bookedRate` number: Booked rate in USD - `shipperRate` number: Shipper rate in USD - `tarpSize` string: Tarp size requirement - `minimumBulkHeadTemperature` number: Minimum bulkhead temperature requirement in Fahrenheit - `maximumBulkHeadTemperature` number: Maximum bulkhead temperature requirement in Fahrenheit - `groupExternalId` string, nullable: The external identifier used to associate this load with a group. Used during create/update to resolve the internal groupKey. - `customData` LoadCustomData, nullable: Optional client-specific metadata for the load. Use string keys; each value may be a string, number, boolean, array of JSON-safe values, or a nested object with the same rules. The serialized JSON must not exceed 10,000 characters. If you want Augie to use values from customData in automated workflows, coordinate the expected keys and meanings with Augment. Your SOPs or workflow instructions may need to be updated so Augie knows when and how to reference those values. On update, sending this field replaces the stored value. Omitting it preserves the existing value, while sending `null` clears it. - `trackingEvents` TrackingEvent[]: Providing this field replaces all existing tracking events for the Load, including an empty array, which clears them. Omit the field to preserve existing tracking events. To append events instead of replacing them, use the POST /v2/loads/tracking endpoint. - `nextSequence` integer: Sequence number of the stop `nextEtaUtc` applies to, matching `LoadRouteStop.sequence`. - `nextEtaUtc` string, date-time: Next estimated arrival time as a UTC ISO 8601 timestamp with an offset (e.g. ending in `Z`, as in `2026-09-12T08:01:05Z`). When `isLocalTime` is true, send a naive local timestamp with no offset instead (e.g. `2026-09-12T03:01:05`). - `eventType` 'DELAYED' | 'INFO' | 'PICKED_UP' | 'PING' | 'COVERED' | 'DISPATCHED', required: Type of tracking event. - `eventSource` '4KITES' | 'CARRIER_API' | 'HIGHWAY' | 'MACROPOINT' | 'P44' | 'PHONE_EMAIL' | 'SMC3' | 'TEXT' | 'TMS' | 'TRUCKER_TOOLS' | 'OTHER', required: How the tracking data was obtained. - `eventUtc` string, date-time, required: Event time as a UTC ISO 8601 timestamp with an offset (e.g. ending in `Z`, as in `2026-09-11T23:00:25Z`). When `isLocalTime` is true, send a naive local timestamp with no offset instead (e.g. `2026-09-11T18:00:25`). - `isLocalTime` boolean: When true, `eventUtc` and `nextEtaUtc` (if present) are treated as naive local times and converted to UTC using the timezone resolved from `latitude`/`longitude`, `postalCode`, or `city`/`stateOrProvince` (in that priority order); `country` (defaults to `US`) helps disambiguate the `postalCode` lookup. One of `latitude`/`longitude`, `postalCode`, or `city`/`stateOrProvince` must be present when `isLocalTime` is true. - `city` string: City closest to the event location. - `country` string: Country of the event location, as an ISO 3166-1 alpha-2 code. Used to disambiguate the `postalCode` lookup when `isLocalTime` is true; defaults to `US` when omitted. Only `US`, `CA`, and `MX` are currently supported for this lookup — any other value falls back to `US`. - `stateOrProvince` string: State or province closest to the event location. - `postalCode` string - `latitude` number - `longitude` number - `temperatureF` number: Temperature in Fahrenheit, if reported by the source. - `notes` string: Free-text context from the carrier communication. - `dispatcher` TrackingEventContact: Contact information for a person associated with a tracking event. - `id` string: Identifier of the contact in the TMS system. - `name` string: Full name of the contact. - `phone` string: Phone number in E.164 format (e.g., +12081234567) or common local format. Supports US, CA, MX, PH. - `phoneExtension` string: Phone number extension (numeric only). - `email` string: Email address of the contact. - `driver` TrackingEventContact: Contact information for a person associated with a tracking event. - `id` string: Identifier of the contact in the TMS system. - `name` string: Full name of the contact. - `phone` string: Phone number in E.164 format (e.g., +12081234567) or common local format. Supports US, CA, MX, PH. - `phoneExtension` string: Phone number extension (numeric only). - `email` string: Email address of the contact. - `carrier` Carrier - `carrierId` string - `name` string, required - `mcNumber` integer - `dotNumber` integer, required - `scac` string - `address` CarrierAddress: Carrier address on a load. Optional on the parent object; when present, include every required field below. - `company` string - `locationName` string - `street1` string, required: Required when address is provided - `street2` string - `city` string, required: Required when address is provided - `stateOrProvince` string, required: Required when address is provided - `postalCode` string, required: Required when address is provided - `country` string, required: Required when address is provided. 2-letter ISO country code: https://www.iban.com/country-codes - `contacts` CarrierContact[] - `id` string - `name` string - `phone` string: Phone number in E.164 format (e.g., +12081234567) or common local format. Supports US, CA, MX, PH. - `phoneExtension` string: Phone number extension (numeric only). - `email` string - `role` 'AP_REP' | 'DISPATCHER' | 'AFTER_HOURS_DISPATCHER' | 'WEEKEND_DISPATCHER' | 'BOOKING' | 'TRACKING', required: Required if contact is provided. - `AP_REP` — Accounts Payable Specialist - `DISPATCHER` — Dispatcher - `AFTER_HOURS_DISPATCHER` — dispatcher to contact outside of regular business hours - `WEEKEND_DISPATCHER` — dispatcher to contact on weekends - `BOOKING` — handles load booking - `TRACKING` — handles load tracking - `drivers` object[] - `id` string - `name` string - `phone` string, required: Phone number in E.164 format (e.g., +12081234567) or common local format. Supports US, CA, MX, PH. - `phoneExtension` string: Phone number extension (numeric only). - `brokerage` Brokerage, required - `contacts` object[] - `id` string - `name` string, required - `phone` string: Phone number in E.164 format (e.g., +12081234567) or common local format. Supports US, CA, MX, PH. - `phoneExtension` string: Phone number extension (numeric only). - `email` string - `role` string[], required: The employee's role(s) on each load. Possible values: `CARRIER_REP` — rep who gets commission credit for the load, `CARRIER_TEAM` — team responsible for carrier-facing operations and relationships, `OPERATIONS_REP` — manages day-to-day operations on the load, `OPERATIONS_MANAGER` — brokerage-side manager or supervisor, `ACCOUNT_MANAGER` — manages the customer relationship, `CUSTOMER_REP` — sales rep to the customer, `CUSTOMER_TEAM` — part of the broader customer team, `BOOKED_BY` — party who booked the load, `AP_REP` — manages invoices and payments, `AFTER_HOURS_REP` — contact available outside of regular business hours. - `customer` Customer - `customerId` string - `name` string, required - `carrierPaymentStatuses` CarrierPaymentStatus[]: Per-carrier payment status entries for this load. Each entry represents the payment outcome for one carrier on the load (e.g., TONU + linehaul on a co-brokered load yields two entries). Sending this field replaces any prior set of statuses for the load. - `carrierId` string, required: Brokerage-side external carrier identifier (the `externalId` used elsewhere in the API). Resolved against `(brokerageKey, carrierId)`, which is unique. Required on every entry. - `status` 'PAID' | 'SCHEDULED' | 'OTHER', required: Explicit payment status. `OTHER` is a catch-all for states not yet promoted to first-class enum values (e.g., PARTIAL, APPROVED, DISPUTED, FAILED); additional values may be added in a backward-compatible way. - `scheduledPaymentDate` string, date: Scheduled payment date (YYYY-MM-DD, UTC). - `actualPaymentDate` string, date: Actual payment date (YYYY-MM-DD, UTC). - `paymentMethod` 'ACH' | 'CHECK': Payment method used. - `paymentReferenceNumbers` string[]: Broker-side transaction or confirmation IDs associated with the payment (e.g., TriumphPay confirmation IDs). A list supports split payments and multiple confirmation IDs per payment. ## Response `204` Load created successfully ## Other responses - `400`: Malformed JSON request body, or a bad request rejected while processing the load. Field-level validation failures are returned as `422` instead. - `401`: Unauthorized - `422`: Validation failed. `errorCode` is `VALIDATION_ERROR` and `details` is keyed by the field path that failed, using the same indexes as the arrays you sent. Status-based failures — such as a route stop missing `expectedArrivalWindowStart` on a load at `CUSTOMER_CONFIRMED` — are reported here. --- [API](https://skmtc.dev/goaugment/apis/augment-api.md) - [All operations](https://skmtc.dev/goaugment/apis/augment-api/llms.txt) - [OpenAPI document](https://skmtc.dev/goaugment/apis/augment-api/revisions/b61097634d79?raw)